Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): harden the bridge against loss and unify source undo (#2962)

Nick Gomezdd778e7e7120
diff --git a/.changeset/bridge-loss-hardening.md b/.changeset/bridge-loss-hardening.md
new file mode 100644
index 000000000..9d9e9a214
--- /dev/null
+++ b/.changeset/bridge-loss-hardening.md
@@ -0,0 +1,11 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Edits typed while something else is rewriting the same document no longer disappear. The bridge between the visual editor and the raw markdown behind it gained four safety nets, all default-on: a defer guard that holds back a rebuild which would overwrite a keystroke that has not propagated yet, a pre-drain flush that pushes a pending non-overlapping keystroke into the document before an agent write or undo rebuilds it, a loss detector that spots content dropped at the reconciliation boundary, and a fixed-point backstop that freezes a rebuild loop which oscillates instead of settling. The practical effect: typing through an agent write, a `git pull` that lands on the open document, or a same-second edit from a second window is far less likely to cost you a line.
+
+- Anything a safety net cannot save in place is written to a recovery checkpoint, and those checkpoints now appear in the Timeline as ordinary "Recovered content" versions you can preview and restore like any older version. Before this release the same checkpoints were written but reachable through no API and invisible in the UI, so rescued content was effectively lost anyway.
+- Undo in source mode is now a single origin-aware system. Cmd/Ctrl-Z undoes only what you typed, never a collaborator's or an agent's write. Previously CodeMirror's own history could revert content you never wrote.
+- Unsynced work survives more of the browser lifecycle: a tab flushes to the server when you switch away and resyncs when you come back, edits captured during a server-instance recycle land in a durable IndexedDB outbox so a tab crash mid-recycle no longer drops them, and a worker-homed presence heartbeat keeps a backgrounded tab from being pruned as offline by its peers. In the desktop app, a window holding unsynced work opts out of Chromium's background throttling until it is clean.
+- New project config leaves, each a kill-switch defaulting to on: `bridge.deferGuard.enabled`, `bridge.preDrain.enabled`, `bridge.lossDetector.enabled`, `bridge.fixedPoint.enabled`, `bridge.flushOnHide.enabled`, `bridge.backgroundThrottle.enabled`. Turn one off only to isolate a suspected regression.
+- New `lossCapture.enabled` and `lossCapture.maxBytes` config leaves plus a local event ring at `.ok/local/loss-capture/` (roughly 12 MB before it rotates). It records which safety net fired, on which document, and when, and it is content-free by schema: a byte length and a digest, never document text. Nothing leaves your machine until you run `ok diagnose bundle`; set `lossCapture.enabled: false` for a sensitive workspace.
diff --git a/.changeset/diagnose-bundle-consent-posture.md b/.changeset/diagnose-bundle-consent-posture.md
new file mode 100644
index 000000000..342607d6a
--- /dev/null
+++ b/.changeset/diagnose-bundle-consent-posture.md
@@ -0,0 +1,16 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+`ok diagnose bundle` now redacts by default, and the y/N prompt states plainly what leaves your machine before it writes anything.
+
+- **Credentials are scrubbed on every bundle.** GitHub PATs, AWS access keys, Anthropic and OpenAI keys, bearer tokens, JWTs, and URL-embedded credentials are replaced with `[REDACTED-*]` placeholders, and macOS/Linux home-directory paths are anonymized to `~/` (the path hierarchy below the home directory is preserved). `ok diagnose bundle` never ran this scrub before, so bundles produced by earlier versions could carry a live token; `ok bug-report` and the in-app bug report already did.
+- **The content directory path is masked** as `<CONTENT_DIR>`, so a shared bundle does not leak your home-directory layout.
+- **The flag is now `--no-redact`**, an explicit opt-out that writes a raw bundle for you to inspect locally: no credential scrubbing and no path masking. `--redact` is still accepted and is now simply the default, so existing scripts and muscle memory keep working.
+- **Document names ship in cleartext.** The old opt-in `--redact` pass hashed them to `doc:<8hex>` and wrote a `<bundle>.docnames.json` inverse-map sidecar next to the zip; both are gone. Legible document names are what make a bundle diagnosable, so the tradeoff is now an informed one rather than a silent one: the consent summary says "in cleartext" next to the count, and the manifest's `redaction` block no longer carries `docNameMapSidecar` or `docNameCollisions`.
+- **The consent summary is now itemized** by what actually leaves the machine: document names, whether the content directory path is masked, and whether credentials were scrubbed (with the line count). Under `--no-redact` it says so in as many words.
+- **Bundles carry the content-loss ring** as `state/loss-current.jsonl` and `state/loss-prev.jsonl` when it exists, so a "my edit vanished" report arrives with the evidence attached. The ring is content-free by schema.
+
+- **The desktop app now scrubs captured renderer console output before writing it to `~/.ok/logs`.** Console capture is on by default, and a credential printed to the console previously landed verbatim in that log file for its 7-day retention — the keyed-field redaction in front of the log never inspected the message text. The same scrub also masks `/Users/<name>/` paths to `~/` there, matching what the web build already did on its way to the server log.
+
+The in-app bug report and `ok bug-report` always redact. `ok diagnose bundle` is the only surface with an opt-out.
diff --git a/packages/app/package.json b/packages/app/package.json
index 32ea56ecf..355185574 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -26,7 +26,7 @@
"measure:fuzz": "bash scripts/measure-fuzz.sh",
"measure:stress": "bash scripts/measure-stress.sh",
"perf:compare": "bash scripts/perf-compare.sh",
- "test:e2e": "playwright test tests/stress/ux-interactions.e2e.ts tests/stress/file-tree-create.e2e.ts tests/stress/file-tree-drag-to-root.e2e.ts tests/stress/file-tree-deselect-to-root.e2e.ts tests/stress/create-then-rename-editable.e2e.ts tests/stress/find-replace.e2e.ts tests/stress/editor-tabs.e2e.ts tests/stress/crdt-stress.e2e.ts tests/stress/slash-command.e2e.ts tests/stress/paste-fidelity.e2e.ts tests/stress/fr-7a-disconnect-source-mode.e2e.ts tests/stress/docs-open.e2e.ts tests/stress/frozen-table-headers.e2e.ts tests/stress/asset-embed.e2e.ts tests/stress/asset-embed-advanced.e2e.ts tests/stress/asset-click-dispatch.e2e.ts tests/stress/handoff.e2e.ts tests/stress/multi-agent-presence.e2e.ts tests/stress/editor-mode-persistence.e2e.ts tests/stress/lint-config-toggle.e2e.ts tests/stress/sidebar-search-pill.e2e.ts tests/stress/navigation-history.e2e.ts tests/stress/command-palette-semantic.e2e.ts tests/stress/agent-activity-panel.e2e.ts tests/stress/drop-pipeline-auto-open.e2e.ts tests/stress/command-palette-flicker.e2e.ts tests/stress/cm6-list-hanging-indent.e2e.ts tests/stress/ng7-rapid-nav-coherence.e2e.ts tests/stress/reveal-on-activate.e2e.ts tests/stress/selection-indicator.e2e.ts tests/stress/new-file-cross-doc-bleed.e2e.ts tests/stress/editor-mode-flip-cross-doc-bleed.e2e.ts tests/stress/editor-area-viewport-resize.e2e.ts tests/stress/qa-sidebar-responsive.e2e.ts tests/stress/prd-6955-reassertion-repro.e2e.ts tests/stress/prd-6955-reassertion-wedge.e2e.ts tests/stress/prd-6914-repro.e2e.ts tests/stress/showall-lazy-tree.e2e.ts tests/stress/tabs-component-strip.e2e.ts tests/stress/source-find-scroll.e2e.ts tests/stress/harness-app-warmth.e2e.ts tests/stress/qa-canary-authoring-both-modes.e2e.ts tests/stress/qa-canary-live-typing.e2e.ts tests/stress/keystroke-cadence-danger-space.e2e.ts tests/stress/jsx-unregistered-backspace-delete.e2e.ts tests/stress/jsx-unregistered-ime-concurrent.e2e.ts tests/stress/jsx-backspace-delete.e2e.ts tests/stress/link-authoring-bytes.e2e.ts tests/stress/link-authoring-apex.e2e.ts tests/stress/command-palette-parity.e2e.ts tests/stress/settings-search.e2e.ts tests/stress/chip-popover-positioning.e2e.ts tests/stress/docs-open-scroll-restore.e2e.ts tests/stress/file-tree-decoration-chip-strip-repro.e2e.ts tests/stress/grip-click-nodeselect.e2e.ts tests/stress/jsx-halo-semantics.e2e.ts tests/stress/jsx-image-body-click.e2e.ts tests/stress/jsx-prop-panel-placeholder.e2e.ts tests/stress/jsx-range-encompass-halo.e2e.ts tests/stress/jsx-wildcard-convert.e2e.ts tests/stress/markdown-lint.e2e.ts tests/stress/unified-problems.e2e.ts tests/stress/mid-type-recovery.e2e.ts tests/stress/observer-a-multi-client.e2e.ts tests/stress/outline-toolbar-occlusion.e2e.ts tests/stress/quiet-tree-hidden-doc.e2e.ts tests/stress/raw-mdx-fallback-onblur-upgrade.e2e.ts tests/stress/rename-noext-probe.e2e.ts tests/stress/show-ok-folders.e2e.ts tests/stress/source-polish.e2e.ts tests/stress/warm-skeleton-scroll-restore.e2e.ts tests/stress/props-toggle-scroll-preserve.e2e.ts tests/stress/yjs-no-dual-import.e2e.ts tests/stress/slash-command-auto-open.e2e.ts tests/stress/graph-panel-surfaces.e2e.ts tests/stress/clipboard-relative-url-source-fallback.e2e.ts tests/stress/asset-embed-real-fidelity.e2e.ts tests/stress/prop-upload.e2e.ts tests/stress/rename-content-preservation.e2e.ts tests/stress/rename-consolidation.e2e.ts tests/stress/outline-navigation.e2e.ts tests/stress/prd-7627-default-swatch.e2e.ts tests/stress/clipboard-dollar-math-source-fallback.e2e.ts",
+ "test:e2e": "playwright test tests/stress/ux-interactions.e2e.ts tests/stress/file-tree-create.e2e.ts tests/stress/file-tree-drag-to-root.e2e.ts tests/stress/file-tree-deselect-to-root.e2e.ts tests/stress/create-then-rename-editable.e2e.ts tests/stress/find-replace.e2e.ts tests/stress/editor-tabs.e2e.ts tests/stress/crdt-stress.e2e.ts tests/stress/slash-command.e2e.ts tests/stress/paste-fidelity.e2e.ts tests/stress/fr-7a-disconnect-source-mode.e2e.ts tests/stress/docs-open.e2e.ts tests/stress/frozen-table-headers.e2e.ts tests/stress/asset-embed.e2e.ts tests/stress/asset-embed-advanced.e2e.ts tests/stress/asset-click-dispatch.e2e.ts tests/stress/handoff.e2e.ts tests/stress/multi-agent-presence.e2e.ts tests/stress/editor-mode-persistence.e2e.ts tests/stress/lint-config-toggle.e2e.ts tests/stress/sidebar-search-pill.e2e.ts tests/stress/navigation-history.e2e.ts tests/stress/command-palette-semantic.e2e.ts tests/stress/agent-activity-panel.e2e.ts tests/stress/drop-pipeline-auto-open.e2e.ts tests/stress/command-palette-flicker.e2e.ts tests/stress/cm6-list-hanging-indent.e2e.ts tests/stress/ng7-rapid-nav-coherence.e2e.ts tests/stress/reveal-on-activate.e2e.ts tests/stress/selection-indicator.e2e.ts tests/stress/new-file-cross-doc-bleed.e2e.ts tests/stress/editor-mode-flip-cross-doc-bleed.e2e.ts tests/stress/editor-area-viewport-resize.e2e.ts tests/stress/qa-sidebar-responsive.e2e.ts tests/stress/prd-6955-reassertion-repro.e2e.ts tests/stress/prd-6955-reassertion-wedge.e2e.ts tests/stress/prd-6914-repro.e2e.ts tests/stress/showall-lazy-tree.e2e.ts tests/stress/tabs-component-strip.e2e.ts tests/stress/source-find-scroll.e2e.ts tests/stress/harness-app-warmth.e2e.ts tests/stress/qa-canary-authoring-both-modes.e2e.ts tests/stress/qa-canary-live-typing.e2e.ts tests/stress/keystroke-cadence-danger-space.e2e.ts tests/stress/jsx-unregistered-backspace-delete.e2e.ts tests/stress/jsx-unregistered-ime-concurrent.e2e.ts tests/stress/jsx-backspace-delete.e2e.ts tests/stress/link-authoring-bytes.e2e.ts tests/stress/link-authoring-apex.e2e.ts tests/stress/command-palette-parity.e2e.ts tests/stress/settings-search.e2e.ts tests/stress/chip-popover-positioning.e2e.ts tests/stress/docs-open-scroll-restore.e2e.ts tests/stress/file-tree-decoration-chip-strip-repro.e2e.ts tests/stress/grip-click-nodeselect.e2e.ts tests/stress/jsx-halo-semantics.e2e.ts tests/stress/jsx-image-body-click.e2e.ts tests/stress/jsx-prop-panel-placeholder.e2e.ts tests/stress/jsx-range-encompass-halo.e2e.ts tests/stress/jsx-wildcard-convert.e2e.ts tests/stress/markdown-lint.e2e.ts tests/stress/unified-problems.e2e.ts tests/stress/mid-type-recovery.e2e.ts tests/stress/observer-a-multi-client.e2e.ts tests/stress/outline-toolbar-occlusion.e2e.ts tests/stress/quiet-tree-hidden-doc.e2e.ts tests/stress/raw-mdx-fallback-onblur-upgrade.e2e.ts tests/stress/rename-noext-probe.e2e.ts tests/stress/show-ok-folders.e2e.ts tests/stress/source-polish.e2e.ts tests/stress/warm-skeleton-scroll-restore.e2e.ts tests/stress/props-toggle-scroll-preserve.e2e.ts tests/stress/yjs-no-dual-import.e2e.ts tests/stress/slash-command-auto-open.e2e.ts tests/stress/graph-panel-surfaces.e2e.ts tests/stress/clipboard-relative-url-source-fallback.e2e.ts tests/stress/asset-embed-real-fidelity.e2e.ts tests/stress/prop-upload.e2e.ts tests/stress/rename-content-preservation.e2e.ts tests/stress/rename-consolidation.e2e.ts tests/stress/outline-navigation.e2e.ts tests/stress/prd-7627-default-swatch.e2e.ts tests/stress/clipboard-dollar-math-source-fallback.e2e.ts tests/stress/source-mode-undo-keymap.e2e.ts tests/stress/timeline-recovered-restore.e2e.ts",
"test:e2e:install-browsers": "playwright install chromium webkit firefox",
"test:visual": "playwright test --config playwright.visual.config.ts",
"test:visual:update": "playwright test --config playwright.visual.config.ts --update-snapshots",
@@ -52,7 +52,7 @@
{
"name": "all JS chunks combined (gzipped)",
"path": "dist/assets/*.js",
- "limit": "3.6 MB",
+ "limit": "3.61 MB",
"gzip": true,
"running": false
},
diff --git a/packages/app/src/App.dom.test.tsx b/packages/app/src/App.dom.test.tsx
index 61d53c4e7..7e216c5ee 100644
--- a/packages/app/src/App.dom.test.tsx
+++ b/packages/app/src/App.dom.test.tsx
@@ -141,6 +141,18 @@ vi.doMock('@/components/SystemDocSubscriber', () => ({
SystemDocSubscriber: () => <div data-testid="system-doc-subscriber" />,
}));
+// Side-effect-only lifecycle reporters that mount null and drive the provider
+// pool / desktop bridge (flush-on-hide; background-throttle). This chrome-focused
+// test doesn't exercise them and its DocumentContext mock omits `getPool`, so
+// stub them like the other side surfaces above — their behavior is covered by
+// their own suites (install-editor-lifecycle-flush, install-background-throttle-reporter).
+vi.doMock('@/editor/EditorLifecycleFlush', () => ({
+ EditorLifecycleFlush: () => null,
+}));
+vi.doMock('@/editor/BackgroundThrottleReporter', () => ({
+ BackgroundThrottleReporter: () => null,
+}));
+
vi.doMock('@/components/McpConsentDialog', () => ({
McpConsentDialog: () => <div data-testid="mcp-consent-dialog" />,
}));
diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx
index 020b54145..86c1aed9d 100644
--- a/packages/app/src/App.tsx
+++ b/packages/app/src/App.tsx
@@ -28,11 +28,13 @@ import { ReportBugMenuTrigger } from '@/components/ReportBugMenuTrigger';
import { SystemDocSubscriber } from '@/components/SystemDocSubscriber';
import { SidebarInset, SidebarProvider } from '@/components/ui/sidebar';
import { ValidationFreshness } from '@/components/ValidationFreshness';
+import { BackgroundThrottleReporter } from '@/editor/BackgroundThrottleReporter';
import {
DocumentProvider,
useDocumentContext,
useDocumentTransition,
} from '@/editor/DocumentContext';
+import { EditorLifecycleFlush } from '@/editor/EditorLifecycleFlush';
import { parseEditorTabId } from '@/editor/editor-tabs';
import { useInstalledClis } from '@/hooks/use-installed-clis';
import { useReconcileSkillTabs } from '@/hooks/use-reconcile-skill-tabs';
@@ -480,7 +482,13 @@ function ConfigProviderHost({ children }: { children: ReactNode }) {
// self-gates to non-desktop. Mounted here because this host already owns the
// single app-root `collabUrl` read.
useServerKeepalive(collabUrl);
- return <ConfigProvider collabUrl={collabUrl}>{children}</ConfigProvider>;
+ return (
+ <ConfigProvider collabUrl={collabUrl}>
+ <EditorLifecycleFlush />
+ <BackgroundThrottleReporter />
+ {children}
+ </ConfigProvider>
+ );
}
export function App() {
diff --git a/packages/app/src/components/ReportBugDialog.dom.test.tsx b/packages/app/src/components/ReportBugDialog.dom.test.tsx
index 99f670f94..bcbaac2dc 100644
--- a/packages/app/src/components/ReportBugDialog.dom.test.tsx
+++ b/packages/app/src/components/ReportBugDialog.dom.test.tsx
@@ -251,7 +251,7 @@ describe('ReportBugDialog', () => {
expect(checkbox.hasAttribute('disabled')).toBe(false);
expect(
screen.getByText(
- 'Adds telemetry, server state, and runtime info when available. Document names are anonymized.',
+ 'Adds telemetry, server state, and runtime info when available. Credentials are always removed; document names, if included, appear in cleartext (not redacted).',
),
).not.toBeNull();
diff --git a/packages/app/src/components/ReportBugDialogBody.tsx b/packages/app/src/components/ReportBugDialogBody.tsx
index 2a0ad14e6..7107045b9 100644
--- a/packages/app/src/components/ReportBugDialogBody.tsx
+++ b/packages/app/src/components/ReportBugDialogBody.tsx
@@ -579,8 +579,9 @@ function ReportBugDialog({
</label>
<p id={detailedHintId} className="text-1sm text-muted-foreground">
<Trans>
- Adds telemetry, server state, and runtime info when available. Document
- names are anonymized.
+ Adds telemetry, server state, and runtime info when available. Credentials
+ are always removed; document names, if included, appear in cleartext (not
+ redacted).
</Trans>
</p>
</div>
diff --git a/packages/app/src/components/TimelineDiffPane.dom.test.tsx b/packages/app/src/components/TimelineDiffPane.dom.test.tsx
new file mode 100644
index 000000000..2731bcd3a
--- /dev/null
+++ b/packages/app/src/components/TimelineDiffPane.dom.test.tsx
@@ -0,0 +1,304 @@
+/**
+ * RTL mount test: the full-pane version diff's OWN Restore control — the
+ * second restore surface, reached by opening a Timeline row's diff rather than
+ * clicking the row's inline restore icon.
+ *
+ * It repeats the whole journey the Timeline row owns, on its own state: the
+ * confirm gate keyed on `laterEdits`, the POST /api/rollback for the viewed
+ * version's sha (never the parent's), the Cancel and Escape dismissals, and the
+ * dismissal of the pane itself once the restore lands.
+ *
+ * Escape is load-bearing twice over here: the pane binds its own window-level
+ * Escape-to-close, so Escape while the confirm is up must dismiss the dialog
+ * ONLY — dropping the whole pane would discard the user's place in the diff on
+ * a keystroke they aimed at the dialog.
+ *
+ * Stubbed seams: `fetch` (the /api/history version loads plus the rollback
+ * endpoint) and the document context the diff hook reads its live-text provider
+ * from — the pane diffs vs-parent, so both sides are historical fetches and the
+ * provider is never consulted. Everything else is the real component.
+ *
+ * Invocation: `pnpm run test:dom` from `packages/app/`.
+ */
+
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+// Hoisted above every import: the SUT's transitive `useTheme` and its document
+// context bind to these stubs rather than the real providers.
+vi.mock('next-themes', () => ({
+ useTheme: () => ({ resolvedTheme: 'light' }),
+}));
+vi.mock('@/editor/DocumentContext', () => ({
+ useDocumentContext: () => ({ activeProvider: null, activeDocName: 'notes' }),
+}));
+
+import { TooltipProvider } from '@/components/ui/tooltip';
+import {
+ closeTimelineDiff,
+ openTimelineDiff,
+ type TimelineDiffView,
+ useTimelineDiffView,
+} from '@/lib/timeline-diff-store';
+
+const { TimelineDiffPane } = await import('./TimelineDiffPane');
+
+const VERSION_SHA = 'c'.repeat(40);
+const PARENT_SHA = 'p'.repeat(40);
+const PARENT_BODY = 'first line\nsecond line\n';
+const VERSION_BODY = 'first line\nsecond line rewritten\n';
+
+function viewFor(laterEdits: number): TimelineDiffView {
+ return {
+ docName: 'notes',
+ sha: VERSION_SHA,
+ parentSha: PARENT_SHA,
+ laterEdits,
+ authorName: 'Alice',
+ relativeTime: '2 hours ago',
+ absoluteTime: '2026-04-17 00:00',
+ };
+}
+
+interface RollbackCall {
+ body: unknown;
+ signal: AbortSignal | null | undefined;
+}
+
+interface FetchHarness {
+ /** Every POST /api/rollback the pane issued, in order. */
+ rollbacks: RollbackCall[];
+ /** Resolve a held rollback response (no-op when none is held). */
+ release: () => void;
+}
+
+/**
+ * Serve both historical version loads and record every rollback.
+ * `holdRollback` leaves the rollback response pending so a test can inspect the
+ * pane while the request is genuinely in flight.
+ */
+function mockDiffFetch({ holdRollback = false }: { holdRollback?: boolean } = {}): FetchHarness {
+ const rollbacks: RollbackCall[] = [];
+ let resolveHeld: ((res: Response) => void) | undefined;
+
+ globalThis.fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+ const url = typeof input === 'string' ? input : input.toString();
+ if (url.includes(`/api/history/${VERSION_SHA}`)) {
+ return Promise.resolve(
+ new Response(JSON.stringify({ content: VERSION_BODY }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+ }
+ if (url.includes(`/api/history/${PARENT_SHA}`)) {
+ return Promise.resolve(
+ new Response(JSON.stringify({ content: PARENT_BODY }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+ }
+ if (url.includes('/api/rollback')) {
+ rollbacks.push({
+ body: init?.body ? JSON.parse(init.body as string) : null,
+ signal: init?.signal,
+ });
+ if (holdRollback) {
+ return new Promise<Response>((resolve) => {
+ resolveHeld = resolve;
+ });
+ }
+ return Promise.resolve(new Response(null, { status: 200 }));
+ }
+ return Promise.resolve(new Response(null, { status: 404 }));
+ }) as never;
+
+ return {
+ rollbacks,
+ release: () => resolveHeld?.(new Response(null, { status: 200 })),
+ };
+}
+
+/**
+ * Reports whether the diff overlay is still claimed by the store — the same
+ * signal EditorArea paints the pane from, so it is how a user would perceive
+ * "the diff is still open".
+ */
+function DiffStoreProbe() {
+ const view = useTimelineDiffView();
+ return <span data-testid="diff-store-state">{view === null ? 'closed' : 'open'}</span>;
+}
+
+function renderPane(laterEdits: number) {
+ const view = viewFor(laterEdits);
+ openTimelineDiff(view);
+ return render(
+ <TooltipProvider>
+ <DiffStoreProbe />
+ <TimelineDiffPane view={view} isPanelCollapsed={false} onTogglePanel={() => {}} />
+ </TooltipProvider>,
+ );
+}
+
+/** Wait for both historical loads to land so the diff body is painted. */
+async function waitForDiffBody() {
+ await waitFor(() => expect(screen.queryByText('Loading diff')).toBeNull());
+}
+
+function restoreButton(): HTMLButtonElement {
+ return screen.getByTestId('timeline-diff-restore') as HTMLButtonElement;
+}
+
+function storeState(): string {
+ return screen.getByTestId('diff-store-state').textContent ?? '';
+}
+
+let originalFetch: typeof globalThis.fetch;
+
+beforeEach(() => {
+ originalFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+ globalThis.fetch = originalFetch;
+ closeTimelineDiff();
+ cleanup();
+});
+
+describe('TimelineDiffPane — its own Restore reaches the rollback', () => {
+ test('confirming restores the VIEWED version, not its diff baseline', async () => {
+ const { rollbacks } = mockDiffFetch();
+
+ renderPane(2);
+ await waitForDiffBody();
+
+ fireEvent.click(restoreButton());
+
+ // The confirm gates the restore — nothing has left yet.
+ const confirm = await screen.findByTestId('timeline-diff-restore-confirm');
+ expect(rollbacks).toHaveLength(0);
+
+ fireEvent.click(confirm);
+
+ await waitFor(() => expect(rollbacks).toHaveLength(1));
+ // The pane holds two shas; the rollback target is the one being viewed.
+ expect(rollbacks[0].body).toEqual({ docName: 'notes', commitSha: VERSION_SHA });
+ // A landed restore dismisses the diff overlay — the user is returned to the
+ // editor showing the restored document.
+ await waitFor(() => expect(storeState()).toBe('closed'));
+ });
+
+ test('the newest version restores without a confirm; an older one always raises it', async () => {
+ // Held rollback: both halves are asserted while the request state is still
+ // observable, rather than after a resolution has torn the dialog down.
+ const zeroLater = mockDiffFetch({ holdRollback: true });
+ renderPane(0);
+ await waitForDiffBody();
+
+ fireEvent.click(restoreButton());
+ // Nothing to roll back, so the request leaves synchronously on click with
+ // no dialog in between.
+ expect(zeroLater.rollbacks).toHaveLength(1);
+ expect(zeroLater.rollbacks[0].body).toEqual({ docName: 'notes', commitSha: VERSION_SHA });
+ expect(screen.queryByTestId('timeline-diff-restore-confirm')).toBeNull();
+
+ zeroLater.release();
+ await waitFor(() => expect(storeState()).toBe('closed'));
+ cleanup();
+
+ const withLater = mockDiffFetch({ holdRollback: true });
+ renderPane(3);
+ await waitForDiffBody();
+
+ fireEvent.click(restoreButton());
+ expect(await screen.findByTestId('timeline-diff-restore-confirm')).toBeTruthy();
+ expect(withLater.rollbacks).toHaveLength(0);
+ });
+});
+
+describe('TimelineDiffPane — dismissing its confirm leaves the document untouched', () => {
+ test('Cancel closes the dialog, issues no rollback, and keeps the diff open', async () => {
+ const { rollbacks } = mockDiffFetch();
+
+ renderPane(2);
+ await waitForDiffBody();
+ fireEvent.click(restoreButton());
+ await screen.findByTestId('timeline-diff-restore-confirm');
+
+ fireEvent.click(screen.getByTestId('timeline-diff-restore-cancel'));
+
+ await waitFor(() => expect(screen.queryByTestId('timeline-diff-restore-confirm')).toBeNull());
+ expect(rollbacks).toHaveLength(0);
+ expect(storeState()).toBe('open');
+ expect(restoreButton().disabled).toBe(false);
+ });
+
+ test('Escape closes the dialog only — the pane keeps its place, and nothing rolls back', async () => {
+ const { rollbacks } = mockDiffFetch();
+
+ renderPane(2);
+ await waitForDiffBody();
+ fireEvent.click(restoreButton());
+ await screen.findByTestId('timeline-diff-restore-confirm');
+
+ await userEvent.keyboard('{Escape}');
+
+ await waitFor(() => expect(screen.queryByTestId('timeline-diff-restore-confirm')).toBeNull());
+ expect(rollbacks).toHaveLength(0);
+ // The pane's own Escape-to-close must not have fired underneath the dialog.
+ expect(storeState()).toBe('open');
+ expect(screen.getByTestId('timeline-diff-pane')).toBeTruthy();
+ expect(restoreButton().disabled).toBe(false);
+ });
+});
+
+describe('TimelineDiffPane — an unresolved restore leaves no half-applied UI', () => {
+ test('while the request hangs the pane stays whole, and no second rollback can be issued', async () => {
+ const { rollbacks } = mockDiffFetch({ holdRollback: true });
+
+ renderPane(2);
+ await waitForDiffBody();
+ fireEvent.click(restoreButton());
+ const confirm = (await screen.findByTestId(
+ 'timeline-diff-restore-confirm',
+ )) as HTMLButtonElement;
+
+ fireEvent.click(confirm);
+ await waitFor(() => expect(rollbacks).toHaveLength(1));
+
+ // The pane has not torn itself down or claimed success on a request that
+ // never answered: the diff is still painted, the overlay still claimed.
+ expect(screen.getByTestId('timeline-diff-pane')).toBeTruthy();
+ expect(screen.getByText('notes')).toBeTruthy();
+ expect(storeState()).toBe('open');
+
+ // Both restore affordances are latched while the request is outstanding, so
+ // an impatient second click cannot stack a duplicate rollback.
+ expect(confirm.disabled).toBe(true);
+ expect(restoreButton().disabled).toBe(true);
+ fireEvent.click(confirm);
+ fireEvent.click(restoreButton());
+ expect(rollbacks).toHaveLength(1);
+ });
+
+ test('closing the pane mid-flight abandons the wait without a second request', async () => {
+ const { rollbacks, release } = mockDiffFetch({ holdRollback: true });
+
+ const { unmount } = renderPane(2);
+ await waitForDiffBody();
+ fireEvent.click(restoreButton());
+ fireEvent.click(await screen.findByTestId('timeline-diff-restore-confirm'));
+ await waitFor(() => expect(rollbacks).toHaveLength(1));
+
+ unmount();
+
+ // The pane withdraws from the in-flight request rather than leaving a
+ // handler pointed at a disposed tree.
+ expect(rollbacks[0].signal?.aborted).toBe(true);
+ // A late response cannot resurrect the flow or issue anything further.
+ release();
+ await waitFor(() => expect(rollbacks).toHaveLength(1));
+ });
+});
diff --git a/packages/app/src/components/TimelinePanel.dom.test.tsx b/packages/app/src/components/TimelinePanel.dom.test.tsx
index d4039f27e..72c5046e4 100644
--- a/packages/app/src/components/TimelinePanel.dom.test.tsx
+++ b/packages/app/src/components/TimelinePanel.dom.test.tsx
@@ -1,18 +1,21 @@
/**
- * RTL mount test: the Timeline surfaces only actor/system commits.
+ * RTL mount test: the Timeline surfaces actor/system commits plus surfaced
+ * rescue checkpoints.
*
- * Pins two user-visible contracts from the "timeline shows only auto-commits"
- * change: (1) checkpoint rows are filtered out of the panel — they are
- * background-cleanup artifacts now, not user history; and (2) there is no
- * Save Version control in the panel header. This mount test locks the
+ * Pins the user-visible contracts: (1) actor/system rows render; (2) a
+ * recovered-content rescue checkpoint (a registry-`surfaced` kind) renders as
+ * an ordinary "Recovered content" version with a restore control; (3) routine
+ * checkpoints stay out — registry-`hidden` kinds (auto-consolidation) and
+ * null-kind Save-Version / cleanup rows; and (4) there is no Save Version
+ * control in the panel header. This mount test locks the registry-driven
* filtering + header contract without a browser (and without a shadow repo).
- * The diff/restore flow (redesigned into the TimelineDiffPane overlay in #2607)
- * has no browser-tier coverage yet.
+ * The click-restore journey has browser-tier coverage in
+ * `tests/stress/timeline-recovered-restore.e2e.ts`.
*
* Invocation: `pnpm run test:dom` from `packages/app/`.
*/
-import { cleanup, render, screen, waitFor } from '@testing-library/react';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
// `vi.mock` is hoisted above every import, so `next-themes` resolves to this
@@ -22,7 +25,12 @@ vi.mock('next-themes', () => ({
useTheme: () => ({ resolvedTheme: 'light' }),
}));
-import type { TimelineEntry } from '@inkeep/open-knowledge-core';
+import {
+ CHECKPOINT_KINDS,
+ isSurfacedCheckpointKind,
+ type ParsedCheckpoint,
+ type TimelineEntry,
+} from '@inkeep/open-knowledge-core';
import { TooltipProvider } from '@/components/ui/tooltip';
// Import the component AFTER the next-themes mock registers so its transitive
@@ -68,6 +76,71 @@ function upstreamEntry(sha: string): TimelineEntry {
};
}
+/** A silent rescue checkpoint the shared kind registry marks `surfaced`. */
+function recoveredCheckpointEntry(sha: string, checkpoint: ParsedCheckpoint): TimelineEntry {
+ return {
+ sha,
+ timestamp: '2026-04-17T00:00:00Z',
+ author: 'openknowledge',
+ authorEmail: '[email protected]',
+ type: 'checkpoint',
+ // The raw checkpoint subject carries an internal, timestamped label; the UI
+ // must never render it — it shows the "Recovered content" framing instead.
+ message: 'checkpoint: Before concurrent merge @ 2026-05-05T12:00:00Z',
+ contributors: [],
+ checkpoint,
+ };
+}
+
+const BRIDGE_MERGE_LOSS: ParsedCheckpoint = {
+ kind: 'bridge-merge-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { lostSubstrings: ['the keystroke'] },
+};
+const SURFACED_KINDS: ParsedCheckpoint[] = [
+ BRIDGE_MERGE_LOSS,
+ { kind: 'producer-guard-loss', docName: 'notes', size: 12, metadata: { construct: 'paragraph' } },
+ {
+ kind: 'observer-a-duplication',
+ docName: 'notes',
+ size: 12,
+ metadata: { duplicatedLineCount: 1 },
+ },
+ {
+ kind: 'external-change-rescue',
+ docName: 'notes',
+ size: 12,
+ metadata: { incomingDiskSha: 'abc123' },
+ },
+ { kind: 'defer-exhaustion-loss', docName: 'notes', size: 12, metadata: { deferCount: 9 } },
+ {
+ kind: 'bridge-derive-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { lostSubstrings: ['the keystroke'] },
+ },
+ {
+ kind: 'observer-a-apply-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { lostSubstrings: ['the keystroke'] },
+ },
+ { kind: 'bridge-backstop-trip', docName: 'notes', size: 12, metadata: { rounds: 8 } },
+ {
+ kind: 'persistence-reconcile-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { atRiskLines: 1, witnessAvailable: true },
+ },
+];
+const AUTO_CONSOLIDATION: ParsedCheckpoint = {
+ kind: 'auto-consolidation',
+ docName: 'notes',
+ size: 12,
+ metadata: { foldedRefs: 3, trigger: 'ttl' },
+};
+
let originalFetch: typeof globalThis.fetch;
beforeEach(() => {
@@ -163,3 +236,105 @@ describe('TimelineContent — actor/system commits only', () => {
expect(screen.queryByRole('button', { name: /save version/i })).toBeNull();
});
});
+
+describe('TimelineContent — recovered-content checkpoints', () => {
+ test('a surfaced rescue checkpoint renders as a Recovered content version with a restore control', async () => {
+ mockHistory([
+ wipEntry('a'.repeat(40), 'Alice'),
+ recoveredCheckpointEntry('c'.repeat(40), BRIDGE_MERGE_LOSS),
+ ]);
+
+ renderTimeline();
+
+ // Both the WIP row and the recovered checkpoint render.
+ await waitFor(() => {
+ expect(screen.getAllByTestId('timeline-entry-open')).toHaveLength(2);
+ });
+ // The recovered row shows the registry-driven framing, never the raw
+ // service author or the internal, timestamped checkpoint subject.
+ expect(screen.getByText('Recovered content')).toBeTruthy();
+ expect(screen.queryByText(/Before concurrent merge/)).toBeNull();
+ expect(screen.queryByText('openknowledge')).toBeNull();
+ // Every row — the recovered one included — carries a restore affordance.
+ expect(screen.getAllByTestId('timeline-entry-restore')).toHaveLength(2);
+ });
+
+ test('the surfaced-kind fixture covers every kind the registry surfaces (fail-closed)', () => {
+ const registrySurfaced = CHECKPOINT_KINDS.filter((k) => isSurfacedCheckpointKind(k)).sort();
+ const covered = [...new Set(SURFACED_KINDS.map((c) => c.kind))].sort();
+ expect(covered).toEqual(registrySurfaced);
+ });
+
+ test('every surfaced rescue kind renders under the same Recovered content label', async () => {
+ for (const checkpoint of SURFACED_KINDS) {
+ mockHistory([recoveredCheckpointEntry('c'.repeat(40), checkpoint)]);
+ renderTimeline();
+ await waitFor(() => {
+ expect(screen.getByText('Recovered content')).toBeTruthy();
+ });
+ // No internal kind name (e.g. "producer-guard-loss") leaks into the UI.
+ expect(screen.queryByText(new RegExp(checkpoint.kind))).toBeNull();
+ cleanup();
+ }
+ });
+
+ test('a registry-hidden kind (auto-consolidation) never renders', async () => {
+ mockHistory([
+ wipEntry('a'.repeat(40), 'Alice'),
+ recoveredCheckpointEntry('c'.repeat(40), AUTO_CONSOLIDATION),
+ ]);
+
+ renderTimeline();
+
+ await waitFor(() => {
+ expect(screen.getAllByTestId('timeline-entry-open')).toHaveLength(1);
+ });
+ expect(screen.getByText('Alice')).toBeTruthy();
+ expect(screen.queryByText('Recovered content')).toBeNull();
+ });
+
+ test('restoring a recovered row (with later edits) confirms, then POSTs /api/rollback for its sha', async () => {
+ const recoveredSha = 'c'.repeat(40);
+ const rollbackBodies: unknown[] = [];
+ // A newer WIP row above the recovered checkpoint gives it laterEdits > 0, so
+ // restore is destructive and must route through the confirm dialog rather
+ // than firing instantly.
+ globalThis.fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+ const url = typeof input === 'string' ? input : input.toString();
+ if (url.includes('/api/history')) {
+ return Promise.resolve(
+ new Response(
+ JSON.stringify({
+ entries: [
+ wipEntry('a'.repeat(40), 'Alice'),
+ recoveredCheckpointEntry(recoveredSha, BRIDGE_MERGE_LOSS),
+ ],
+ }),
+ { status: 200, headers: { 'Content-Type': 'application/json' } },
+ ),
+ );
+ }
+ if (url.includes('/api/rollback')) {
+ rollbackBodies.push(init?.body ? JSON.parse(init.body as string) : null);
+ return Promise.resolve(new Response(null, { status: 200 }));
+ }
+ return Promise.resolve(new Response(null, { status: 404 }));
+ }) as never;
+
+ renderTimeline();
+ await waitFor(() => expect(screen.getByText('Recovered content')).toBeTruthy());
+
+ // The recovered row is second (Alice is newer) → laterEdits > 0.
+ fireEvent.click(screen.getAllByTestId('timeline-entry-restore')[1]);
+
+ // The confirm dialog gates the restore — nothing has been rolled back yet.
+ const confirm = await screen.findByTestId('timeline-entry-restore-confirm');
+ expect(rollbackBodies).toHaveLength(0);
+
+ fireEvent.click(confirm);
+
+ // Confirming issues exactly one rollback for the recovered checkpoint's sha.
+ await waitFor(() => expect(rollbackBodies).toHaveLength(1));
+ expect(rollbackBodies[0]).toEqual({ docName: 'notes', commitSha: recoveredSha });
+ });
+});
diff --git a/packages/app/src/components/TimelinePanel.restore-dismissal.dom.test.tsx b/packages/app/src/components/TimelinePanel.restore-dismissal.dom.test.tsx
new file mode 100644
index 000000000..8aaa556f2
--- /dev/null
+++ b/packages/app/src/components/TimelinePanel.restore-dismissal.dom.test.tsx
@@ -0,0 +1,239 @@
+/**
+ * RTL mount test: the Timeline row's Restore confirm gate — its two dismissal
+ * paths, and the gate's determinism.
+ *
+ * `TimelinePanel.dom.test.tsx` drives the confirm edge (confirm → POST
+ * /api/rollback for the row's sha). This file pins the other three edges of the
+ * same gate: (1) Cancel dismisses and mutates nothing; (2) Escape dismisses and
+ * mutates nothing; (3) the gate is a function of `laterEdits` rather than
+ * chance — a row with newer versions stacked above it MUST raise the dialog
+ * before any request leaves, and the newest row (nothing to roll back) MUST
+ * restore without one.
+ *
+ * The only stubbed seam is `fetch`. Both dismissal assertions are "zero calls
+ * at the network boundary", and the same stub serves the /api/history load that
+ * renders the rows — so a dead stub cannot fake a green.
+ *
+ * Invocation: `pnpm run test:dom` from `packages/app/`.
+ */
+
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+// `vi.mock` is hoisted above every import, so `next-themes` resolves to this
+// stub before the SUT (imported dynamically below) pulls in its transitive
+// `useTheme`.
+vi.mock('next-themes', () => ({
+ useTheme: () => ({ resolvedTheme: 'light' }),
+}));
+
+import type { ParsedCheckpoint, TimelineEntry } from '@inkeep/open-knowledge-core';
+import { TooltipProvider } from '@/components/ui/tooltip';
+
+// Import the component AFTER the next-themes mock registers so its transitive
+// `useTheme` import binds to the stub rather than the real provider.
+const { TimelineContent } = await import('./TimelinePanel');
+
+const NEWER_SHA = 'a'.repeat(40);
+const RECOVERED_SHA = 'c'.repeat(40);
+
+const BRIDGE_MERGE_LOSS: ParsedCheckpoint = {
+ kind: 'bridge-merge-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { lostSubstrings: ['the keystroke'] },
+};
+
+function wipEntry(sha: string, author: string): TimelineEntry {
+ return {
+ sha,
+ timestamp: '2026-04-17T00:00:00Z',
+ author,
+ authorEmail: `${author}@example.test`,
+ type: 'wip',
+ message: `wip: ${author} edit`,
+ contributors: [{ id: author, name: author, docs: ['notes.md'] }],
+ checkpoint: null,
+ };
+}
+
+function recoveredCheckpointEntry(sha: string): TimelineEntry {
+ return {
+ sha,
+ timestamp: '2026-04-17T00:00:00Z',
+ author: 'openknowledge',
+ authorEmail: '[email protected]',
+ type: 'checkpoint',
+ message: 'checkpoint: Before concurrent merge @ 2026-05-05T12:00:00Z',
+ contributors: [],
+ checkpoint: BRIDGE_MERGE_LOSS,
+ };
+}
+
+interface RollbackCall {
+ body: unknown;
+ signal: AbortSignal | null | undefined;
+}
+
+interface FetchHarness {
+ /** Every POST /api/rollback the component issued, in order. */
+ rollbacks: RollbackCall[];
+ /** Resolve a held rollback response (no-op when none is held). */
+ release: () => void;
+}
+
+/**
+ * Serve the timeline's history load and record every rollback. `holdRollback`
+ * leaves the rollback response pending so a test can inspect the UI while the
+ * request is genuinely in flight.
+ */
+function mockTimelineFetch(
+ entries: TimelineEntry[],
+ { holdRollback = false }: { holdRollback?: boolean } = {},
+): FetchHarness {
+ const rollbacks: RollbackCall[] = [];
+ let resolveHeld: ((res: Response) => void) | undefined;
+
+ globalThis.fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+ const url = typeof input === 'string' ? input : input.toString();
+ if (url.includes('/api/history')) {
+ return Promise.resolve(
+ new Response(JSON.stringify({ entries }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+ }
+ if (url.includes('/api/rollback')) {
+ rollbacks.push({
+ body: init?.body ? JSON.parse(init.body as string) : null,
+ signal: init?.signal,
+ });
+ if (holdRollback) {
+ return new Promise<Response>((resolve) => {
+ resolveHeld = resolve;
+ });
+ }
+ return Promise.resolve(new Response(null, { status: 200 }));
+ }
+ return Promise.resolve(new Response(null, { status: 404 }));
+ }) as never;
+
+ return {
+ rollbacks,
+ release: () => resolveHeld?.(new Response(null, { status: 200 })),
+ };
+}
+
+function renderTimeline() {
+ return render(
+ <TooltipProvider>
+ <TimelineContent docName="notes" />
+ </TooltipProvider>,
+ );
+}
+
+/** The recovered row sits below a newer WIP row, so `laterEdits > 0`. */
+function twoRowHistory(): TimelineEntry[] {
+ return [wipEntry(NEWER_SHA, 'Alice'), recoveredCheckpointEntry(RECOVERED_SHA)];
+}
+
+async function openConfirmForRecoveredRow() {
+ await waitFor(() => expect(screen.getByText('Recovered content')).toBeTruthy());
+ fireEvent.click(screen.getAllByTestId('timeline-entry-restore')[1]);
+ await screen.findByTestId('timeline-entry-restore-confirm');
+}
+
+function restoreButtons(): HTMLButtonElement[] {
+ return screen.getAllByTestId('timeline-entry-restore') as HTMLButtonElement[];
+}
+
+let originalFetch: typeof globalThis.fetch;
+
+beforeEach(() => {
+ originalFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+ globalThis.fetch = originalFetch;
+ cleanup();
+});
+
+describe('TimelineContent — restore confirm dismissal leaves the document untouched', () => {
+ test('Cancel closes the dialog and issues no rollback', async () => {
+ const { rollbacks } = mockTimelineFetch(twoRowHistory());
+
+ renderTimeline();
+ await openConfirmForRecoveredRow();
+ expect(rollbacks).toHaveLength(0);
+
+ fireEvent.click(screen.getByTestId('timeline-entry-restore-cancel'));
+
+ await waitFor(() => expect(screen.queryByTestId('timeline-entry-restore-confirm')).toBeNull());
+ expect(rollbacks).toHaveLength(0);
+ // Backing out leaves the row fully interactive — no pending state stranded
+ // behind the dismissal.
+ expect(restoreButtons()[1].disabled).toBe(false);
+ });
+
+ test('Escape closes the dialog and issues no rollback', async () => {
+ const { rollbacks } = mockTimelineFetch(twoRowHistory());
+
+ renderTimeline();
+ await openConfirmForRecoveredRow();
+ expect(rollbacks).toHaveLength(0);
+
+ await userEvent.keyboard('{Escape}');
+
+ await waitFor(() => expect(screen.queryByTestId('timeline-entry-restore-confirm')).toBeNull());
+ expect(rollbacks).toHaveLength(0);
+ expect(restoreButtons()[1].disabled).toBe(false);
+ });
+
+ test('re-opening after a dismissal still reaches the rollback (the gate is not one-shot)', async () => {
+ const { rollbacks } = mockTimelineFetch(twoRowHistory());
+
+ renderTimeline();
+ await openConfirmForRecoveredRow();
+ fireEvent.click(screen.getByTestId('timeline-entry-restore-cancel'));
+ await waitFor(() => expect(screen.queryByTestId('timeline-entry-restore-confirm')).toBeNull());
+
+ // Second pass through the same gate, this time confirming.
+ fireEvent.click(restoreButtons()[1]);
+ fireEvent.click(await screen.findByTestId('timeline-entry-restore-confirm'));
+
+ await waitFor(() => expect(rollbacks).toHaveLength(1));
+ expect(rollbacks[0].body).toEqual({ docName: 'notes', commitSha: RECOVERED_SHA });
+ });
+});
+
+describe('TimelineContent — the confirm gate is decided by laterEdits', () => {
+ test('a row with later edits raises the dialog first; the newest row restores without one', async () => {
+ // The rollback response is held so both halves are asserted while the
+ // request state is still observable, rather than after a resolution has
+ // torn the dialog down.
+ const { rollbacks, release } = mockTimelineFetch(twoRowHistory(), { holdRollback: true });
+
+ renderTimeline();
+ await waitFor(() => expect(screen.getByText('Recovered content')).toBeTruthy());
+
+ // Row 1 (the recovered checkpoint) has one newer version above it.
+ fireEvent.click(restoreButtons()[1]);
+ expect(await screen.findByTestId('timeline-entry-restore-confirm')).toBeTruthy();
+ expect(rollbacks).toHaveLength(0);
+
+ fireEvent.click(screen.getByTestId('timeline-entry-restore-cancel'));
+ await waitFor(() => expect(screen.queryByTestId('timeline-entry-restore-confirm')).toBeNull());
+
+ // Row 0 is the newest version — nothing stacked above it to roll back, so
+ // the request leaves synchronously on click with no dialog in between.
+ fireEvent.click(restoreButtons()[0]);
+ expect(rollbacks).toHaveLength(1);
+ expect(rollbacks[0].body).toEqual({ docName: 'notes', commitSha: NEWER_SHA });
+ expect(screen.queryByTestId('timeline-entry-restore-confirm')).toBeNull();
+
+ release();
+ await waitFor(() => expect(restoreButtons()[0].disabled).toBe(false));
+ });
+});
diff --git a/packages/app/src/components/TimelinePanel.tsx b/packages/app/src/components/TimelinePanel.tsx
index 8cd8c0884..c729f35f3 100644
--- a/packages/app/src/components/TimelinePanel.tsx
+++ b/packages/app/src/components/TimelinePanel.tsx
@@ -3,15 +3,18 @@
* TimelinePanel — document edit history content for the DocPanel timeline tab.
*
* Fetches GET /api/history on mount, polls every 10s while mounted. The
- * timeline surfaces only actor/system commits — WIP writes from agents,
- * principals, the file watcher, the service, plus upstream syncs — as a flat
- * reverse-chronological list. Checkpoint rows are filtered out: checkpoints
- * — from background cleanup jobs (shadow-branch GC, auto-consolidation,
- * silent rescue) and from agents via the MCP `checkpoint` tool — are restore
- * points, not user-facing edit history (agents reach them through `history` /
- * `restore_version`). The WIP commits those checkpoints fold over remain
- * visible (the server walks their ancestry), so dropping the checkpoint rows
- * loses no edit history.
+ * timeline surfaces actor/system commits — WIP writes from agents, principals,
+ * the file watcher, the service, plus upstream syncs — as a flat
+ * reverse-chronological list, PLUS the recovered-content rescue checkpoints the
+ * shared kind registry marks `visibility: 'surfaced'` (rendered as ordinary
+ * "Recovered content" versions). The rest of the checkpoints stay out: routine
+ * cleanup / auto-consolidation (registry `hidden`) and Save-Version / MCP
+ * `checkpoint`-tool restore points (no parsed kind) are not user-facing edit
+ * history. Whether a checkpoint surfaces is driven by
+ * `isSurfacedCheckpointKind` so this panel never drifts from the server's
+ * timeline-query + GC partition. The WIP commits any dropped checkpoint folds
+ * over remain visible (the server walks their ancestry), so dropping them loses
+ * no edit history.
*
* Per-row UX:
* - Click a row → open the version's "what changed" diff in the main editor
@@ -31,6 +34,7 @@ import {
AGENT_ICON_COLORS_DARK,
colorFromSeed,
iconFromClientName,
+ isSurfacedCheckpointKind,
ProblemDetailsSchema,
type TimelineEntry,
} from '@inkeep/open-knowledge-core';
@@ -43,6 +47,7 @@ import {
ChevronRight,
GitBranch,
HardDrive,
+ History,
Loader2,
RotateCcw,
Sparkles,
@@ -107,12 +112,7 @@ async function pollHistoryOnce(
return 'error';
}
const data = (await res.json()) as { entries: TimelineEntry[] };
- // Drop checkpoint rows: they're background-cleanup artifacts now, not
- // user history. The WIP commits they fold over are returned independently
- // (the server walks checkpoint ancestry), so this loses no edit history.
- // Exclude-by-type (not an allowlist) keeps any future actor/system entry
- // type visible by default.
- handlers.setEntries((data.entries ?? []).filter((e) => e.type !== 'checkpoint'));
+ handlers.setEntries((data.entries ?? []).filter(showsInTimeline));
handlers.setError(null);
return 'ok';
} catch (e) {
@@ -136,6 +136,20 @@ interface TimelineContentProps {
// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * A row belongs in the timeline unless it is a checkpoint the shared kind
+ * registry does not surface. A recovered-content rescue checkpoint (a parsed
+ * surfaced kind) renders as an ordinary version; Save-Version / MCP-checkpoint
+ * restore points (no parsed kind) and registry-`hidden` kinds stay out of edit
+ * history. Guarding `checkpoint !== null` is load-bearing: `isSurfacedCheckpointKind`
+ * treats a null kind as surfaced (its callers include non-checkpoint rows), so
+ * the null-kind checkpoints must be excluded here rather than by the registry.
+ */
+function showsInTimeline(entry: TimelineEntry): boolean {
+ if (entry.type !== 'checkpoint') return true;
+ return entry.checkpoint !== null && isSurfacedCheckpointKind(entry.checkpoint.kind);
+}
+
function formatRelativeTime(isoString: string): string {
const date = new Date(isoString);
const now = new Date();
@@ -178,9 +192,14 @@ type EntryDescriptor =
| { kind: 'rename'; from: string; to: string }
| { kind: 'reconcile' }
| { kind: 'upstream' }
+ | { kind: 'recovered' }
| { kind: 'edit' };
function classifyEntry(entry: TimelineEntry): EntryDescriptor {
+ // Only surfaced rescue checkpoints reach the render (showsInTimeline drops
+ // the rest), so any checkpoint here is recovered content — labeled generically
+ // rather than by its internal kind.
+ if (entry.type === 'checkpoint') return { kind: 'recovered' };
if (entry.type === 'upstream') return { kind: 'upstream' };
const msg = entry.message;
const rollback = /^rollback: .+ to ([0-9a-f]{7,40})$/.exec(msg);
@@ -199,6 +218,9 @@ function docLeaf(path: string): string {
/** Map internal author names to user-friendly display names. Uses structured contributors when available. */
function displayAuthor(entry: TimelineEntry): string {
+ // Rescue checkpoints are service-authored; the recovery framing is the title,
+ // never the raw service author or the internal checkpoint label.
+ if (entry.type === 'checkpoint') return t`Recovered content`;
if (entry.type === 'upstream') return t`Upstream sync`;
if (entry.contributors.length === 1) return entry.contributors[0].name;
if (entry.contributors.length > 1) return entry.contributors.map((c) => c.name).join(', ');
@@ -211,6 +233,7 @@ function displayAuthor(entry: TimelineEntry): string {
function ContributorIcon({ entry, isDark }: { entry: TimelineEntry; isDark: boolean }) {
const iconClass = 'size-3.5 shrink-0 text-muted-foreground';
+ if (entry.type === 'checkpoint') return <History className={iconClass} aria-hidden="true" />;
if (entry.type === 'upstream') return <GitBranch className={iconClass} />;
if (entry.contributors.length > 0) {
@@ -418,6 +441,11 @@ function EntryDetail({
return <p className="truncate text-xs text-muted-foreground">{t`Synced from disk`}</p>;
}
+ // A recovered row's title ("Recovered content") is the whole label; it has no
+ // contributor doc list, so render no second line rather than the "Edited"
+ // fallback below (which would misdescribe a system rescue as a user edit).
+ if (descriptor.kind === 'recovered') return null;
+
if (allDocs.length > 0) {
return (
<p className="truncate text-xs text-muted-foreground" title={allDocs.join(', ')}>
diff --git a/packages/app/src/editor/BackgroundThrottleReporter.dom.test.tsx b/packages/app/src/editor/BackgroundThrottleReporter.dom.test.tsx
new file mode 100644
index 000000000..bec74353d
--- /dev/null
+++ b/packages/app/src/editor/BackgroundThrottleReporter.dom.test.tsx
@@ -0,0 +1,91 @@
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import type { OkDesktopBridge } from '@/lib/desktop-bridge-types';
+
+/**
+ * Composition test for the app-side wiring: config kill-switch + pool signal +
+ * `window.okDesktop` bridge. Verifies the component gates on the Electron host,
+ * reads `bridge.backgroundThrottle.enabled`, and pushes through
+ * `editor.notifyBackgroundThrottle` — the glue the install-helper unit test
+ * (over a fake pool) cannot see. The real main→Chromium effect is the
+ * packaged-app desktop-smoke rung (carried as a coverage gap).
+ */
+
+let pendingListener: (() => void) | null = null;
+let poolPending = false;
+const fakePool = {
+ hasAnyUnsyncedWork: () => poolPending,
+ addUnsyncedWorkListener: (cb: () => void) => {
+ pendingListener = cb;
+ return () => {
+ pendingListener = null;
+ };
+ },
+};
+
+vi.doMock('./DocumentContext', () => ({
+ getPool: () => fakePool,
+ useDocumentContext: () => ({ collabUrl: 'ws://localhost:1/collab' }),
+}));
+
+let projectConfig: unknown = { bridge: { backgroundThrottle: { enabled: true } } };
+vi.doMock('@/lib/config-context', () => ({
+ useConfigContext: () => ({ projectConfig }),
+}));
+
+const { BackgroundThrottleReporter } = await import('./BackgroundThrottleReporter');
+
+function installFakeBridge(): ReturnType<typeof vi.fn> {
+ const notifyBackgroundThrottle = vi.fn();
+ (window as unknown as { okDesktop?: OkDesktopBridge }).okDesktop = {
+ editor: { notifyBackgroundThrottle },
+ } as unknown as OkDesktopBridge;
+ return notifyBackgroundThrottle;
+}
+
+describe('BackgroundThrottleReporter', () => {
+ afterEach(() => {
+ cleanup();
+ pendingListener = null;
+ poolPending = false;
+ projectConfig = { bridge: { backgroundThrottle: { enabled: true } } };
+ (window as unknown as { okDesktop?: OkDesktopBridge }).okDesktop = undefined;
+ });
+
+ test('seeds main with the current state and reports the pending-work edge', () => {
+ const notify = installFakeBridge();
+ render(<BackgroundThrottleReporter />);
+ expect(notify).toHaveBeenCalledTimes(1);
+ expect(notify).toHaveBeenLastCalledWith({ hasPendingWork: false, enabled: true });
+
+ poolPending = true;
+ pendingListener?.();
+ expect(notify).toHaveBeenLastCalledWith({ hasPendingWork: true, enabled: true });
+ });
+
+ test('carries a disabled kill-switch so main resolves the OS default', () => {
+ projectConfig = { bridge: { backgroundThrottle: { enabled: false } } };
+ const notify = installFakeBridge();
+ render(<BackgroundThrottleReporter />);
+ expect(notify).toHaveBeenLastCalledWith({ hasPendingWork: false, enabled: false });
+ });
+
+ test('is inert outside the Electron host (no window.okDesktop)', () => {
+ // No bridge installed — the component must not touch the pool or throw.
+ expect(() => render(<BackgroundThrottleReporter />)).not.toThrow();
+ expect(pendingListener).toBeNull();
+ });
+
+ test('is inert on a bridge whose editor lacks notifyBackgroundThrottle (older shell)', () => {
+ // The preload bridge is a cross-process contract the renderer cannot
+ // enforce: a shell built before this channel exposes `editor` without the
+ // method. Throttling is an optimization; its absence must not crash the
+ // app shell (an unguarded call here took down the whole tree through the
+ // nearest error boundary, caught by the desktop-emulating e2e).
+ (window as unknown as { okDesktop?: OkDesktopBridge }).okDesktop = {
+ editor: { notifyActiveTargetChanged: () => {} },
+ } as unknown as OkDesktopBridge;
+ expect(() => render(<BackgroundThrottleReporter />)).not.toThrow();
+ expect(pendingListener).toBeNull();
+ });
+});
diff --git a/packages/app/src/editor/BackgroundThrottleReporter.tsx b/packages/app/src/editor/BackgroundThrottleReporter.tsx
new file mode 100644
index 000000000..f4973b6b4
--- /dev/null
+++ b/packages/app/src/editor/BackgroundThrottleReporter.tsx
@@ -0,0 +1,39 @@
+import { useEffect } from 'react';
+import { useConfigContext } from '@/lib/config-context';
+import { getPool, useDocumentContext } from './DocumentContext';
+import { installBackgroundThrottleReporter } from './install-background-throttle-reporter';
+
+/**
+ * Reports the window's unsynced-work state to the desktop main process so main
+ * keys the window's Chromium background-throttling to it. Renders nothing.
+ *
+ * Inert outside the Electron host (no `window.okDesktop`). Mounted under both
+ * DocumentProvider (for `collabUrl` → the pool) and ConfigProvider (for the
+ * `bridge.backgroundThrottle.enabled` kill-switch, default ON until the config
+ * doc syncs, matching the schema default).
+ */
+export function BackgroundThrottleReporter(): null {
+ const { collabUrl } = useDocumentContext();
+ const { projectConfig } = useConfigContext();
+ const enabled = projectConfig?.bridge?.backgroundThrottle?.enabled ?? true;
+
+ useEffect(() => {
+ if (collabUrl === null) return;
+ const bridge = window.okDesktop;
+ // Capability check, not just host check: the preload bridge is a
+ // cross-process contract the renderer cannot enforce, so a shell built
+ // before this channel exposes `editor` without the method. Throttling is
+ // an optimization; its absence must never crash the app shell.
+ const notify = bridge?.editor?.notifyBackgroundThrottle;
+ if (typeof notify !== 'function') return;
+ const pool = getPool(collabUrl);
+ return installBackgroundThrottleReporter({
+ enabled,
+ hasAnyUnsyncedWork: () => pool.hasAnyUnsyncedWork(),
+ addUnsyncedWorkListener: (cb) => pool.addUnsyncedWorkListener(cb),
+ report: (signal) => notify(signal),
+ });
+ }, [collabUrl, enabled]);
+
+ return null;
+}
diff --git a/packages/app/src/editor/DocumentContext.tsx b/packages/app/src/editor/DocumentContext.tsx
index 5a4ec7954..440963b66 100644
--- a/packages/app/src/editor/DocumentContext.tsx
+++ b/packages/app/src/editor/DocumentContext.tsx
@@ -380,7 +380,7 @@ const MARKDOWN_EXTENSION_QUALIFIED_DOC_PATTERN = /\.(md|mdx)$/i;
// module instance takes over so WebSocket / observer / timer state doesn't leak.
let pool: ProviderPool | null = null;
-function getPool(collabUrl: string): ProviderPool {
+export function getPool(collabUrl: string): ProviderPool {
if (!pool) {
pool = new ProviderPool(MAX_POOL, collabUrl);
// Wire the editor cache to the pool's eviction events. Without this
diff --git a/packages/app/src/editor/EditorLifecycleFlush.tsx b/packages/app/src/editor/EditorLifecycleFlush.tsx
new file mode 100644
index 000000000..80a55eab7
--- /dev/null
+++ b/packages/app/src/editor/EditorLifecycleFlush.tsx
@@ -0,0 +1,30 @@
+import { useEffect } from 'react';
+import { useConfigContext } from '@/lib/config-context';
+import { getPool, useDocumentContext } from './DocumentContext';
+import { installEditorLifecycleFlush } from './install-editor-lifecycle-flush';
+
+/**
+ * Wires tab-lifecycle background flush / resync to the provider pool and
+ * honors the `bridge.flushOnHide.enabled` kill-switch. Renders nothing.
+ *
+ * Mounted under both DocumentProvider (for `collabUrl` → the pool) and
+ * ConfigProvider (for the project config). The kill-switch defaults ON until
+ * the config doc syncs (`projectConfig` null), matching the schema default.
+ */
+export function EditorLifecycleFlush(): null {
+ const { collabUrl } = useDocumentContext();
+ const { projectConfig } = useConfigContext();
+ const enabled = projectConfig?.bridge?.flushOnHide?.enabled ?? true;
+
+ useEffect(() => {
+ if (collabUrl === null) return;
+ const pool = getPool(collabUrl);
+ pool.setFlushOnHideEnabled(enabled);
+ return installEditorLifecycleFlush({
+ onHide: () => pool.flushOnHide(),
+ onVisible: () => pool.resyncOnVisible(),
+ });
+ }, [collabUrl, enabled]);
+
+ return null;
+}
diff --git a/packages/app/src/editor/SourceEditor.tsx b/packages/app/src/editor/SourceEditor.tsx
index 5169fdb4d..fe583f85a 100644
--- a/packages/app/src/editor/SourceEditor.tsx
+++ b/packages/app/src/editor/SourceEditor.tsx
@@ -10,10 +10,9 @@ import {
toEffectiveBase,
} from '@inkeep/open-knowledge-core';
import { isMacOS } from '@tiptap/core';
-import { basicSetup } from 'codemirror';
import { useTheme } from 'next-themes';
import { useEffect, useRef, useState } from 'react';
-import { yCollab } from 'y-codemirror.next';
+import { yCollab, yUndoManagerKeymap } from 'y-codemirror.next';
import type * as Y from 'yjs';
import { emitOpenAskAiComposer } from '@/components/ask-ai-composer-events';
import { OUTLINE_NAV_EVENT, type OutlineNavDetail } from '@/components/OutlinePanel';
@@ -42,6 +41,7 @@ import {
consumePendingSourceNavigation,
} from './source-editor-navigation';
import { createMarkdownLintExtension } from './source-lint/markdown-lint-source';
+import { sourceModeSetup } from './source-mode-setup';
import { createSourcePolishExtension } from './source-polish';
import { FM_FENCE_LINE_RE } from './source-polish/view-plugin';
import { attachTypingBurstDetector } from './typing-burst-detector';
@@ -255,7 +255,7 @@ export function SourceEditor({
const state = EditorState.create({
doc: ytext.toString(),
extensions: [
- basicSetup,
+ sourceModeSetup,
// Search-result scroll. CM's default search `scrollToMatch` is
// `EditorView.scrollIntoView(range)` (y:'nearest'), which no-ops in
// full-page source mode: the editor renders at content height with no
@@ -276,6 +276,10 @@ export function SourceEditor({
// focus mode. Upstream convention per codemirror.net/examples/tab/.
keymap.of([indentWithTab]),
yCollab(ytext, provider.awareness),
+ // Route Mod-z/Mod-y to the y-codemirror Y.UndoManager (origin-aware,
+ // remote/agent writes excluded) instead of CodeMirror's native
+ // history, which sourceModeSetup omits.
+ keymap.of(yUndoManagerKeymap),
// Nested-CM / SourceEditor convergence: the factory provides markdown
// (with GFM + codeLanguages), wiki-link + md-link decorations,
// agent-flash, theme compartment, line-wrapping. Source mode adds the
diff --git a/packages/app/src/editor/TiptapEditor.tsx b/packages/app/src/editor/TiptapEditor.tsx
index bdf658ca0..72c3aa63a 100644
--- a/packages/app/src/editor/TiptapEditor.tsx
+++ b/packages/app/src/editor/TiptapEditor.tsx
@@ -38,6 +38,7 @@ import type { SidebarDragPayload } from '@/lib/sidebar-drag';
import { useIdentity } from '../presence/identity';
import { registerEditor, unregisterEditor } from './active-editor';
import { applyLintFixes } from './apply-lint-fix.ts';
+import { getAwarenessHeartbeat } from './awareness-heartbeat-runtime';
import { buildAwarenessUser } from './awareness-user';
import { bindingStalenessGuardPlugin, type WedgeDetail } from './binding-staleness-guard';
import { BubbleMenuBar } from './bubble-menu/BubbleMenuBar';
@@ -1554,6 +1555,14 @@ const TiptapEditorChrome: FC<TiptapEditorChromeProps> = ({
user: buildAwarenessUser({ principal, identity }),
mode: isSourceMode ? 'source' : 'wysiwyg',
});
+ // Keep this presence entry fresh from an unthrottled worker clock so a
+ // backgrounded tab (whose main-thread renewal is throttled) isn't pruned
+ // as outdated by peers. clearAwareness on cleanup is race-safe against a
+ // newly-active editor registering first.
+ const heartbeat = getAwarenessHeartbeat();
+ heartbeat.start();
+ heartbeat.setAwareness(awareness);
+ return () => heartbeat.clearAwareness(awareness);
}, [provider, docName, activeDocName, identity, principal, isSourceMode]);
// Plumb the React `isSourceMode` prop through to the per-editor WeakMap in
diff --git a/packages/app/src/editor/awareness-heartbeat-runtime.test.ts b/packages/app/src/editor/awareness-heartbeat-runtime.test.ts
new file mode 100644
index 000000000..9b8be1c87
--- /dev/null
+++ b/packages/app/src/editor/awareness-heartbeat-runtime.test.ts
@@ -0,0 +1,241 @@
+/**
+ * The production wiring of the presence keepalive: `getAwarenessHeartbeat()`,
+ * its `WorkerTicker`, and the worker that actually holds the clock.
+ *
+ * `awareness-heartbeat.test.ts` drives the renewal policy through an injected
+ * ticker, which leaves the entire worker path unobserved — and the worker path
+ * IS the feature ("worker timers are not background-throttled"). A wrong
+ * interval constant, a mismatched message string, or a missing
+ * `postMessage('start')` would leave that suite green while presence quietly
+ * starves in every backgrounded tab.
+ *
+ * So both real modules run here, wired to each other through a two-ended
+ * transport that stands in for the `Worker` boundary itself: the main side is
+ * what `WorkerTicker` constructs, the worker side is the global `self` the
+ * worker installs its handler on. Neither module is stubbed, so the message
+ * vocabulary and the interval are pinned end to end.
+ *
+ * The heartbeat is a module singleton, so each test re-imports the graph
+ * (`vi.resetModules()`) to get a fresh one.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+import { AWARENESS_RENEW_INTERVAL_MS } from './awareness-heartbeat';
+
+interface WorkerScopeLike {
+ postMessage(message: unknown): void;
+ onmessage: ((event: { data: unknown }) => void) | null;
+}
+
+const constructed: { url: unknown; options: unknown }[] = [];
+let terminateCount = 0;
+let mainSide: TransportWorker | null = null;
+let workerScope: WorkerScopeLike;
+
+/** The main-thread end of the transport — the object `new Worker(...)` yields. */
+class TransportWorker {
+ onmessage: ((event: { data: unknown }) => void) | null = null;
+ constructor(url: unknown, options?: unknown) {
+ constructed.push({ url, options });
+ mainSide = this;
+ }
+ postMessage(message: unknown): void {
+ workerScope.onmessage?.({ data: message });
+ }
+ terminate(): void {
+ terminateCount += 1;
+ }
+}
+
+/** Pin the awareness's local stamp into the fake-timer time base. */
+function setLastUpdated(aw: Awareness, t: number): void {
+ const meta = aw.meta.get(aw.clientID);
+ if (meta) aw.meta.set(aw.clientID, { clock: meta.clock, lastUpdated: t });
+}
+
+async function loadRuntime(): Promise<typeof import('./awareness-heartbeat-runtime')> {
+ vi.resetModules();
+ // Importing the worker installs its `onmessage` on the stubbed scope, which
+ // is what the transport's main side posts into.
+ await import('./awareness-heartbeat.worker');
+ return import('./awareness-heartbeat-runtime');
+}
+
+let doc: Y.Doc;
+let awareness: Awareness;
+
+beforeEach(() => {
+ constructed.length = 0;
+ terminateCount = 0;
+ mainSide = null;
+ workerScope = {
+ onmessage: null,
+ postMessage: (message: unknown) => {
+ mainSide?.onmessage?.({ data: message });
+ },
+ };
+ vi.stubGlobal('self', workerScope);
+ vi.stubGlobal('Worker', TransportWorker);
+ vi.useFakeTimers();
+ doc = new Y.Doc();
+ awareness = new Awareness(doc);
+});
+
+afterEach(() => {
+ awareness.destroy();
+ doc.destroy();
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+});
+
+/** Publish presence and pin its stamp to the current (faked) instant. */
+function publish(): void {
+ awareness.setLocalState({ user: { name: 'me' } });
+ setLastUpdated(awareness, Date.now());
+}
+
+describe('awareness heartbeat production wiring', () => {
+ it('renews the local entry off the worker clock at the renewal interval', async () => {
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ const heartbeat = getAwarenessHeartbeat();
+ heartbeat.setAwareness(awareness);
+ publish();
+ const clockAtPublish = awareness.meta.get(awareness.clientID)?.clock ?? -1;
+
+ heartbeat.start();
+ vi.advanceTimersByTime(AWARENESS_RENEW_INTERVAL_MS);
+
+ // A renewal bumps the awareness clock, which is what peers watch to decide
+ // the entry is not outdated. Nothing between `start()` and this assertion
+ // is stubbed: the ticker really constructed a worker, really posted
+ // `start`, the worker's own interval really fired, and its `tick` really
+ // reached the heartbeat.
+ expect(awareness.meta.get(awareness.clientID)?.clock ?? -1).toBeGreaterThan(clockAtPublish);
+
+ heartbeat.stop();
+ });
+
+ it('does not tick before the interval elapses', async () => {
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ const heartbeat = getAwarenessHeartbeat();
+ heartbeat.setAwareness(awareness);
+ publish();
+ let updates = 0;
+ awareness.on('update', () => {
+ updates += 1;
+ });
+
+ heartbeat.start();
+ vi.advanceTimersByTime(AWARENESS_RENEW_INTERVAL_MS - 1);
+
+ // Pins the worker's interval to the shared constant: a worker clock that
+ // ran faster (or on a literal of its own) would already have ticked.
+ expect(updates).toBe(0);
+ });
+
+ it('keeps renewing every interval for as long as it runs', async () => {
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ const heartbeat = getAwarenessHeartbeat();
+ heartbeat.setAwareness(awareness);
+ publish();
+ heartbeat.start();
+
+ const renewInstants: number[] = [];
+ awareness.on('update', () => renewInstants.push(Date.now()));
+
+ for (let i = 0; i < 4; i += 1) {
+ vi.advanceTimersByTime(AWARENESS_RENEW_INTERVAL_MS);
+ setLastUpdated(awareness, Date.now());
+ }
+
+ expect(renewInstants).toHaveLength(4);
+ heartbeat.stop();
+ });
+
+ it('constructs the worker as an ES module', async () => {
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ getAwarenessHeartbeat().start();
+
+ expect(constructed).toHaveLength(1);
+ // The worker source uses ESM `import`, so a classic worker would fail to
+ // load and the clock would never start.
+ expect(constructed[0]?.options).toMatchObject({ type: 'module' });
+ expect(String(constructed[0]?.url)).toContain('awareness-heartbeat.worker');
+ });
+
+ it('start() is idempotent — one worker, one clock', async () => {
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ const heartbeat = getAwarenessHeartbeat();
+ heartbeat.setAwareness(awareness);
+ publish();
+ let updates = 0;
+ awareness.on('update', () => {
+ updates += 1;
+ });
+
+ heartbeat.start();
+ heartbeat.start();
+ vi.advanceTimersByTime(AWARENESS_RENEW_INTERVAL_MS);
+
+ expect(constructed).toHaveLength(1);
+ expect(updates).toBe(1);
+ heartbeat.stop();
+ });
+
+ it('stop() halts the worker clock and terminates it', async () => {
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ const heartbeat = getAwarenessHeartbeat();
+ heartbeat.setAwareness(awareness);
+ publish();
+ heartbeat.start();
+
+ heartbeat.stop();
+ let updates = 0;
+ awareness.on('update', () => {
+ updates += 1;
+ });
+ vi.advanceTimersByTime(AWARENESS_RENEW_INTERVAL_MS * 5);
+
+ expect(terminateCount).toBe(1);
+ expect(updates).toBe(0);
+ });
+
+ it('ignores worker messages that are not ticks', async () => {
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ const heartbeat = getAwarenessHeartbeat();
+ heartbeat.setAwareness(awareness);
+ publish();
+ heartbeat.start();
+ // Age the entry past the renewal threshold so a renewal is the ONLY thing
+ // standing between this message and an observable update.
+ vi.setSystemTime(Date.now() + AWARENESS_RENEW_INTERVAL_MS * 2);
+ let updates = 0;
+ awareness.on('update', () => {
+ updates += 1;
+ });
+
+ workerScope.postMessage('not-a-tick');
+ workerScope.postMessage({ type: 'tick' });
+
+ expect(updates).toBe(0);
+ heartbeat.stop();
+ });
+
+ it('returns a process singleton', async () => {
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ expect(getAwarenessHeartbeat()).toBe(getAwarenessHeartbeat());
+ });
+
+ it('degrades to inert where there is no Worker (SSR, unit rigs)', async () => {
+ vi.stubGlobal('Worker', undefined);
+ const { getAwarenessHeartbeat } = await loadRuntime();
+ const heartbeat = getAwarenessHeartbeat();
+ heartbeat.setAwareness(awareness);
+ publish();
+
+ expect(() => heartbeat.start()).not.toThrow();
+ expect(constructed).toHaveLength(0);
+ expect(() => heartbeat.stop()).not.toThrow();
+ });
+});
diff --git a/packages/app/src/editor/awareness-heartbeat-runtime.ts b/packages/app/src/editor/awareness-heartbeat-runtime.ts
new file mode 100644
index 000000000..8f5668135
--- /dev/null
+++ b/packages/app/src/editor/awareness-heartbeat-runtime.ts
@@ -0,0 +1,48 @@
+/**
+ * Production wiring for {@link AwarenessHeartbeat}: a Web Worker-backed ticker
+ * plus a process singleton the active editor points at its awareness.
+ */
+import { AwarenessHeartbeat, type HeartbeatTicker } from './awareness-heartbeat';
+
+class WorkerTicker implements HeartbeatTicker {
+ private worker: Worker | null = null;
+
+ start(onTick: () => void): void {
+ // No Worker outside a browser (jsdom unit rigs, SSR) — degrade to inert
+ // rather than throw; the vendored main-thread renewal still runs there.
+ if (typeof Worker === 'undefined' || this.worker !== null) return;
+ this.worker = new Worker(new URL('./awareness-heartbeat.worker.ts', import.meta.url), {
+ type: 'module',
+ });
+ this.worker.onmessage = (event: MessageEvent) => {
+ if (event.data === 'tick') onTick();
+ };
+ this.worker.postMessage('start');
+ }
+
+ stop(): void {
+ if (this.worker === null) return;
+ this.worker.postMessage('stop');
+ this.worker.terminate();
+ this.worker = null;
+ }
+}
+
+let singleton: AwarenessHeartbeat | null = null;
+
+/** The process-wide awareness heartbeat, created lazily on first use. */
+export function getAwarenessHeartbeat(): AwarenessHeartbeat {
+ if (singleton === null) singleton = new AwarenessHeartbeat(new WorkerTicker());
+ return singleton;
+}
+
+// Under Vite HMR the module reloads, but the Web Worker + interval the singleton
+// started would be orphaned. Tear it down on dispose, mirroring the ProviderPool
+// singleton in DocumentContext. Production builds strip this branch entirely
+// (Vite replaces `import.meta.hot` with `undefined` at build time).
+if (import.meta.hot) {
+ import.meta.hot.dispose(() => {
+ singleton?.stop();
+ singleton = null;
+ });
+}
diff --git a/packages/app/src/editor/awareness-heartbeat.test.ts b/packages/app/src/editor/awareness-heartbeat.test.ts
new file mode 100644
index 000000000..185d7d969
--- /dev/null
+++ b/packages/app/src/editor/awareness-heartbeat.test.ts
@@ -0,0 +1,216 @@
+/**
+ * Starvation contract for the worker-homed presence keepalive.
+ *
+ * Peers prune a presence entry after `outdatedTimeout` (30s) with no update.
+ * The vendored renewal runs on a main-thread timer a backgrounded tab
+ * throttles to ~1/min, so the entry would cross the prune line; the heartbeat
+ * re-homes the renewal on an unthrottled worker clock. This drives that
+ * renewal logic through an injected ticker + clock against REAL y-protocols
+ * Awareness objects (real lastUpdated/clock bookkeeping, real update fan-out to
+ * a wired peer). It does NOT reproduce real browser throttling — that is only
+ * observable at a browser/long-run rung and is carried as an open residual,
+ * not claimed here.
+ *
+ * Time base: y-protocols stamps `lastUpdated` from a reference to `Date.now`
+ * captured at import, so fake timers can't reach it. Instead the heartbeat's
+ * `now` is injected and each simulated renewal instant is written back into the
+ * awareness meta, keeping the awareness's stamp and the heartbeat's clock in
+ * one controlled time base.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+ Awareness,
+ applyAwarenessUpdate,
+ encodeAwarenessUpdate,
+ outdatedTimeout,
+} from 'y-protocols/awareness';
+import * as Y from 'yjs';
+import { AwarenessHeartbeat, type HeartbeatTicker } from './awareness-heartbeat';
+
+class ManualTicker implements HeartbeatTicker {
+ private cb: (() => void) | null = null;
+ start(onTick: () => void): void {
+ this.cb = onTick;
+ }
+ stop(): void {
+ this.cb = null;
+ }
+ fire(): void {
+ this.cb?.();
+ }
+}
+
+/** Pin the awareness's local stamp into the test-controlled time base. */
+function setLastUpdated(aw: Awareness, t: number): void {
+ const meta = aw.meta.get(aw.clientID);
+ if (meta) aw.meta.set(aw.clientID, { clock: meta.clock, lastUpdated: t });
+}
+
+function wire(from: Awareness, to: Awareness): void {
+ from.on(
+ 'update',
+ ({ added, updated, removed }: { added: number[]; updated: number[]; removed: number[] }) => {
+ const changed = added.concat(updated).concat(removed);
+ applyAwarenessUpdate(to, encodeAwarenessUpdate(from, changed), 'wire');
+ },
+ );
+}
+
+describe('AwarenessHeartbeat starvation contract', () => {
+ it('renews at worker cadence so consecutive updates never exceed the prune window', () => {
+ const clientDoc = new Y.Doc();
+ const peerDoc = new Y.Doc();
+ const clientAw = new Awareness(clientDoc);
+ const peerAw = new Awareness(peerDoc);
+ wire(clientAw, peerAw);
+
+ let clock = 0;
+ const ticker = new ManualTicker();
+ const heartbeat = new AwarenessHeartbeat(ticker, { now: () => clock });
+ heartbeat.setAwareness(clientAw);
+ heartbeat.start();
+
+ // Publish at t=0. The publish is the first "fresh" instant.
+ clientAw.setLocalState({ user: { name: 'me' } });
+ setLastUpdated(clientAw, 0);
+ const peerClockAtPublish = peerAw.meta.get(clientAw.clientID)?.clock ?? -1;
+
+ const renewInstants: number[] = [0];
+ clientAw.on('update', () => renewInstants.push(clock));
+
+ // Worker ticks every 15s (its unthrottled cadence), well past the 30s line.
+ for (const t of [15_000, 30_000, 45_000, 60_000]) {
+ clock = t;
+ ticker.fire();
+ setLastUpdated(clientAw, t); // the renewal (if any) landed at this instant
+ }
+
+ // Every tick renewed (15s ≥ the 15s threshold), so the peer observed four
+ // fresh updates and the largest gap between renewals stays under the prune
+ // window — the entry never goes outdated.
+ expect(renewInstants).toEqual([0, 15_000, 30_000, 45_000, 60_000]);
+ let maxGap = 0;
+ for (let i = 1; i < renewInstants.length; i++) {
+ maxGap = Math.max(maxGap, renewInstants[i] - renewInstants[i - 1]);
+ }
+ expect(maxGap).toBeLessThan(outdatedTimeout);
+
+ const peerClockNow = peerAw.meta.get(clientAw.clientID)?.clock ?? -1;
+ expect(peerClockNow - peerClockAtPublish).toBe(4); // peer saw each renewal
+
+ heartbeat.stop();
+ clientAw.destroy();
+ peerAw.destroy();
+ clientDoc.destroy();
+ peerDoc.destroy();
+ });
+
+ it('without the heartbeat renewing, the entry goes outdated past the prune window', () => {
+ const doc = new Y.Doc();
+ const aw = new Awareness(doc);
+
+ let clock = 0;
+ const ticker = new ManualTicker();
+ // Registered but never started — models the clamped main thread with no
+ // worker assist. Ticks that do fire must not renew.
+ const heartbeat = new AwarenessHeartbeat(ticker, { now: () => clock });
+ heartbeat.setAwareness(aw);
+
+ aw.setLocalState({ user: { name: 'me' } });
+ setLastUpdated(aw, 0);
+ let updates = 0;
+ aw.on('update', () => {
+ updates += 1;
+ });
+
+ clock = 45_000;
+ ticker.fire(); // heartbeat not started → inert
+
+ expect(updates).toBe(0);
+ const lastUpdated = aw.meta.get(aw.clientID)?.lastUpdated ?? 0;
+ expect(clock - lastUpdated).toBeGreaterThanOrEqual(outdatedTimeout);
+
+ aw.destroy();
+ doc.destroy();
+ });
+
+ it('does not re-stamp an entry that is still fresh', () => {
+ const doc = new Y.Doc();
+ const aw = new Awareness(doc);
+
+ let clock = 0;
+ const ticker = new ManualTicker();
+ const heartbeat = new AwarenessHeartbeat(ticker, { now: () => clock });
+ heartbeat.setAwareness(aw);
+ heartbeat.start();
+
+ aw.setLocalState({ user: { name: 'me' } });
+ setLastUpdated(aw, 0);
+ let updates = 0;
+ aw.on('update', () => {
+ updates += 1;
+ });
+
+ clock = 5_000; // only 5s elapsed, under the 15s threshold
+ ticker.fire();
+
+ expect(updates).toBe(0);
+
+ heartbeat.stop();
+ aw.destroy();
+ doc.destroy();
+ });
+
+ it('is a no-op when nothing is registered or the local state is null', () => {
+ const ticker = new ManualTicker();
+ const heartbeat = new AwarenessHeartbeat(ticker);
+ heartbeat.start();
+ expect(() => ticker.fire()).not.toThrow(); // no awareness registered
+
+ const doc = new Y.Doc();
+ const aw = new Awareness(doc); // local state null (never published)
+ heartbeat.setAwareness(aw);
+ expect(() => ticker.fire()).not.toThrow();
+
+ heartbeat.stop();
+ aw.destroy();
+ doc.destroy();
+ });
+
+ it('clearAwareness clears only the current registration', () => {
+ const docA = new Y.Doc();
+ const docB = new Y.Doc();
+ const awA = new Awareness(docA);
+ const awB = new Awareness(docB);
+
+ let clock = 0;
+ const ticker = new ManualTicker();
+ const heartbeat = new AwarenessHeartbeat(ticker, { now: () => clock });
+ heartbeat.setAwareness(awA);
+ heartbeat.start();
+
+ awA.setLocalState({ user: { name: 'a' } });
+ setLastUpdated(awA, 0);
+
+ // Wrong instance → no-op; awA is still registered and renews when stale.
+ heartbeat.clearAwareness(awB);
+ clock = 20_000;
+ ticker.fire();
+ const clockAfterRenew = awA.meta.get(awA.clientID)?.clock ?? -1;
+ expect(clockAfterRenew).toBeGreaterThan(0);
+ setLastUpdated(awA, 20_000);
+
+ // Correct instance → clears; a later stale tick no longer renews.
+ heartbeat.clearAwareness(awA);
+ clock = 60_000;
+ ticker.fire();
+ expect(awA.meta.get(awA.clientID)?.clock).toBe(clockAfterRenew);
+
+ heartbeat.stop();
+ awA.destroy();
+ awB.destroy();
+ docA.destroy();
+ docB.destroy();
+ });
+});
diff --git a/packages/app/src/editor/awareness-heartbeat.ts b/packages/app/src/editor/awareness-heartbeat.ts
new file mode 100644
index 000000000..73c345ea7
--- /dev/null
+++ b/packages/app/src/editor/awareness-heartbeat.ts
@@ -0,0 +1,94 @@
+/**
+ * Worker-homed keepalive for per-doc presence.
+ *
+ * The vendored y-protocols Awareness renews the local entry every
+ * `outdatedTimeout / 2` (15s) and peers prune an entry after `outdatedTimeout`
+ * (30s) with no update. That renewal runs on a MAIN-THREAD `setInterval`,
+ * which a backgrounded tab throttles to ~1/min — long enough for peers to
+ * drop this client as outdated, so presence flaps when the tab returns. This
+ * heartbeat re-homes the renewal on a Web Worker clock (worker timers are not
+ * background-throttled), re-stamping the local entry within the prune window
+ * so peers keep seeing it.
+ *
+ * Non-authoritative and best-effort: it is a presence assist, not a durability
+ * mechanism (that is flush-on-hide). Real background-throttling behavior is
+ * only observable at a browser/long-run rung; the hermetic test drives the
+ * renewal logic through an injected ticker and does not claim real throttling.
+ */
+import type { Awareness } from 'y-protocols/awareness';
+
+/** `outdatedTimeout / 2` — the vendored Awareness renewal threshold. */
+export const AWARENESS_RENEW_INTERVAL_MS = 15_000;
+
+/**
+ * Drives the heartbeat's ticks. Production uses a Web Worker whose timer the
+ * browser does not throttle; tests inject a manual ticker to advance renewals
+ * deterministically.
+ */
+export interface HeartbeatTicker {
+ start(onTick: () => void): void;
+ stop(): void;
+}
+
+export interface AwarenessHeartbeatOptions {
+ renewIntervalMs?: number;
+ now?: () => number;
+}
+
+export class AwarenessHeartbeat {
+ private awareness: Awareness | null = null;
+ private started = false;
+ private readonly renewIntervalMs: number;
+ private readonly now: () => number;
+
+ constructor(
+ private readonly ticker: HeartbeatTicker,
+ options: AwarenessHeartbeatOptions = {},
+ ) {
+ this.renewIntervalMs = options.renewIntervalMs ?? AWARENESS_RENEW_INTERVAL_MS;
+ this.now = options.now ?? (() => Date.now());
+ }
+
+ start(): void {
+ if (this.started) return;
+ this.started = true;
+ this.ticker.start(() => this.renewIfStale());
+ }
+
+ stop(): void {
+ if (!this.started) return;
+ this.started = false;
+ this.ticker.stop();
+ this.awareness = null;
+ }
+
+ /** Point the heartbeat at the active doc's awareness, or `null` to idle. */
+ setAwareness(awareness: Awareness | null): void {
+ this.awareness = awareness;
+ }
+
+ /**
+ * Clear only if the heartbeat still points at `awareness`. An unmounting
+ * editor uses this so a cleanup that races a newly-active editor's
+ * `setAwareness` can't blank the new registration.
+ */
+ clearAwareness(awareness: Awareness): void {
+ if (this.awareness === awareness) this.awareness = null;
+ }
+
+ /** Re-stamp the local entry when it is within one interval of going stale. */
+ renewIfStale(): void {
+ const awareness = this.awareness;
+ if (awareness === null) return;
+ const local = awareness.getLocalState();
+ // A nulled entry is an intentional removal (navigate-away), not a
+ // starvation candidate — nothing to keep alive.
+ if (local === null) return;
+ const lastUpdated = awareness.meta.get(awareness.clientID)?.lastUpdated ?? 0;
+ if (this.now() - lastUpdated >= this.renewIntervalMs) {
+ // Re-setting the same state bumps lastUpdated and fans a fresh update to
+ // peers — the exact renewal the vendored main-thread timer would do.
+ awareness.setLocalState(local);
+ }
+ }
+}
diff --git a/packages/app/src/editor/awareness-heartbeat.worker.ts b/packages/app/src/editor/awareness-heartbeat.worker.ts
new file mode 100644
index 000000000..657bd3409
--- /dev/null
+++ b/packages/app/src/editor/awareness-heartbeat.worker.ts
@@ -0,0 +1,31 @@
+/**
+ * Unthrottled tick source for the awareness heartbeat. A dedicated Web Worker
+ * timer is not subject to the background-tab throttling the main thread is, so
+ * it keeps posting ticks on schedule while the tab is hidden — which is the
+ * whole point of homing the presence keepalive off the main thread.
+ */
+import { AWARENESS_RENEW_INTERVAL_MS } from './awareness-heartbeat';
+
+type WorkerScope = {
+ postMessage(message: unknown): void;
+ onmessage: ((event: { data: unknown }) => void) | null;
+};
+// In a worker context `self` is the DedicatedWorkerGlobalScope; the cast keeps
+// this file typeable under the app's DOM lib without a webworker-lib reference
+// that would conflict with the rest of the package.
+const scope = self as unknown as WorkerScope;
+
+let timer: ReturnType<typeof setInterval> | null = null;
+
+scope.onmessage = (event) => {
+ if (event.data === 'start') {
+ if (timer === null) {
+ timer = setInterval(() => scope.postMessage('tick'), AWARENESS_RENEW_INTERVAL_MS);
+ }
+ } else if (event.data === 'stop') {
+ if (timer !== null) {
+ clearInterval(timer);
+ timer = null;
+ }
+ }
+};
diff --git a/packages/app/src/editor/client-persistence.test.ts b/packages/app/src/editor/client-persistence.test.ts
index b56a3957c..f92e7961a 100644
--- a/packages/app/src/editor/client-persistence.test.ts
+++ b/packages/app/src/editor/client-persistence.test.ts
@@ -645,6 +645,36 @@ describe('flushFullState', () => {
docB.destroy();
});
+ test('commits the flush transaction explicitly and still persists durably', async () => {
+ const docName = uniqueDocName('cp-flush-commit');
+ const doc = new Y.Doc();
+ const provider = createClientPersistence({
+ branch: TEST_BRANCH,
+ serverInstanceId: TEST_SERVER_INSTANCE_ID,
+ docName,
+ doc,
+ });
+ await provider.whenSynced;
+ doc.getText('source').insert(0, 'commit me');
+
+ // Only the flush path calls IDBTransaction.commit() explicitly; every
+ // other IDB op in this suite relies on auto-commit, so a call on the
+ // prototype during the flush is attributable to the flush path.
+ const commitSpy = vi.spyOn(IDBTransaction.prototype, 'commit');
+ try {
+ await provider.flushFullState();
+ expect(commitSpy).toHaveBeenCalled();
+ } finally {
+ commitSpy.mockRestore();
+ }
+
+ // Explicit commit must not break durability: a full-state row is present.
+ const rows = await readPersistedUpdates(TEST_BRANCH, TEST_SERVER_INSTANCE_ID, docName);
+ expect(rows.length).toBe(1);
+ await provider.destroy();
+ doc.destroy();
+ });
+
test('resolves only after the full-state row is committed and superseded rows are trimmed', async () => {
const docName = uniqueDocName('cp-flush-durable');
const doc = new Y.Doc();
diff --git a/packages/app/src/editor/client-persistence.ts b/packages/app/src/editor/client-persistence.ts
index 612693eff..f7e777aba 100644
--- a/packages/app/src/editor/client-persistence.ts
+++ b/packages/app/src/editor/client-persistence.ts
@@ -244,6 +244,13 @@ class ClientPersistenceImpl implements ClientPersistenceProvider {
// just written; rows added concurrently after it keep their
// own, higher keys.
store.delete(IDBKeyRange.upperBound(addReq.result, true));
+ // Explicitly commit rather than waiting for the auto-commit that
+ // fires when the event loop next has no pending requests. On the
+ // flush-on-hide/unload path the tab may be frozen before that turn
+ // runs, so starting the commit now shortens the window in which a
+ // freeze could strand the write. Guarded — not every engine
+ // implements the (Baseline) method.
+ if (typeof tx.commit === 'function') tx.commit();
};
} catch (err) {
reject(err instanceof Error ? err : new Error(String(err)));
diff --git a/packages/app/src/editor/clipboard/source-clipboard.ts b/packages/app/src/editor/clipboard/source-clipboard.ts
index eec41408b..3697fad38 100644
--- a/packages/app/src/editor/clipboard/source-clipboard.ts
+++ b/packages/app/src/editor/clipboard/source-clipboard.ts
@@ -59,6 +59,19 @@ import {
import { isMarkdown } from './is-markdown.ts';
import { installShiftTracker, pasteShiftHeld } from './shift-tracker.ts';
+/**
+ * Origin for the large-paste direct `Y.Text('source')` write. The chunked
+ * path bypasses CM6's dispatch and writes Y.Text itself, so it needs its own
+ * marked origin — a distinct `context.origin` keeps the write's provenance
+ * legible to any client-side observer that inspects origins, matching the
+ * source-mode lint-fix write's shape.
+ */
+const SOURCE_PASTE_ORIGIN = Object.freeze({
+ source: 'local' as const,
+ skipStoreHooks: false,
+ context: Object.freeze({ origin: 'source-paste' as const }),
+});
+
export interface SourceClipboardDeps {
ydoc: Y.Doc;
ytext: Y.Text;
@@ -368,6 +381,7 @@ function tryBranchDHtml(
// inserts incrementally.
void chunkedYTextInsert(deps.ydoc, deps.ytext, anchorIndex, markdown, {
resolveOffset,
+ origin: SOURCE_PASTE_ORIGIN,
}).catch((err) => {
handleChunkedInsertFailure({
view,
diff --git a/packages/app/src/editor/install-background-throttle-reporter.test.ts b/packages/app/src/editor/install-background-throttle-reporter.test.ts
new file mode 100644
index 000000000..714c73f6f
--- /dev/null
+++ b/packages/app/src/editor/install-background-throttle-reporter.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import { installBackgroundThrottleReporter } from './install-background-throttle-reporter';
+
+/** A fake pool: a mutable unsynced flag + a listener registry the test fires. */
+function makeFakePool(initial: boolean) {
+ let pending = initial;
+ const listeners = new Set<() => void>();
+ return {
+ setPending(next: boolean) {
+ pending = next;
+ for (const cb of listeners) cb();
+ },
+ hasAnyUnsyncedWork: () => pending,
+ addUnsyncedWorkListener: (cb: () => void) => {
+ listeners.add(cb);
+ return () => {
+ listeners.delete(cb);
+ };
+ },
+ listenerCount: () => listeners.size,
+ };
+}
+
+describe('installBackgroundThrottleReporter', () => {
+ it('seeds main with the current state on install', () => {
+ const pool = makeFakePool(false);
+ const reports: { hasPendingWork: boolean; enabled: boolean }[] = [];
+ installBackgroundThrottleReporter({
+ enabled: true,
+ hasAnyUnsyncedWork: pool.hasAnyUnsyncedWork,
+ addUnsyncedWorkListener: pool.addUnsyncedWorkListener,
+ report: (s) => reports.push(s),
+ });
+ expect(reports).toEqual([{ hasPendingWork: false, enabled: true }]);
+ });
+
+ it('reports the true↔false transitions and carries the kill-switch', () => {
+ const pool = makeFakePool(false);
+ const reports: { hasPendingWork: boolean; enabled: boolean }[] = [];
+ installBackgroundThrottleReporter({
+ enabled: true,
+ hasAnyUnsyncedWork: pool.hasAnyUnsyncedWork,
+ addUnsyncedWorkListener: pool.addUnsyncedWorkListener,
+ report: (s) => reports.push(s),
+ });
+ pool.setPending(true);
+ pool.setPending(false);
+ expect(reports).toEqual([
+ { hasPendingWork: false, enabled: true },
+ { hasPendingWork: true, enabled: true },
+ { hasPendingWork: false, enabled: true },
+ ]);
+ });
+
+ it('dedupes: a burst that does not cross the edge reports once', () => {
+ const pool = makeFakePool(false);
+ const reports: { hasPendingWork: boolean; enabled: boolean }[] = [];
+ installBackgroundThrottleReporter({
+ enabled: true,
+ hasAnyUnsyncedWork: pool.hasAnyUnsyncedWork,
+ addUnsyncedWorkListener: pool.addUnsyncedWorkListener,
+ report: (s) => reports.push(s),
+ });
+ pool.setPending(true);
+ pool.setPending(true); // still pending — no new report (keystroke burst)
+ pool.setPending(true);
+ expect(reports.filter((r) => r.hasPendingWork)).toHaveLength(1);
+ });
+
+ it('forwards the disabled kill-switch so main resolves the OS default', () => {
+ const pool = makeFakePool(true);
+ const reports: { hasPendingWork: boolean; enabled: boolean }[] = [];
+ installBackgroundThrottleReporter({
+ enabled: false,
+ hasAnyUnsyncedWork: pool.hasAnyUnsyncedWork,
+ addUnsyncedWorkListener: pool.addUnsyncedWorkListener,
+ report: (s) => reports.push(s),
+ });
+ expect(reports).toEqual([{ hasPendingWork: true, enabled: false }]);
+ });
+
+ it('stops reporting after unsubscribe', () => {
+ const pool = makeFakePool(false);
+ const reports: { hasPendingWork: boolean; enabled: boolean }[] = [];
+ const stop = installBackgroundThrottleReporter({
+ enabled: true,
+ hasAnyUnsyncedWork: pool.hasAnyUnsyncedWork,
+ addUnsyncedWorkListener: pool.addUnsyncedWorkListener,
+ report: (s) => reports.push(s),
+ });
+ stop();
+ expect(pool.listenerCount()).toBe(0);
+ pool.setPending(true);
+ expect(reports).toHaveLength(1); // only the install-time seed
+ });
+});
diff --git a/packages/app/src/editor/install-background-throttle-reporter.ts b/packages/app/src/editor/install-background-throttle-reporter.ts
new file mode 100644
index 000000000..200993377
--- /dev/null
+++ b/packages/app/src/editor/install-background-throttle-reporter.ts
@@ -0,0 +1,34 @@
+/**
+ * Reports a desktop window's aggregate unsynced-work state to the main process
+ * so main can key the window's Chromium background-throttling to it.
+ *
+ * Installed only in the Electron host (the caller gates on `window.okDesktop`).
+ * Dedupes to the true↔false edge: every keystroke bumps a provider's
+ * `unsyncedChanges`, so a typing burst collapses to one report when work
+ * begins and one when the doc finishes syncing.
+ */
+export interface BackgroundThrottleReporterDeps {
+ /** The `bridge.backgroundThrottle.enabled` kill-switch, resolved renderer-side. */
+ enabled: boolean;
+ /** Current aggregate: does any open doc hold unsynced work. */
+ hasAnyUnsyncedWork: () => boolean;
+ /** Subscribe to unsynced-work edges; returns an unsubscribe. */
+ addUnsyncedWorkListener: (cb: () => void) => () => void;
+ /** Push the signal to main (the `okDesktop` bridge). */
+ report: (signal: { hasPendingWork: boolean; enabled: boolean }) => void;
+}
+
+export function installBackgroundThrottleReporter(
+ deps: BackgroundThrottleReporterDeps,
+): () => void {
+ let lastReported: boolean | null = null;
+ const push = (): void => {
+ const hasPendingWork = deps.hasAnyUnsyncedWork();
+ if (hasPendingWork === lastReported) return;
+ lastReported = hasPendingWork;
+ deps.report({ hasPendingWork, enabled: deps.enabled });
+ };
+ // Seed main with the current state on install, then track edges.
+ push();
+ return deps.addUnsyncedWorkListener(push);
+}
diff --git a/packages/app/src/editor/install-editor-lifecycle-flush.test.ts b/packages/app/src/editor/install-editor-lifecycle-flush.test.ts
new file mode 100644
index 000000000..2e494bc7a
--- /dev/null
+++ b/packages/app/src/editor/install-editor-lifecycle-flush.test.ts
@@ -0,0 +1,138 @@
+import { describe, expect, it, vi } from 'vitest';
+import { installEditorLifecycleFlush } from './install-editor-lifecycle-flush';
+
+type Listener = (event: Event) => void;
+
+function makeFakeTarget() {
+ const listeners = new Map<string, Listener>();
+ return {
+ addEventListener(type: string, listener: Listener) {
+ listeners.set(type, listener);
+ },
+ removeEventListener(type: string) {
+ listeners.delete(type);
+ },
+ emit(type: string) {
+ listeners.get(type)?.(new Event(type));
+ },
+ has(type: string) {
+ return listeners.has(type);
+ },
+ };
+}
+
+function makeFakeDoc(visibilityState: DocumentVisibilityState) {
+ const target = makeFakeTarget();
+ return Object.assign(target, {
+ visibilityState,
+ setVisibility(v: DocumentVisibilityState) {
+ (this as { visibilityState: DocumentVisibilityState }).visibilityState = v;
+ },
+ });
+}
+
+describe('installEditorLifecycleFlush', () => {
+ it('flushes on pagehide', () => {
+ const onHide = vi.fn();
+ const onVisible = vi.fn();
+ const win = makeFakeTarget();
+ const doc = makeFakeDoc('visible');
+ installEditorLifecycleFlush({ onHide, onVisible, win, doc });
+
+ win.emit('pagehide');
+
+ expect(onHide).toHaveBeenCalledTimes(1);
+ expect(onVisible).not.toHaveBeenCalled();
+ });
+
+ it('flushes on visibilitychange when hidden', () => {
+ const onHide = vi.fn();
+ const onVisible = vi.fn();
+ const win = makeFakeTarget();
+ const doc = makeFakeDoc('hidden');
+ installEditorLifecycleFlush({ onHide, onVisible, win, doc });
+
+ doc.emit('visibilitychange');
+
+ expect(onHide).toHaveBeenCalledTimes(1);
+ expect(onVisible).not.toHaveBeenCalled();
+ });
+
+ it('resyncs on visibilitychange when visible', () => {
+ const onHide = vi.fn();
+ const onVisible = vi.fn();
+ const win = makeFakeTarget();
+ const doc = makeFakeDoc('visible');
+ installEditorLifecycleFlush({ onHide, onVisible, win, doc });
+
+ doc.emit('visibilitychange');
+
+ expect(onVisible).toHaveBeenCalledTimes(1);
+ expect(onHide).not.toHaveBeenCalled();
+ });
+
+ it('runs the hide work once for a real tab close, not once per listener', () => {
+ const onHide = vi.fn();
+ const onVisible = vi.fn();
+ const win = makeFakeTarget();
+ const doc = makeFakeDoc('visible');
+ installEditorLifecycleFlush({ onHide, onVisible, win, doc });
+
+ // The close sequence browsers actually emit: visibilitychange → hidden,
+ // then pagehide. Both listeners exist because neither fires reliably in
+ // every teardown, but one close is one hide — otherwise every open doc
+ // gets two forceSync()s and two concurrent full-state IDB flushes.
+ doc.setVisibility('hidden');
+ doc.emit('visibilitychange');
+ win.emit('pagehide');
+
+ expect(onHide).toHaveBeenCalledTimes(1);
+ });
+
+ it('re-arms the hide after the tab becomes visible again', () => {
+ const onHide = vi.fn();
+ const onVisible = vi.fn();
+ const win = makeFakeTarget();
+ const doc = makeFakeDoc('visible');
+ installEditorLifecycleFlush({ onHide, onVisible, win, doc });
+
+ doc.setVisibility('hidden');
+ doc.emit('visibilitychange');
+ expect(onHide).toHaveBeenCalledTimes(1);
+
+ // A restored page (tab switch back, bfcache restore) hides again normally.
+ doc.setVisibility('visible');
+ doc.emit('visibilitychange');
+ doc.setVisibility('hidden');
+ doc.emit('visibilitychange');
+
+ expect(onVisible).toHaveBeenCalledTimes(1);
+ expect(onHide).toHaveBeenCalledTimes(2);
+ });
+
+ it('removes both listeners on uninstall', () => {
+ const onHide = vi.fn();
+ const onVisible = vi.fn();
+ const win = makeFakeTarget();
+ const doc = makeFakeDoc('hidden');
+ const uninstall = installEditorLifecycleFlush({ onHide, onVisible, win, doc });
+
+ uninstall();
+
+ expect(win.has('pagehide')).toBe(false);
+ expect(doc.has('visibilitychange')).toBe(false);
+ win.emit('pagehide');
+ doc.emit('visibilitychange');
+ expect(onHide).not.toHaveBeenCalled();
+ expect(onVisible).not.toHaveBeenCalled();
+ });
+
+ it('is a safe no-op when globals are absent', () => {
+ const onHide = vi.fn();
+ const onVisible = vi.fn();
+ // Neither win nor doc provided and (in the node test env) no real globals.
+ const uninstall = installEditorLifecycleFlush({ onHide, onVisible });
+ expect(() => uninstall()).not.toThrow();
+ expect(onHide).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/app/src/editor/install-editor-lifecycle-flush.ts b/packages/app/src/editor/install-editor-lifecycle-flush.ts
new file mode 100644
index 000000000..3167d84e0
--- /dev/null
+++ b/packages/app/src/editor/install-editor-lifecycle-flush.ts
@@ -0,0 +1,54 @@
+/**
+ * Attach the tab-lifecycle listeners that drive background flush / resync.
+ *
+ * Mirrors the client-log-forwarder's hide handling: listen on BOTH `pagehide`
+ * (fires on real unload/bfcache where `visibilitychange` may not) and
+ * `visibilitychange → hidden`, and fire `onVisible` when the tab returns. The
+ * `win`/`doc` are injectable so the unit test can emit synthetic events without
+ * jsdom; production falls back to the real globals.
+ *
+ * The two listeners overlap: closing a tab fires `visibilitychange → hidden`
+ * AND THEN `pagehide`, so a naive fan-out runs the hide work twice per real
+ * close (two `forceSync()`s and two concurrent full-state IDB flushes per open
+ * doc). `onHide` is therefore edge-triggered — once per hidden transition,
+ * re-armed by the next `visible` (which is also what a bfcache restore
+ * delivers, so a restored page hides again normally).
+ */
+export interface EditorLifecycleFlushDeps {
+ onHide: () => void;
+ onVisible: () => void;
+ win?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+ doc?: Pick<Document, 'addEventListener' | 'removeEventListener'> & {
+ readonly visibilityState: DocumentVisibilityState;
+ };
+}
+
+export function installEditorLifecycleFlush(deps: EditorLifecycleFlushDeps): () => void {
+ const win = deps.win ?? (typeof window !== 'undefined' ? window : undefined);
+ const doc = deps.doc ?? (typeof document !== 'undefined' ? document : undefined);
+ if (win === undefined || doc === undefined) return () => {};
+
+ let hidden = false;
+ const fireHide = (): void => {
+ if (hidden) return;
+ hidden = true;
+ deps.onHide();
+ };
+
+ const onPageHide = (): void => fireHide();
+ const onVisibility = (): void => {
+ if (doc.visibilityState === 'hidden') fireHide();
+ else if (doc.visibilityState === 'visible') {
+ hidden = false;
+ deps.onVisible();
+ }
+ };
+
+ win.addEventListener('pagehide', onPageHide as (event: Event) => void);
+ doc.addEventListener('visibilitychange', onVisibility);
+
+ return () => {
+ win.removeEventListener('pagehide', onPageHide as (event: Event) => void);
+ doc.removeEventListener('visibilitychange', onVisibility);
+ };
+}
diff --git a/packages/app/src/editor/provider-pool-cross-tab-replay.test.ts b/packages/app/src/editor/provider-pool-cross-tab-replay.test.ts
new file mode 100644
index 000000000..577146e17
--- /dev/null
+++ b/packages/app/src/editor/provider-pool-cross-tab-replay.test.ts
@@ -0,0 +1,186 @@
+/**
+ * Cross-tab exactly-once for the durable replay outbox.
+ *
+ * The outbox record is keyed `(branch, docName)` with no tab component, so
+ * every same-origin tab (a browser preview and the desktop shell both sit on
+ * `127.0.0.1:PORT`) sees ONE record. That record is therefore the cross-tab
+ * claim token: whichever tab consumes it owns the replay and the others must
+ * stand down.
+ *
+ * They must stand down because `replayBufferedContent` is not re-entrant. It
+ * decides which CRDT surface holds the un-delivered edit by asking which
+ * surface still matches the server — so once another tab has landed the
+ * recovered content on the server, this tab's surfaces read INVERTED: the
+ * surface that "matches base" is now the stale one, and applying anyway
+ * splices the pre-recycle bytes back over the content just recovered. The
+ * failure mode is not a duplicate, it is a SILENT REVERT of recovered work.
+ *
+ * Two pools against the process-global `fake-indexeddb` stand in for two tabs;
+ * providers point at a dead URL and are driven by synthetic `synced` emits, so
+ * the replay path runs exactly as it does in production without a server.
+ */
+import { randomUUID } from 'node:crypto';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterEach, describe, expect, it } from 'vitest';
+import * as Y from 'yjs';
+import { UNKNOWN_BRANCH_SENTINEL } from './client-persistence';
+import { ProviderPool } from './provider-pool';
+import { readReplayOutboxEntry, writeReplayOutboxEntry } from './replay-outbox';
+
+const DUMMY_WS = 'ws://localhost:1/collab';
+
+function uniqueDocName(): string {
+ return `pp-cross-tab-${randomUUID()}`;
+}
+
+/**
+ * A pre-recycle state whose un-delivered edit lives in `Y.Text('source')` with
+ * an empty fragment — the unacked source-mode shape. Against an empty fresh
+ * doc the replay recovers it; against a doc that ALREADY has it, the surface
+ * attribution flips and a re-apply would splice the empty fragment body back
+ * over the recovered text.
+ */
+function buildSourceOnlyState(text: string): { delta: Uint8Array; fullState: Uint8Array } {
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, text);
+ const fullState = Y.encodeStateAsUpdate(doc);
+ const delta = Y.encodeStateAsUpdate(doc, Y.encodeStateVector(new Y.Doc()));
+ doc.destroy();
+ return { delta, fullState };
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2_000): Promise<boolean> {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ if (predicate()) return true;
+ await wait(10);
+ }
+ return predicate();
+}
+
+const pools: ProviderPool[] = [];
+
+function newPool(): ProviderPool {
+ const pool = new ProviderPool(3, DUMMY_WS);
+ pools.push(pool);
+ return pool;
+}
+
+afterEach(() => {
+ while (pools.length > 0) pools.pop()?.dispose();
+});
+
+describe('ProviderPool cross-tab replay claim', () => {
+ it('a tab whose RAM buffer lost the shared claim does not revert the recovered content', async () => {
+ const docName = uniqueDocName();
+ const marker = `cross-tab-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+
+ // Tab A: mid-recycle. Its RAM buffer holds the un-delivered edit and the
+ // durable mirror has committed, exactly as `handleServerInstanceMismatch`
+ // leaves things.
+ expect(
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState }),
+ ).toBe(true);
+ const tabA = newPool();
+ const entryA = tabA.open(docName);
+ if (!entryA) throw new Error('expected entry for tab A');
+ entryA.observerCleanup = () => {};
+ tabA.__test_seedBufferedUpdate(docName, delta, {
+ fullState,
+ durable: true,
+ branch: UNKNOWN_BRANCH_SENTINEL,
+ });
+
+ // Tab B opens the same doc with no RAM buffer of its own, reads the shared
+ // record, and recovers the edit.
+ const tabB = newPool();
+ const entryB = tabB.open(docName);
+ if (!entryB) throw new Error('expected entry for tab B');
+ entryB.observerCleanup = () => {};
+ entryB.provider.emit('synced', { state: true });
+ expect(
+ await waitFor(() => entryB.provider.document.getText('source').toString() === marker),
+ ).toBe(true);
+ expect(await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)).toBeNull();
+
+ // The recovered content reaches tab A the ordinary way (server → peers).
+ entryA.provider.document.getText('source').insert(0, marker);
+
+ // Now tab A's own replay fires. Its pre-recycle replica has ytext=marker
+ // and an EMPTY fragment; the server now also has `marker`, so the surface
+ // comparison would read the empty fragment as "the base the server
+ // rebuilt" and splice it over the recovery — wiping the doc. The lost
+ // claim is what stops it.
+ entryA.provider.emit('synced', { state: true });
+ // `source === marker` is already true from the peer delivery above, so it
+ // cannot be the wait predicate (it would pass before tab A's replay even
+ // fires). Wait on the positive completion signal — tab A's replay running
+ // to completion and standing down, which consumes its RAM buffer — then
+ // assert the replay left the recovery intact rather than splicing over it.
+ expect(await waitFor(() => tabA.__test_hasBufferedUpdate(docName) === false)).toBe(true);
+ expect(entryA.provider.document.getText('source').toString()).toBe(marker);
+ });
+
+ it('two fresh tabs racing one record: the loser leaves the recovery alone', async () => {
+ const docName = uniqueDocName();
+ const marker = `race-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ // Neither tab has a RAM buffer: both are post-crash reopens racing the one
+ // durable record.
+ const tabA = newPool();
+ const entryA = tabA.open(docName);
+ const tabB = newPool();
+ const entryB = tabB.open(docName);
+ if (!entryA || !entryB) throw new Error('expected entries');
+ entryA.observerCleanup = () => {};
+ entryB.observerCleanup = () => {};
+
+ entryA.provider.emit('synced', { state: true });
+ entryB.provider.emit('synced', { state: true });
+ // Exactly one tab claims the single durable record and replays; the other
+ // reads it already-consumed and stands down. The consume is an atomic
+ // single-record claim, so once one tab shows the marker the post-state is
+ // stable — wait for that instead of a fixed sleep.
+ expect(
+ await waitFor(
+ () =>
+ [entryA, entryB].filter(
+ (e) => e.provider.document.getText('source').toString() === marker,
+ ).length === 1,
+ ),
+ ).toBe(true);
+
+ const textA = entryA.provider.document.getText('source').toString();
+ const textB = entryB.provider.document.getText('source').toString();
+ // Exactly one tab replays. The other leaves its doc untouched rather than
+ // inserting a second copy — these docs are not yet peers, so a duplicate
+ // would show up as the marker landing on both.
+ expect([textA, textB].filter((t) => t === marker)).toHaveLength(1);
+ expect([textA, textB].filter((t) => t === '')).toHaveLength(1);
+ expect(await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)).toBeNull();
+ });
+
+ it('a RAM-only buffer (no durable mirror) still replays', async () => {
+ const docName = uniqueDocName();
+ const marker = `ram-only-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+
+ // Over-cap docs, failed durable writes, and engines without
+ // `indexedDB.databases()` all leave a buffer with no token. Nothing to
+ // claim must never read as "someone else claimed it".
+ const pool = newPool();
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ pool.__test_seedBufferedUpdate(docName, delta, { fullState, durable: false });
+
+ entry.provider.emit('synced', { state: true });
+
+ expect(
+ await waitFor(() => entry.provider.document.getText('source').toString() === marker),
+ ).toBe(true);
+ });
+});
diff --git a/packages/app/src/editor/provider-pool-durable-replay.test.ts b/packages/app/src/editor/provider-pool-durable-replay.test.ts
new file mode 100644
index 000000000..140802c3a
--- /dev/null
+++ b/packages/app/src/editor/provider-pool-durable-replay.test.ts
@@ -0,0 +1,179 @@
+/**
+ * Unit tests for durable replay-outbox recovery in ProviderPool.
+ *
+ * These construct a real HocuspocusProvider against a dead URL (never
+ * connects) and drive the replay listener via a synthetic `synced` emit,
+ * against the globally-installed `fake-indexeddb`. They cover the reopen path:
+ * a fresh tab (no in-memory buffer) recovers an unsynced edit from the durable
+ * outbox, consumes it before applying (so a reopen never re-applies), and
+ * never crashes on a corrupt buffer.
+ *
+ * The content-level replay against a REAL server (Observer B derive, real
+ * `theirs` comparison) is exercised in
+ * `tests/integration/replay-outbox-durable.test.ts`.
+ */
+import { randomUUID } from 'node:crypto';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import * as Y from 'yjs';
+import { UNKNOWN_BRANCH_SENTINEL } from './client-persistence';
+import { ProviderPool } from './provider-pool';
+import { readReplayOutboxEntry, writeReplayOutboxEntry } from './replay-outbox';
+
+// Spy-wrap the REAL outbox module (no behavior change) so the replay
+// listener's own invocation count is observable. Its first act on a fresh tab
+// is the outbox read, which makes that count the direct reading of "how many
+// times did the replay run".
+vi.mock('./replay-outbox', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('./replay-outbox')>();
+ return {
+ ...actual,
+ readReplayOutboxEntry: vi.fn(actual.readReplayOutboxEntry),
+ consumeReplayOutboxEntry: vi.fn(actual.consumeReplayOutboxEntry),
+ };
+});
+
+const DUMMY_WS = 'ws://localhost:1/collab';
+
+function uniqueDocName(): string {
+ return `pp-durable-${randomUUID()}`;
+}
+
+/**
+ * Build a source-only pre-recycle state: an unsynced edit lives in
+ * `Y.Text('source')`, the XML fragment is empty. Against an empty fresh doc
+ * (the unit tier's dead-URL provider), the content-level replay's fragment-
+ * clean branch splices the recovered source in.
+ */
+function buildSourceOnlyState(text: string): { delta: Uint8Array; fullState: Uint8Array } {
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, text);
+ const fullState = Y.encodeStateAsUpdate(doc);
+ const delta = Y.encodeStateAsUpdate(doc, Y.encodeStateVector(new Y.Doc()));
+ doc.destroy();
+ return { delta, fullState };
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2_000): Promise<boolean> {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ if (predicate()) return true;
+ await wait(10);
+ }
+ return predicate();
+}
+
+let pool: ProviderPool;
+
+afterEach(() => {
+ pool?.dispose();
+});
+
+describe('ProviderPool durable replay outbox', () => {
+ it('recovers an unsynced edit from the durable outbox on a fresh open', async () => {
+ const docName = uniqueDocName();
+ const marker = `durable-recovered-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ entry.provider.emit('synced', { state: true });
+
+ const recovered = await waitFor(() =>
+ entry.provider.document.getText('source').toString().includes(marker),
+ );
+ expect(recovered).toBe(true);
+ // Consume-first: the durable outbox is gone after recovery.
+ expect(await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)).toBeNull();
+ });
+
+ it('does not re-apply after a completed recovery (exactly-once across reopen)', async () => {
+ const docName = uniqueDocName();
+ const marker = `once-only-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ entry.provider.emit('synced', { state: true });
+ await waitFor(() => entry.provider.document.getText('source').toString().includes(marker));
+ pool.dispose();
+
+ // A second fresh tab: the outbox was consumed, so no replay fires and the
+ // fresh doc stays empty — the recovered content is NOT re-inserted.
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry2 = pool.open(docName);
+ if (!entry2) throw new Error('expected entry2');
+ entry2.observerCleanup = () => {};
+ entry2.provider.emit('synced', { state: true });
+ await wait(80);
+ expect(entry2.provider.document.getText('source').toString()).toBe('');
+ expect(await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)).toBeNull();
+ });
+
+ it('a second `synced` never re-enters the replay', async () => {
+ const docName = uniqueDocName();
+ const marker = `single-fire-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+
+ vi.mocked(readReplayOutboxEntry).mockClear();
+
+ // A reconnect can re-emit `synced` while the first replay is still inside
+ // its awaits — the record is not consumed yet, so a second entrant would
+ // read the SAME buffer and race the consume the design exists to make
+ // single-fire. The listener detaches itself synchronously before the first
+ // await for exactly this reason; both emits land in that window.
+ entry.provider.emit('synced', { state: true });
+ entry.provider.emit('synced', { state: true });
+
+ const recovered = await waitFor(() =>
+ entry.provider.document.getText('source').toString().includes(marker),
+ );
+ expect(recovered).toBe(true);
+ await wait(80);
+
+ expect(vi.mocked(readReplayOutboxEntry)).toHaveBeenCalledTimes(1);
+ // And the user-visible outcome: one copy of the recovered edit.
+ expect(entry.provider.document.getText('source').toString()).toBe(marker);
+ });
+
+ it('consumes the outbox and does not crash on a corrupt buffer', async () => {
+ const docName = uniqueDocName();
+ // Valid record shape, but a truncated Yjs update — the guarded apply must
+ // not crash the client, and the outbox is consumed before the apply is
+ // attempted (consume-first) so it can never re-fire.
+ const real = buildSourceOnlyState('some real content that will be truncated');
+ const truncated = real.fullState.slice(0, 4);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, {
+ delta: truncated,
+ fullState: truncated,
+ });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ entry.provider.emit('synced', { state: true });
+
+ // The outbox is consumed regardless of the apply outcome (consume-first).
+ let consumed = false;
+ for (let i = 0; i < 60 && !consumed; i += 1) {
+ consumed = (await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)) === null;
+ if (!consumed) await wait(10);
+ }
+ expect(consumed).toBe(true);
+ // No meaningful content was fabricated from the corrupt bytes.
+ expect(entry.provider.document.getText('source').toString()).toBe('');
+ });
+});
diff --git a/packages/app/src/editor/provider-pool-flush-on-hide.test.ts b/packages/app/src/editor/provider-pool-flush-on-hide.test.ts
new file mode 100644
index 000000000..103d88942
--- /dev/null
+++ b/packages/app/src/editor/provider-pool-flush-on-hide.test.ts
@@ -0,0 +1,292 @@
+/**
+ * Pool-level contract for the background-flush / resync-on-visible
+ * mechanism: `flushOnHide()` pushes each pending doc's work to the server
+ * and commits its IDB cache; `resyncOnVisible()` re-runs the sync
+ * handshake; the `bridge.flushOnHide.enabled` kill-switch makes both inert.
+ *
+ * `forceSync` (server round-trip) and `flushFullState` (IDB commit) are the
+ * two outgoing boundary commands the mechanism issues, so they are the
+ * spy targets here. The real "delta reaches the SERVER" outcome is proven
+ * end-to-end against a live server in the integration tier; this suite pins
+ * the pool's gating logic deterministically without wall-clock waits.
+ */
+import { randomUUID } from 'node:crypto';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { ClientPersistenceProvider } from './client-persistence';
+import { ProviderPool } from './provider-pool';
+
+type OpenEntry = NonNullable<ReturnType<ProviderPool['open']>>;
+
+function openEntry(p: ProviderPool, docName: string): OpenEntry {
+ const entry = p.open(docName);
+ if (entry === null) throw new Error(`expected open("${docName}") to return an entry`);
+ return entry;
+}
+
+const DUMMY_WS = 'ws://localhost:1/collab';
+const TEST_SERVER_INSTANCE_ID = 'flush-on-hide-epoch';
+
+function uniqueDocName(): string {
+ return `flush-hide-${randomUUID()}`;
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2_000): Promise<boolean> {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ if (predicate()) return true;
+ await wait(10);
+ }
+ return predicate();
+}
+
+async function awaitPersistence(entry: {
+ persistence: ClientPersistenceProvider | null;
+}): Promise<ClientPersistenceProvider> {
+ await waitFor(() => entry.persistence !== null);
+ if (entry.persistence === null) throw new Error('expected persistence to attach');
+ return entry.persistence;
+}
+
+let pool: ProviderPool;
+afterEach(() => {
+ pool?.dispose();
+});
+
+describe('ProviderPool background flush-on-hide', () => {
+ it('force-syncs the server AND commits IDB for a doc with a pending delta', async () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ const persistence = await awaitPersistence(entry);
+
+ // A local WYSIWYG-shaped edit bumps unsyncedChanges (the "pending delta"
+ // precondition) — the provider is never connected on DUMMY_WS, so the
+ // edit stays unacked.
+ entry.provider.document.getText('source').insert(0, 'pending edit');
+ expect(entry.provider.unsyncedChanges).toBeGreaterThan(0);
+
+ const forceSyncSpy = vi.spyOn(entry.provider, 'forceSync').mockImplementation(() => {});
+ const flushSpy = vi.spyOn(persistence, 'flushFullState').mockResolvedValue(undefined);
+
+ pool.flushOnHide();
+
+ expect(forceSyncSpy).toHaveBeenCalledTimes(1);
+ expect(flushSpy).toHaveBeenCalledTimes(1);
+ });
+
+ it('is inert when the kill-switch is off (no force-sync, no IDB commit)', async () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ const persistence = await awaitPersistence(entry);
+ entry.provider.document.getText('source').insert(0, 'pending edit');
+ expect(entry.provider.unsyncedChanges).toBeGreaterThan(0);
+
+ const forceSyncSpy = vi.spyOn(entry.provider, 'forceSync').mockImplementation(() => {});
+ const flushSpy = vi.spyOn(persistence, 'flushFullState').mockResolvedValue(undefined);
+
+ pool.setFlushOnHideEnabled(false);
+ pool.flushOnHide();
+
+ expect(forceSyncSpy).not.toHaveBeenCalled();
+ expect(flushSpy).not.toHaveBeenCalled();
+ });
+
+ it('skips docs with no pending delta', () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ // No edit — unsyncedChanges stays 0.
+ expect(entry.provider.unsyncedChanges).toBe(0);
+
+ const forceSyncSpy = vi.spyOn(entry.provider, 'forceSync').mockImplementation(() => {});
+ pool.flushOnHide();
+
+ expect(forceSyncSpy).not.toHaveBeenCalled();
+ });
+
+ it('resyncOnVisible re-runs the sync handshake for active docs', () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ entry.provider.emit('synced', { state: true });
+ // resync pulls server-side changes the tab may have missed while hidden,
+ // so it fires regardless of local pending state.
+ const forceSyncSpy = vi.spyOn(entry.provider, 'forceSync').mockImplementation(() => {});
+
+ pool.resyncOnVisible();
+
+ expect(forceSyncSpy).toHaveBeenCalledTimes(1);
+ });
+
+ it('resyncOnVisible skips a disconnected doc rather than latching it dirty', () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ entry.provider.emit('synced', { state: true });
+ entry.provider.emit('status', { status: 'disconnected' });
+
+ // Precondition: the doc is CLEAN. The real `forceSync()` runs
+ // `resetUnsyncedChanges()`, which sets unsyncedChanges to 1 unconditionally
+ // and only returns to 0 when the server answers — so calling it here would
+ // pin a clean doc dirty for the whole disconnect. Un-mocked on purpose:
+ // the latch is the behavior under test, not the call.
+ expect(entry.provider.unsyncedChanges).toBe(0);
+
+ pool.resyncOnVisible();
+
+ expect(entry.provider.unsyncedChanges).toBe(0);
+ expect(pool.hasAnyUnsyncedWork()).toBe(false);
+ });
+
+ it('resyncOnVisible is inert when the kill-switch is off', () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ entry.provider.emit('synced', { state: true });
+ const forceSyncSpy = vi.spyOn(entry.provider, 'forceSync').mockImplementation(() => {});
+
+ pool.setFlushOnHideEnabled(false);
+ pool.resyncOnVisible();
+
+ expect(forceSyncSpy).not.toHaveBeenCalled();
+ });
+
+ it('emits a structured recovery event when the unload IDB flush rejects (never silent)', async () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ const persistence = await awaitPersistence(entry);
+ entry.provider.document.getText('source').insert(0, 'pending edit');
+ expect(entry.provider.unsyncedChanges).toBeGreaterThan(0);
+
+ vi.spyOn(entry.provider, 'forceSync').mockImplementation(() => {});
+ // The unload path's effective durability is this IDB commit; a rejection
+ // here (quota, aborted tx) loses edits, so it must be observable — not
+ // swallowed by an empty catch.
+ vi.spyOn(persistence, 'flushFullState').mockRejectedValue(
+ new Error('flushFullState transaction aborted'),
+ );
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ pool.flushOnHide();
+ await waitFor(() =>
+ warnSpy.mock.calls.some((c) => String(c[0]).includes('ok-pool-flush-on-hide-failed')),
+ );
+ const emitted = warnSpy.mock.calls
+ .map((c) => String(c[0]))
+ .find((s) => s.includes('ok-pool-flush-on-hide-failed'));
+ warnSpy.mockRestore();
+
+ expect(emitted).toBeDefined();
+ // Content-free breadcrumb: names the doc + error name, never document content.
+ expect(emitted).toContain(docName);
+ expect(emitted).toContain('flushFullState transaction aborted');
+ });
+
+ it('flushOnHide stands down while a mismatch recycle is in flight', async () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ const persistence = await awaitPersistence(entry);
+ entry.provider.document.getText('source').insert(0, 'pending edit');
+
+ const forceSyncSpy = vi.spyOn(entry.provider, 'forceSync').mockImplementation(() => {});
+ const flushSpy = vi.spyOn(persistence, 'flushFullState').mockResolvedValue(undefined);
+
+ // Planted positive: this doc IS flush-eligible right now, so a later
+ // "not called" can only come from the recycle guard.
+ pool.flushOnHide();
+ expect(forceSyncSpy).toHaveBeenCalledTimes(1);
+ forceSyncSpy.mockClear();
+ flushSpy.mockClear();
+
+ // Open the recycle window. The mismatch flow captures this delta into the
+ // durable outbox and owns re-delivery; a concurrent forceSync would race
+ // the very epoch being recycled away.
+ entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
+
+ pool.flushOnHide();
+
+ expect(forceSyncSpy).not.toHaveBeenCalled();
+ expect(flushSpy).not.toHaveBeenCalled();
+
+ await pool.awaitMismatchSettled();
+ });
+
+ it('a throwing unsynced-work listener does not stop the next one or escape the provider event', async () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ await awaitPersistence(entry);
+
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ let reachedSecond = 0;
+ // Insertion order is iteration order, so the thrower runs first.
+ const offA = pool.addUnsyncedWorkListener(() => {
+ throw new Error('ipc boom');
+ });
+ const offB = pool.addUnsyncedWorkListener(() => {
+ reachedSecond += 1;
+ });
+
+ try {
+ // Driven the way production drives it: a provider unsynced-work edge.
+ expect(() => entry.provider.emit('unsyncedChanges', { number: 1 })).not.toThrow();
+ expect(reachedSecond).toBe(1);
+ // Reported, not swallowed.
+ expect(
+ warn.mock.calls.some(([arg]) =>
+ String(arg).includes('ok-pool-unsynced-work-listener-threw'),
+ ),
+ ).toBe(true);
+ } finally {
+ offA();
+ offB();
+ warn.mockRestore();
+ }
+ });
+
+ it('resyncOnVisible stands down while a mismatch recycle is in flight', async () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const docName = uniqueDocName();
+ const entry = openEntry(pool, docName);
+ pool.setActive(docName);
+ await awaitPersistence(entry);
+ entry.provider.emit('synced', { state: true });
+
+ const forceSyncSpy = vi.spyOn(entry.provider, 'forceSync').mockImplementation(() => {});
+
+ // Planted positive: this doc IS resync-eligible right now, so a later
+ // "not called" can only come from the recycle guard.
+ pool.resyncOnVisible();
+ expect(forceSyncSpy).toHaveBeenCalledTimes(1);
+ forceSyncSpy.mockClear();
+
+ // Open the recycle window. Re-syncing here races the epoch being recycled
+ // away and latches unsyncedChanges on a provider about to be destroyed.
+ entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
+
+ pool.resyncOnVisible();
+
+ expect(forceSyncSpy).not.toHaveBeenCalled();
+
+ await pool.awaitMismatchSettled();
+ });
+});
diff --git a/packages/app/src/editor/provider-pool-replay-discard.test.ts b/packages/app/src/editor/provider-pool-replay-discard.test.ts
new file mode 100644
index 000000000..41ca2a11f
--- /dev/null
+++ b/packages/app/src/editor/provider-pool-replay-discard.test.ts
@@ -0,0 +1,166 @@
+/**
+ * Discard semantics for the replay buffer once it has a DURABLE half.
+ *
+ * `close()` and `clearBufferedUpdates()` both exist to make a pending replay
+ * buffer go away: the first because the user closed the doc (or the LRU evicted
+ * it) and resurrecting the edit later would surprise them, the second because
+ * an edit authored against branch A must never land on branch B. Dropping only
+ * the in-memory copy would leave the outbox record behind as an immortal
+ * orphan that replays on the next open — reintroducing, through the durable
+ * layer, exactly the leak each method was written to close.
+ *
+ * Also covers the other side of the same coin: a buffer with NO durable mirror
+ * must not be gated on a token that was never written.
+ */
+import { randomUUID } from 'node:crypto';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import * as Y from 'yjs';
+import { UNKNOWN_BRANCH_SENTINEL } from './client-persistence';
+import { ProviderPool } from './provider-pool';
+import { readReplayOutboxEntry, writeReplayOutboxEntry } from './replay-outbox';
+
+const DUMMY_WS = 'ws://localhost:1/collab';
+
+function uniqueDocName(): string {
+ return `pp-discard-${randomUUID()}`;
+}
+
+function buildSourceOnlyState(text: string): { delta: Uint8Array; fullState: Uint8Array } {
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, text);
+ const fullState = Y.encodeStateAsUpdate(doc);
+ const delta = Y.encodeStateAsUpdate(doc, Y.encodeStateVector(new Y.Doc()));
+ doc.destroy();
+ return { delta, fullState };
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2_000): Promise<boolean> {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ if (predicate()) return true;
+ await wait(10);
+ }
+ return predicate();
+}
+
+let pool: ProviderPool;
+afterEach(() => {
+ pool?.dispose();
+ vi.restoreAllMocks();
+});
+
+describe('ProviderPool replay-buffer discard reaches the durable mirror', () => {
+ it('close() drops the durable record, so a reopen replays nothing', async () => {
+ const docName = uniqueDocName();
+ const marker = `closed-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ pool.__test_seedBufferedUpdate(docName, delta, {
+ fullState,
+ durable: true,
+ branch: UNKNOWN_BRANCH_SENTINEL,
+ });
+
+ pool.close(docName);
+
+ expect(pool.__test_hasBufferedUpdate(docName)).toBe(false);
+ // The durable half has to go too, or the next open resurrects the edit.
+ await vi.waitFor(async () => {
+ expect(await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)).toBeNull();
+ });
+
+ // End-to-end: reopening replays nothing.
+ const reopened = pool.open(docName);
+ if (!reopened) throw new Error('expected reopened entry');
+ reopened.observerCleanup = () => {};
+ reopened.provider.emit('synced', { state: true });
+ await wait(120);
+ expect(reopened.provider.document.getText('source').toString()).toBe('');
+ });
+
+ it('clearBufferedUpdates() drops the durable record under the branch it was captured on', async () => {
+ const docName = uniqueDocName();
+ const authoringBranch = `feature-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState('branch-a edit');
+ await writeReplayOutboxEntry(authoringBranch, docName, { delta, fullState });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ // The branch-switch flow runs AFTER the observed branch has already moved,
+ // so the discard has to use the branch the buffer was captured on — not
+ // whatever the pool observes now (here: the unknown-branch sentinel).
+ pool.__test_seedBufferedUpdate(docName, delta, {
+ fullState,
+ durable: true,
+ branch: authoringBranch,
+ });
+
+ pool.clearBufferedUpdates();
+
+ expect(pool.__test_bufferedUpdatesSize()).toBe(0);
+ await vi.waitFor(async () => {
+ expect(await readReplayOutboxEntry(authoringBranch, docName)).toBeNull();
+ });
+ });
+
+ it('a buffer with no durable mirror replays even when the outbox probe throws', async () => {
+ const docName = uniqueDocName();
+ const marker = `ram-only-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ // Over-cap doc / failed durable write: RAM is the ONLY carrier.
+ pool.__test_seedBufferedUpdate(docName, delta, { fullState, durable: false });
+
+ // Any consume attempt would now throw. The replay must not attempt one:
+ // the RAM copy is already deleted by the time a consume could fail, and
+ // there is no outbox record to recover from, so bailing here drops the
+ // edit inside the mechanism that exists to preserve it.
+ vi.spyOn(indexedDB, 'databases').mockRejectedValue(new Error('databases() unavailable'));
+
+ entry.provider.emit('synced', { state: true });
+
+ expect(
+ await waitFor(() => entry.provider.document.getText('source').toString() === marker),
+ ).toBe(true);
+ });
+
+ it('reports the in-process loss when the entry is replaced mid-consume', async () => {
+ const docName = uniqueDocName();
+ const { delta, fullState } = buildSourceOnlyState(`abandoned-${randomUUID()}`);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ pool.__test_seedBufferedUpdate(docName, delta, {
+ fullState,
+ durable: true,
+ branch: UNKNOWN_BRANCH_SENTINEL,
+ });
+
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ // Fire the replay, then yank the entry out from under it while the consume
+ // is still awaiting. Both carriers are gone at that point, so the bail is a
+ // real loss and has to be loud — the sibling failure arms all emit.
+ entry.provider.emit('synced', { state: true });
+ pool.close(docName);
+
+ await vi.waitFor(() => {
+ const events = warn.mock.calls
+ .map(([first]) => (typeof first === 'string' ? first : ''))
+ .filter((line) => line.includes('ok-buffer-replay-abandoned'));
+ expect(events).not.toHaveLength(0);
+ });
+ });
+});
diff --git a/packages/app/src/editor/provider-pool-replay-diverged.test.ts b/packages/app/src/editor/provider-pool-replay-diverged.test.ts
new file mode 100644
index 000000000..06dd2778a
--- /dev/null
+++ b/packages/app/src/editor/provider-pool-replay-diverged.test.ts
@@ -0,0 +1,160 @@
+/**
+ * The divergence bail in the content-level replay's surface attribution.
+ *
+ * `replayBufferedContent` recovers a pre-recycle edit by deciding which CRDT
+ * surface holds it: whichever surface still MATCHES the fresh server content is
+ * the base, and the other one carries the edit. When NEITHER surface matches,
+ * that inference is unavailable — the buffer was captured against a document
+ * state the server has since moved past — and splicing either candidate would
+ * overwrite live content with an aged snapshot. The bail refuses the splice and
+ * emits `ok-buffer-replay-diverged`, leaving the caller's delta fallback (which
+ * merges rather than replaces) as the terminal path.
+ *
+ * Every other replay test builds its replica against an EMPTY provider doc, so
+ * the fragment surface always compares clean and the third arm never runs. Both
+ * arms here share one buffer and vary only what the provider holds: unmoved
+ * content splices, moved content bails.
+ */
+import { randomUUID } from 'node:crypto';
+import { MarkdownManager } from '@inkeep/open-knowledge-core';
+import { getSchema } from '@tiptap/core';
+import { updateYFragment } from '@tiptap/y-tiptap';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as Y from 'yjs';
+import { sharedExtensions } from './extensions/shared.ts';
+import { ProviderPool } from './provider-pool';
+
+const DUMMY_WS = 'ws://localhost:1/collab';
+const schema = getSchema(sharedExtensions);
+const mdManager = new MarkdownManager({ extensions: sharedExtensions });
+
+/** The document both surfaces of the buffer were captured against. */
+const BASE_MD = '# Notes\n\nSettled paragraph.\n';
+/** The un-drained source-mode edit living in the buffer's `Y.Text`. */
+const BUFFERED_MD = '# Notes\n\nSettled paragraph.\n\nUnsynced source-mode line.\n';
+/** A line that exists ONLY in the buffer — its arrival marks a splice. */
+const BUFFERED_MARKER = 'Unsynced source-mode line.';
+/**
+ * What the post-restart server rebuilt from disk. Shares no body line with
+ * `BASE_MD`, so the buffer's fragment surface no longer matches it either —
+ * the ambiguity the bail exists for.
+ */
+const MOVED_MD = '# Notes\n\nA different paragraph, authored elsewhere.\n';
+/** A line that exists ONLY on the server — its survival marks a refusal. */
+const MOVED_MARKER = 'authored elsewhere';
+
+/**
+ * A pre-recycle replica whose two surfaces disagree: the fragment sits at
+ * `baseMd` (the acked base) while `Y.Text` carries `editedMd` (the unsynced
+ * source-mode edit). That is the shape the attribution is written to resolve.
+ */
+function buildTwoSurfaceState(
+ baseMd: string,
+ editedMd: string,
+): { delta: Uint8Array; fullState: Uint8Array } {
+ const doc = new Y.Doc();
+ doc.transact(() => {
+ doc.getText('source').insert(0, editedMd);
+ updateYFragment(
+ doc,
+ doc.getXmlFragment('default'),
+ schema.nodeFromJSON(mdManager.parse(baseMd)),
+ {
+ mapping: new Map(),
+ isOMark: new Map(),
+ },
+ );
+ });
+ const fullState = Y.encodeStateAsUpdate(doc);
+ const delta = Y.encodeStateAsUpdate(doc, Y.encodeStateVector(new Y.Doc()));
+ doc.destroy();
+ return { delta, fullState };
+}
+
+/** Structured client events the pool emits (recovery → warn, breadcrumb → info). */
+function emittedEvents(spy: ReturnType<typeof vi.spyOn>): string[] {
+ return spy.mock.calls.flatMap(([first]) => {
+ if (typeof first !== 'string') return [];
+ try {
+ const parsed = JSON.parse(first) as { event?: unknown };
+ return typeof parsed.event === 'string' ? [parsed.event] : [];
+ } catch {
+ return [];
+ }
+ });
+}
+
+let pool: ProviderPool;
+let warn: ReturnType<typeof vi.spyOn>;
+let info: ReturnType<typeof vi.spyOn>;
+
+/** True once the replay has reached one of its two terminal outcomes. */
+function replaySettled(): boolean {
+ const seen = [...emittedEvents(warn), ...emittedEvents(info)];
+ return (
+ seen.includes('ok-buffer-replay-content-applied') ||
+ seen.includes('ok-pool-buffer-replay-delta-applied')
+ );
+}
+
+beforeEach(() => {
+ warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ info = vi.spyOn(console, 'info').mockImplementation(() => {});
+});
+
+afterEach(() => {
+ pool?.dispose();
+ vi.restoreAllMocks();
+});
+
+/** Open a doc, seed the provider's live `Y.Text`, and arm the RAM replay buffer. */
+function armReplay(serverContent: string): { docName: string; ytext: Y.Text } {
+ const docName = `pp-diverged-${randomUUID()}`;
+ const { delta, fullState } = buildTwoSurfaceState(BASE_MD, BUFFERED_MD);
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ const ytext = entry.provider.document.getText('source');
+ ytext.insert(0, serverContent);
+ pool.__test_seedBufferedUpdate(docName, delta, { fullState, durable: false });
+ entry.provider.emit('synced', { state: true });
+ return { docName, ytext };
+}
+
+describe('content-level replay against content the server has moved past', () => {
+ it('refuses the splice and reports the divergence', async () => {
+ const { ytext } = armReplay(MOVED_MD);
+
+ // Settle on the replay's terminal event, whichever it is — waiting on the
+ // refusal itself would make every assertion below unreachable in the world
+ // where the bail is gone, which is the world they exist to fail in.
+ await vi.waitFor(() => {
+ expect(replaySettled()).toBe(true);
+ });
+
+ // The refusal is the point: the live server content is still there. A
+ // splice would have deleted it and written the aged buffer over the top.
+ expect(ytext.toString()).toContain(MOVED_MARKER);
+ expect(emittedEvents(warn)).toContain('ok-buffer-replay-diverged');
+ // ...and the aged edit was never spliced in as content.
+ expect(emittedEvents(warn)).not.toContain('ok-buffer-replay-content-applied');
+ // The replay ran all the way to the terminal fallback rather than stopping
+ // early — without this, "no splice" would also be satisfied by a replay
+ // that never reached the attribution at all.
+ expect(emittedEvents(info)).toContain('ok-pool-buffer-replay-delta-applied');
+ });
+
+ it('splices the same buffer when the server content has NOT moved', async () => {
+ // Same buffer, same code path, one variable changed: the provider still
+ // holds the base the fragment was captured at, so the attribution resolves
+ // and the unsynced edit is recovered. This is what the arm above refuses.
+ const { ytext } = armReplay(BASE_MD);
+
+ await vi.waitFor(() => {
+ expect(emittedEvents(warn)).toContain('ok-buffer-replay-content-applied');
+ });
+ expect(ytext.toString()).toContain(BUFFERED_MARKER);
+ expect(emittedEvents(warn)).not.toContain('ok-buffer-replay-diverged');
+ });
+});
diff --git a/packages/app/src/editor/provider-pool.test.ts b/packages/app/src/editor/provider-pool.test.ts
index e38f701a3..6ebbf2ae4 100644
--- a/packages/app/src/editor/provider-pool.test.ts
+++ b/packages/app/src/editor/provider-pool.test.ts
@@ -324,6 +324,34 @@ describe('ProviderPool onChange', () => {
});
});
+describe('ProviderPool unsynced-work signal', () => {
+ test('hasAnyUnsyncedWork reflects an active provider unsyncedChanges count', () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open('doc1');
+ if (entry === null) throw new Error('expected entry');
+ expect(pool.hasAnyUnsyncedWork()).toBe(false);
+ entry.provider.unsyncedChanges = 1;
+ expect(pool.hasAnyUnsyncedWork()).toBe(true);
+ entry.provider.unsyncedChanges = 0;
+ expect(pool.hasAnyUnsyncedWork()).toBe(false);
+ });
+
+ test('addUnsyncedWorkListener fires on the provider unsyncedChanges event; unsubscribe stops it', () => {
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open('doc1');
+ if (entry === null) throw new Error('expected entry');
+ let calls = 0;
+ const stop = pool.addUnsyncedWorkListener(() => {
+ calls++;
+ });
+ entry.provider.emit('unsyncedChanges', { number: 1 });
+ expect(calls).toBe(1);
+ stop();
+ entry.provider.emit('unsyncedChanges', { number: 2 });
+ expect(calls).toBe(1);
+ });
+});
+
describe('ProviderPool onEvict subscription', () => {
// Replaces the explicit cross-module call to evictTiptapEditor /
// evictCmEditor that lived in destroyEntry. Verifies that
diff --git a/packages/app/src/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.ts
index 74fa78334..0dbee910e 100644
--- a/packages/app/src/editor/provider-pool.ts
+++ b/packages/app/src/editor/provider-pool.ts
@@ -29,6 +29,12 @@ import { sharedExtensions } from './extensions/shared.ts';
import { isSystemDoc } from './is-system-doc';
import { getMountId } from './mount-id-registry';
import { setupObservers } from './observers';
+import {
+ consumeReplayOutboxEntry,
+ ReplayOutboxTimeoutError,
+ readReplayOutboxEntry,
+ writeReplayOutboxEntry,
+} from './replay-outbox';
import { BridgeSetupError, invalidateSyncPromise, rejectSyncPromise } from './sync-promise';
/**
@@ -38,6 +44,30 @@ import { BridgeSetupError, invalidateSyncPromise, rejectSyncPromise } from './sy
*/
export const TAB_REPLAY_ORIGIN = Object.freeze({ kind: 'tab-replay' } as const);
+/**
+ * One doc's captured pre-recycle unsynced edit. See the `bufferedUpdates`
+ * field comment for what `delta`/`fullState` carry.
+ */
+interface BufferedReplayUpdate {
+ readonly delta: Uint8Array;
+ readonly fullState: Uint8Array | null;
+ /**
+ * The branch this buffer was captured under — the outbox key's first
+ * component. Captured rather than re-read at use time because the discard
+ * paths run AFTER a branch switch has already moved the observed branch.
+ */
+ readonly branch: string;
+ /**
+ * True once a durable outbox record for this buffer has committed. That
+ * record is the cross-tab exactly-once token, so it also decides whether
+ * the replay must claim before applying and whether a discard has to reach
+ * IDB. Flipped by the write's resolution, so it stays false for over-cap
+ * docs, failed writes, and engines with no durable outbox at all — those
+ * buffers are RAM-only and behave exactly as they did before the outbox.
+ */
+ durable: boolean;
+}
+
export type SyncState = 'connecting' | 'synced' | 'disconnected';
export type ServerRestartRecoveryState =
| { kind: 'idle' }
@@ -444,6 +474,20 @@ export class ProviderPool {
private readonly wsUrl: string;
private readonly recycleDebounceMs: number;
private readonly clearDataTimeoutMs: number;
+ /**
+ * Gates the background-flush / resync-on-visible mechanism. Wired from
+ * the project `bridge.flushOnHide.enabled` kill-switch (default ON) via
+ * `setFlushOnHideEnabled`; when off, `flushOnHide`/`resyncOnVisible` are
+ * inert.
+ */
+ private flushOnHideEnabled = true;
+ /**
+ * Listeners notified whenever any provider's `unsyncedChanges` count moves.
+ * Separate from `onChange` (a single lifecycle callback) so the desktop
+ * background-throttle reporter can observe unsynced-work edges without
+ * competing for the `onChange` slot the DocumentContext owns.
+ */
+ private readonly unsyncedWorkListeners = new Set<() => void>();
private onChange: PoolChangeCallback | null = null;
private tabIdentity: { principalId: string; tabSessionId: string } | null = null;
private serverRestartRecoveryState: ServerRestartRecoveryState = IDLE_SERVER_RESTART_RECOVERY;
@@ -482,8 +526,12 @@ export class ProviderPool {
* Unsynced-edit buffer captured per-doc during a `server-instance-mismatch`
* recycle. Populated right before `clearData()` wipes IDB; drained at the
* fresh provider's FIRST post-recycle `synced` event when the replay
- * listener restores the edit. In-memory only — a tab crash inside the
- * recycle window loses the buffer (accepted trade-off).
+ * listener restores the edit. This map is the fast in-session carrier; a
+ * durable copy is mirrored into the replay outbox (`replay-outbox.ts`) so a
+ * tab crash inside the recycle window no longer loses the buffer — a fresh
+ * tab reads it back from IDB and replays. The two stay coherent: whichever
+ * source the replay listener consumes, it deletes the durable outbox first
+ * so the edit is never re-applied.
*
* `delta` is the raw unsynced Yjs update relative to the last acked
* baseline. It CANNOT integrate into the post-restart doc on its own:
@@ -499,10 +547,7 @@ export class ProviderPool {
* delta apply (which at worst leaves the structs pending, today's
* behavior).
*/
- private readonly bufferedUpdates = new Map<
- string,
- { delta: Uint8Array; fullState: Uint8Array | null }
- >();
+ private readonly bufferedUpdates = new Map<string, BufferedReplayUpdate>();
/**
* Per-docName `closeAndClearPersistence` in-flight tracking. Drives the
* delete-then-recreate-same-docname coordination: while a clear is in
@@ -1244,6 +1289,25 @@ export class ProviderPool {
console.warn(JSON.stringify(parts));
}
+ /**
+ * Describe a durable-outbox failure for telemetry, splitting a STALL from an
+ * ordinary IDB error the same way `ok-client-cache-clear-failed` does. The
+ * two call for different responses: an error is one failed operation, a
+ * timeout means the storage layer is wedged and whatever the operation was
+ * gating (a recycle, a replay) is stuck behind it.
+ */
+ private outboxFailureFields(err: unknown): {
+ failureKind: 'timeout' | 'rejected';
+ errorName: string;
+ errorMessage: string;
+ } {
+ return {
+ failureKind: err instanceof ReplayOutboxTimeoutError ? 'timeout' : 'rejected',
+ errorName: err instanceof Error ? err.name : 'non-error-throw',
+ errorMessage: err instanceof Error ? err.message : String(err),
+ };
+ }
+
/**
* Info-level lifecycle breadcrumb for the reconnect/recycle path. Same
* structured-console channel as the recovery events (the client log
@@ -2076,58 +2140,158 @@ export class ProviderPool {
provider.on('disconnect', onDisconnect);
provider.on('authenticationFailed', onAuthenticationFailed);
provider.on('close', onServerDrivenClose);
-
- // Buffer-replay wiring: if this docName has a pending buffered update
- // from a prior authenticationFailed recycle, apply it to the fresh
- // Y.Doc on the first `synced` event. The listener self-detaches after
- // firing once; if no buffered update exists for this docName, this is
- // a no-op path. Origin `TAB_REPLAY_ORIGIN` lets observers distinguish
- // replay writes from user edits / server sync deliveries.
- const buffered = this.bufferedUpdates.get(docName);
- if (buffered !== undefined) {
- const staleClaimAtReplayInstall = this.recoveryMismatchStaleClaim;
- const replayOnce = (): void => {
- provider.off('synced', replayOnce);
- if (entry.kind !== 'active' || this.entries.get(docName) !== entry) return;
- const current = this.bufferedUpdates.get(docName);
- if (current === undefined) return;
- // Drop the buffer reference up-front: a malformed update that
- // throws would throw again on retry, and the server's sync has
- // already delivered the canonical state. Catch the throw so it
- // doesn't escape into Hocuspocus's event emitter as an unhandled
- // rejection and so the next sync can proceed.
+ // Fan a provider's unsynced-work edges out to pool-level listeners (the
+ // desktop background-throttle reporter). Removed with the provider on
+ // `destroy()`. The immediate emit catches a doc that opens already dirty.
+ provider.on('unsyncedChanges', () => this.emitUnsyncedWork());
+ this.emitUnsyncedWork();
+
+ // Buffer-replay wiring: on the first `synced` after (re)open, replay any
+ // unsynced edit captured during a prior `server-instance-mismatch`
+ // recycle. Two sources: the in-session RAM buffer (same-tab recycle) and
+ // the durable outbox (`replay-outbox.ts`, which survives a tab crash in
+ // the recycle window — the only signal a fresh tab has). The listener
+ // self-detaches after firing once; with no buffered edit it is a cheap
+ // no-op (one `indexedDB.databases()` check). Origin `TAB_REPLAY_ORIGIN`
+ // lets observers distinguish replay writes from user edits / server sync.
+ const staleClaimAtReplayInstall = this.recoveryMismatchStaleClaim;
+ const runReplay = async (): Promise<void> => {
+ if (entry.kind !== 'active' || this.entries.get(docName) !== entry) return;
+ const branch = this.normalizedObservedBranch();
+
+ // Prefer the RAM buffer (no IDB read); fall back to the durable outbox,
+ // the only carrier after a tab crash.
+ let source: { delta: Uint8Array; fullState: Uint8Array | null };
+ // The outbox key this replay's token lives under, and whether a token
+ // exists at all. A RAM buffer with no durable mirror (over-cap doc,
+ // failed write, engine without `databases()`) has nothing to claim.
+ let tokenBranch = branch;
+ let tokenBacked: boolean;
+ const buffered = this.bufferedUpdates.get(docName);
+ if (buffered !== undefined) {
this.bufferedUpdates.delete(docName);
+ source = buffered;
+ tokenBranch = buffered.branch;
+ tokenBacked = buffered.durable;
+ } else {
try {
- if (
- current.fullState !== null &&
- this.replayBufferedContent(docName, provider, current.fullState)
- ) {
- return;
- }
- // Delta-only fallback (full state over cap, replica rebuild threw,
- // or content divergence made the surface attribution ambiguous).
- // The raw delta usually parks in `pendingStructs` on a rebuilt doc
- // — kept as the terminal fallback so this path never REGRESSES
- // relative to the pre-content-replay behavior.
- Y.applyUpdate(provider.document, current.delta, TAB_REPLAY_ORIGIN);
- this.emitStructuredClientBreadcrumb({
- event: 'ok-pool-buffer-replay-delta-applied',
- docName,
- deltaBytes: current.delta.byteLength,
+ const durable = await readReplayOutboxEntry(branch, docName);
+ if (durable === null) return;
+ source = durable;
+ tokenBacked = true;
+ } catch (err: unknown) {
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-buffer-replay-outbox-read-failed',
+ ...this.recoveryTelemetryBase(docName, staleClaimAtReplayInstall),
+ ...this.outboxFailureFields(err),
});
+ return;
+ }
+ }
+
+ // Consume-first: delete the durable outbox BEFORE any content reaches
+ // the server, so a crash after apply can never let a reopen re-apply.
+ // The content-level replay's surface comparison is not re-entrant — a
+ // stale outbox replayed against already-synced content would clobber it.
+ // At-most-once in the tiny [consumed → server-synced] tail (matching the
+ // RAM buffer, and past the crash window the outbox exists to close).
+ //
+ // The consume is also the CROSS-TAB claim: same-origin tabs share one
+ // `(branch, docName)` record, so losing the claim means another tab
+ // already replayed this edit and this one must stand down. That covers
+ // both orders — the other tab consuming before we read (we never see a
+ // record) and after (we see one but cannot claim it).
+ //
+ // Only attempt it when a durable record actually backs this replay. An
+ // unconditional consume would, on a RAM-only buffer, throw its way into
+ // the bail below with the RAM copy ALREADY deleted and no outbox to
+ // recover from — dropping the edit inside the mechanism that exists to
+ // preserve it.
+ if (tokenBacked) {
+ let claimed: boolean;
+ try {
+ claimed = await consumeReplayOutboxEntry(tokenBranch, docName);
} catch (err: unknown) {
- const errorName = err instanceof Error ? err.name : 'non-error-throw';
+ // Bail rather than apply: the record is still there, so a later
+ // clean open recovers the edit instead of risking a double-apply.
this.emitStructuredClientRecoveryEvent({
- event: 'ok-buffer-replay-failed',
+ event: 'ok-buffer-replay-outbox-consume-failed',
...this.recoveryTelemetryBase(docName, staleClaimAtReplayInstall),
- replayByteLength: current.delta.byteLength,
- errorName,
- errorMessage: err instanceof Error ? err.message : String(err),
+ ...this.outboxFailureFields(err),
+ });
+ return;
+ }
+ if (!claimed) {
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-buffer-replay-superseded',
+ ...this.recoveryTelemetryBase(docName, staleClaimAtReplayInstall),
+ reason: 'claimed-by-another-tab',
});
+ return;
}
- };
- provider.on('synced', replayOnce);
- }
+ }
+ if (entry.kind !== 'active' || this.entries.get(docName) !== entry) {
+ // Both carriers are gone by now (RAM deleted above, outbox claimed),
+ // so this bail is a real in-process loss — not the ratified crash
+ // tail. Loud so it can never be mistaken for "nothing to replay".
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-buffer-replay-abandoned',
+ ...this.recoveryTelemetryBase(docName, staleClaimAtReplayInstall),
+ reason: 'entry-replaced-during-consume',
+ replayByteLength: source.delta.byteLength,
+ });
+ return;
+ }
+
+ try {
+ if (
+ source.fullState !== null &&
+ this.replayBufferedContent(docName, provider, source.fullState)
+ ) {
+ return;
+ }
+ // Delta-only fallback (full state over cap, replica rebuild threw, or
+ // content divergence made the surface attribution ambiguous). The raw
+ // delta usually parks in `pendingStructs` on a rebuilt doc — kept as
+ // the terminal fallback so this path never REGRESSES relative to the
+ // pre-content-replay behavior.
+ Y.applyUpdate(provider.document, source.delta, TAB_REPLAY_ORIGIN);
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-buffer-replay-delta-applied',
+ docName,
+ deltaBytes: source.delta.byteLength,
+ });
+ } catch (err: unknown) {
+ const errorName = err instanceof Error ? err.name : 'non-error-throw';
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-buffer-replay-failed',
+ ...this.recoveryTelemetryBase(docName, staleClaimAtReplayInstall),
+ replayByteLength: source.delta.byteLength,
+ errorName,
+ errorMessage: err instanceof Error ? err.message : String(err),
+ });
+ }
+ };
+ const onSyncedReplay = (): void => {
+ // Detach synchronously so a second `synced` during the async replay never
+ // re-triggers. `runReplay` handles its own known failure boundaries
+ // (outbox read/consume, apply) and returns; this outer handler fires only
+ // on an UNEXPECTED throw — which, once a carrier has been consumed, is a
+ // silent in-process loss. Emit it (like this file's other fire-and-forget
+ // recovery paths) rather than swallow, while still keeping the rejection
+ // out of the `synced` emitter. Kept minimal (no telemetry-base helper) so
+ // the fallback itself can never throw its way back out.
+ provider.off('synced', onSyncedReplay);
+ void runReplay().catch((err: unknown) => {
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-buffer-replay-unexpected-error',
+ docName,
+ errorName: err instanceof Error ? err.name : 'non-error-throw',
+ errorMessage: err instanceof Error ? err.message : String(err),
+ });
+ });
+ };
+ provider.on('synced', onSyncedReplay);
this._entries.set(docName, entry);
this.touch(docName);
@@ -2248,6 +2412,13 @@ export class ProviderPool {
branch: this.normalizedObservedBranch(),
});
const startedAt = Date.now();
+ // Branch scope for the durable replay outbox — captured once so every
+ // per-doc write uses the same key the reopen path reconstructs.
+ const recoveryBranch = this.normalizedObservedBranch();
+ // Durable-outbox writes kicked off during the capture loop. Awaited before
+ // `clearData()` so a crash while the y-indexeddb store is being wiped still
+ // leaves the buffer recoverable (buffer → clearData → recycle ordering).
+ const outboxWrites: Promise<void>[] = [];
const recoveryActiveDocName = this.activeDocName;
// Recovery UI (spinner + failure panel) only tracks the foreground doc.
// Background pool entries still recycle and clear IDB on mismatch; if
@@ -2316,29 +2487,61 @@ export class ProviderPool {
// edit at content level (see `bufferedUpdates` doc comment). Docs
// whose full state exceeds the cap keep the delta-only fallback.
const fullState = Y.encodeStateAsUpdate(poolEntry.provider.document);
- this.bufferedUpdates.set(docName, {
+ const fullStateForBuffer = fullState.byteLength > MAX_BUFFER_BYTES ? null : fullState;
+ const buffered: BufferedReplayUpdate = {
delta: unsynced,
- fullState: fullState.byteLength > MAX_BUFFER_BYTES ? null : fullState,
- });
+ fullState: fullStateForBuffer,
+ branch: recoveryBranch,
+ durable: false,
+ };
+ this.bufferedUpdates.set(docName, buffered);
+ // Mirror the buffer into the durable outbox only when content-level
+ // replay is possible (over-cap docs stay RAM-only — their crash loss
+ // is the same accepted trade-off as before). A failed durable write
+ // degrades to the RAM buffer, so swallow-and-observe rather than
+ // block the recycle. `durable` flips only once the record has
+ // committed; everything downstream (the cross-tab claim, the discard
+ // paths) keys off it, so an unwritten mirror can never be mistaken
+ // for a live token.
+ if (fullStateForBuffer !== null) {
+ outboxWrites.push(
+ writeReplayOutboxEntry(recoveryBranch, docName, {
+ delta: unsynced,
+ fullState: fullStateForBuffer,
+ })
+ .then((persisted) => {
+ if (persisted) buffered.durable = true;
+ else {
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-buffer-replay-outbox-unavailable',
+ ...this.recoveryTelemetryBase(docName),
+ reason: 'indexeddb-databases-unsupported',
+ });
+ }
+ })
+ .catch((err: unknown) => {
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-buffer-replay-outbox-write-failed',
+ ...this.recoveryTelemetryBase(docName),
+ ...this.outboxFailureFields(err),
+ });
+ }),
+ );
+ }
this.emitStructuredClientBreadcrumb({
event: 'ok-pool-mismatch-buffer-captured',
docName,
deltaBytes: unsynced.byteLength,
- fullStateBytes: fullState.byteLength > MAX_BUFFER_BYTES ? 0 : fullState.byteLength,
+ fullStateBytes: fullStateForBuffer === null ? 0 : fullStateForBuffer.byteLength,
});
}
}
- // Gate per-doc on clearData success. A `clearData` failure (blocked
- // by another tab/DevTools, quota exhaustion, transaction-aborted)
- // means the IDB still holds the pre-restart Y.Doc state — recycling
- // into the un-cleared DB would hydrate the fresh provider's Y.Doc
- // from stale data BEFORE Yjs sync runs, re-opening the content-
- // duplication bug class clearData exists to prevent. Use
- // `Promise.allSettled` so per-element rejections surface (the prior
- // `Promise.all + per-element catch` swallowed every failure, then
- // recycled unconditionally).
- const clears: { docName: string; promise: Promise<void> }[] = [];
+ // Select entries to clear now, but DEFER the actual `clearData()` calls
+ // until the durable outbox writes commit — a crash between "IDB wiped"
+ // and "outbox written" would lose the buffer, so the outbox must land
+ // first. Keeps the buffer → clearData → recycle ordering.
+ const toClear: { docName: string; persistence: ClientPersistenceProvider }[] = [];
for (const [docName, poolEntry] of snapshot) {
// TearingDown entries have null persistence by construction; Active
// entries opened before the live server epoch was known also have
@@ -2348,18 +2551,34 @@ export class ProviderPool {
// SHOULD be cleared.
if (poolEntry.kind !== 'active') continue;
if (poolEntry.persistence === null) continue;
- clears.push({
- docName,
- promise: this.withClearDataTimeout(docName, poolEntry.persistence.clearData()),
- });
+ toClear.push({ docName, persistence: poolEntry.persistence });
}
- this.emitStructuredClientBreadcrumb({
- event: 'ok-pool-mismatch-clears-begin',
- count: clears.length,
- });
- const inflight: Promise<void> = Promise.allSettled(clears.map((c) => c.promise))
- .then((results) => {
+ // Clear IDB then recycle. When the durable outbox has writes in flight,
+ // await them first so a crash between "IDB wiped" and "outbox written"
+ // can't lose the buffer; with nothing to write, clearData starts
+ // synchronously (timing unchanged from before the durable layer).
+ const runClearsAndRecycle = (): Promise<void> => {
+ // Gate per-doc on clearData success. A `clearData` failure (blocked
+ // by another tab/DevTools, quota exhaustion, transaction-aborted)
+ // means the IDB still holds the pre-restart Y.Doc state — recycling
+ // into the un-cleared DB would hydrate the fresh provider's Y.Doc
+ // from stale data BEFORE Yjs sync runs, re-opening the content-
+ // duplication bug class clearData exists to prevent. Use
+ // `Promise.allSettled` so per-element rejections surface (the prior
+ // `Promise.all + per-element catch` swallowed every failure, then
+ // recycled unconditionally).
+ const clears: { docName: string; promise: Promise<void> }[] = toClear.map(
+ ({ docName, persistence }) => ({
+ docName,
+ promise: this.withClearDataTimeout(docName, persistence.clearData()),
+ }),
+ );
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-mismatch-clears-begin',
+ count: clears.length,
+ });
+ return Promise.allSettled(clears.map((c) => c.promise)).then((results) => {
const failed: string[] = [];
const cleared: string[] = [];
let sawClearTimeout = false;
@@ -2426,12 +2645,17 @@ export class ProviderPool {
// `failureReason` is only read when `failedDocNames` is non-empty; this branch is all clears OK.
this.enterServerRestartReconnect(reconnectDocNames, [], startedAt, 'clear-data-failed');
this.recycleAllEntries();
- })
- .finally(() => {
- if (this.mismatchInFlight === inflight) {
- this.mismatchInFlight = null;
- }
});
+ };
+ const inflight: Promise<void> = (
+ outboxWrites.length === 0
+ ? runClearsAndRecycle()
+ : Promise.allSettled(outboxWrites).then(runClearsAndRecycle)
+ ).finally(() => {
+ if (this.mismatchInFlight === inflight) {
+ this.mismatchInFlight = null;
+ }
+ });
this.mismatchInFlight = inflight;
}
@@ -2616,7 +2840,7 @@ export class ProviderPool {
this.lruOrder = this.lruOrder.filter((n) => n !== docName);
// Explicit close discards any pending replay buffer — the user closed
// the tab; resurrecting unsynced edits later would surprise them.
- this.bufferedUpdates.delete(docName);
+ this.discardBufferedUpdate(docName);
if (this.activeDocName === docName) {
this.activeDocName = null;
@@ -2813,7 +3037,38 @@ export class ProviderPool {
* branch B Y.Doc the next time the user opened that doc.
*/
clearBufferedUpdates(): void {
- this.bufferedUpdates.clear();
+ for (const docName of Array.from(this.bufferedUpdates.keys())) {
+ this.discardBufferedUpdate(docName);
+ }
+ }
+
+ /**
+ * Drop one doc's pending replay buffer on an INTENTIONAL discard (explicit
+ * close, LRU eviction, cross-branch invalidation) — RAM copy and durable
+ * mirror together.
+ *
+ * Dropping only the RAM copy would leave the outbox record behind as an
+ * immortal orphan: a later open of the same doc reads it back and replays an
+ * arbitrarily old edit, which is exactly the surprise `close()` and the
+ * cross-branch invalidation were each written to prevent. Fire-and-forget —
+ * both call sites are synchronous and the record is idempotent to consume —
+ * but a failure is reported, since it leaves a resurrectable edit behind.
+ *
+ * Deliberately NOT called from `dispose()`: that is a pool-lifecycle end
+ * (HMR remount, collab-URL swap, test teardown), not a user discard, and the
+ * durable copy surviving it is the crash-durability the outbox exists for.
+ */
+ private discardBufferedUpdate(docName: string): void {
+ const buffered = this.bufferedUpdates.get(docName);
+ this.bufferedUpdates.delete(docName);
+ if (buffered === undefined || !buffered.durable) return;
+ void consumeReplayOutboxEntry(buffered.branch, docName).catch((err: unknown) => {
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-buffer-replay-outbox-discard-failed',
+ ...this.recoveryTelemetryBase(docName),
+ ...this.outboxFailureFields(err),
+ });
+ });
}
/**
@@ -2824,8 +3079,17 @@ export class ProviderPool {
* branch-switched / close drain semantics. Naming-prefix `__test`
* keeps these out of production call sites by convention.
*/
- __test_seedBufferedUpdate(docName: string, update: Uint8Array): void {
- this.bufferedUpdates.set(docName, { delta: update, fullState: null });
+ __test_seedBufferedUpdate(
+ docName: string,
+ update: Uint8Array,
+ options: { fullState?: Uint8Array; durable?: boolean; branch?: string } = {},
+ ): void {
+ this.bufferedUpdates.set(docName, {
+ delta: update,
+ fullState: options.fullState ?? null,
+ branch: options.branch ?? this.normalizedObservedBranch(),
+ durable: options.durable ?? false,
+ });
}
__test_bufferedUpdatesSize(): number {
return this.bufferedUpdates.size;
@@ -2883,6 +3147,145 @@ export class ProviderPool {
return this.entries.get(docName) ?? null;
}
+ /**
+ * Toggle the background-flush / resync-on-visible mechanism. Wired from
+ * the project `bridge.flushOnHide.enabled` kill-switch (default ON);
+ * disable only to isolate a suspected regression.
+ */
+ setFlushOnHideEnabled(enabled: boolean): void {
+ this.flushOnHideEnabled = enabled;
+ }
+
+ /**
+ * Push every active doc's unsynced work to the server and commit its IDB
+ * cache when the tab is backgrounded or unloaded.
+ *
+ * A backgrounded tab's timers are throttled and it may be frozen or
+ * recycled before the provider's incremental-update path delivers the
+ * last edits. IndexedDB alone is not durable — it is an additive cache
+ * the mismatch-recycle flow clears — so the flush should reach the SERVER.
+ * `forceSync()` re-runs the sync handshake (the same primitive
+ * `forceSyncInterval` uses to recover dropped updates), reconciling any
+ * edit the server is missing; `flushFullState()` then commits the cache.
+ *
+ * How much of that lands depends on which hide this is, and the difference
+ * is structural, not a gap to close: `forceSync()` only SENDS SyncStep1, and
+ * the client's own updates travel to the server one full exchange later (the
+ * server answers with its SyncStep1, the client replies SyncStep2). On
+ * `visibilitychange → hidden` the tab is still alive, so that exchange
+ * completes and the server delivery is real. On a true unload (`pagehide`
+ * for a close/navigate) the tab does not survive the round trip, so the
+ * effective durability there is the IndexedDB commit — which is why
+ * `flushFullState()` is not treated as the redundant half of this pair. No
+ * WebSocket primitive can beat unload; `sendBeacon` carries no CRDT session.
+ *
+ * Skipped while a server-instance-mismatch recycle is in flight: that
+ * flow already captures the unsynced delta into the durable replay outbox
+ * and owns re-delivery, so a concurrent forceSync would race the epoch it
+ * is being recycled against for no benefit.
+ */
+ flushOnHide(): void {
+ if (!this.flushOnHideEnabled) return;
+ if (this.mismatchInFlight !== null) return;
+ for (const entry of this._entries.values()) {
+ if (entry.kind !== 'active') continue;
+ if (entry.provider.unsyncedChanges > 0) {
+ entry.provider.forceSync();
+ // On a true unload this IDB commit is the effective durability (see the
+ // docblock above), so a rejection loses edits — route it through the
+ // structured emitter like the other durability-path failures in this
+ // file rather than swallowing it. Fire-and-forget: never let it reject.
+ void entry.persistence?.flushFullState().catch((err: unknown) => {
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-pool-flush-on-hide-failed',
+ ...this.recoveryTelemetryBase(entry.docName),
+ errorName: err instanceof Error ? err.name : 'non-error-throw',
+ errorMessage: err instanceof Error ? err.message : String(err),
+ });
+ });
+ }
+ }
+ }
+
+ /**
+ * Re-run the sync handshake for every active doc when the tab returns to
+ * the foreground. A backgrounded tab can miss server-pushed updates
+ * (throttled delivery, a dropped frame, a brief disconnect); `forceSync`
+ * pulls whatever the client is behind on so the doc reconverges.
+ *
+ * Only docs that have completed a sync are re-synced. `forceSync()` calls
+ * `resetUnsyncedChanges()`, which sets `unsyncedChanges` to 1
+ * unconditionally and only returns to 0 when the server answers — so firing
+ * it at a provider that cannot answer LATCHES every clean doc dirty for as
+ * long as the disconnect lasts. That pins `hasAnyUnsyncedWork()` true, which
+ * holds desktop background-throttling suppressed (battery) and makes
+ * `flushOnHide` force-sync every doc on every hide. Nothing is lost by
+ * skipping: a provider that is connecting or reconnecting runs the full sync
+ * handshake itself once the socket is up.
+ */
+ resyncOnVisible(): void {
+ if (!this.flushOnHideEnabled) return;
+ // Same stand-down as `flushOnHide`: the recycle flow owns re-delivery for
+ // the epoch being recycled away, so a forceSync here races it. It would
+ // also latch `unsyncedChanges` on providers about to be destroyed, which is
+ // the exact spurious-latch this method's docblock exists to avoid.
+ if (this.mismatchInFlight !== null) return;
+ for (const entry of this._entries.values()) {
+ if (entry.kind !== 'active') continue;
+ if (entry.syncState !== 'synced') continue;
+ entry.provider.forceSync();
+ }
+ }
+
+ /**
+ * True while any open doc holds edits the server has not yet acked.
+ *
+ * Over-reports (true) rather than under-reports: this keys the desktop
+ * background-throttle toggle, and keeping timers alive a moment too long is
+ * safe (a little less battery), while throttling mid-sync is not. A doc
+ * that closes while still dirty is the one residual over-report window.
+ */
+ hasAnyUnsyncedWork(): boolean {
+ for (const entry of this._entries.values()) {
+ if (entry.kind === 'active' && entry.provider.unsyncedChanges > 0) return true;
+ }
+ return false;
+ }
+
+ /**
+ * Subscribe to unsynced-work edges (see `hasAnyUnsyncedWork`). The callback
+ * fires whenever any provider's `unsyncedChanges` count moves and once when
+ * a doc opens; the subscriber recomputes `hasAnyUnsyncedWork()` and dedupes
+ * the true↔false transition itself. Returns an unsubscribe.
+ */
+ addUnsyncedWorkListener(cb: () => void): () => void {
+ this.unsyncedWorkListeners.add(cb);
+ return () => {
+ this.unsyncedWorkListeners.delete(cb);
+ };
+ }
+
+ private emitUnsyncedWork(): void {
+ // Isolated per listener. This runs inside a provider's `unsyncedChanges`
+ // handler, so an unguarded throw would abandon the remaining listeners AND
+ // propagate into the pool's provider event loop. The desktop subscriber
+ // calls an Electron IPC proxy, a cross-process boundary the renderer
+ // cannot enforce, and the install-time capability check cannot speak for a
+ // proxy that throws later. Reported rather than swallowed: a listener that
+ // is failing is a real signal, it just must not take sync bookkeeping with
+ // it.
+ for (const cb of this.unsyncedWorkListeners) {
+ try {
+ cb();
+ } catch (err) {
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-pool-unsynced-work-listener-threw',
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+ }
+ }
+
/**
* Destroy and recreate the entry for `docName`, preserving `activeDocName`
* across the swap. Used by the "Try again" retry path in
@@ -2945,6 +3348,12 @@ export class ProviderPool {
this.pendingServerInstanceKnown = null;
this.tabIdentity = null;
this.recoveryMismatchStaleClaim = undefined;
+ // Pool-level subscriptions and toggles are mutable fields like any other:
+ // a disposed pool that still fans unsynced-work edges out to a previous
+ // mount's subscriber, or that carries a previous run's kill-switch value,
+ // is exactly the stale-state bleed this block exists to prevent.
+ this.unsyncedWorkListeners.clear();
+ this.flushOnHideEnabled = true;
}
private evictLru(): void {
diff --git a/packages/app/src/editor/qa-001-crash-window.test.ts b/packages/app/src/editor/qa-001-crash-window.test.ts
new file mode 100644
index 000000000..6f2e0ed24
--- /dev/null
+++ b/packages/app/src/editor/qa-001-crash-window.test.ts
@@ -0,0 +1,154 @@
+/**
+ * Crash-window sweep for the durable replay outbox, with an OCCURRENCE-COUNT
+ * oracle.
+ *
+ * The committed durable-replay tests assert with `.includes()` / absence, which
+ * is blind to the failure that actually matters here: a recovered edit applied
+ * TWICE. This drives the same ProviderPool durable-replay path against
+ * fake-indexeddb and counts, sweeping the consume-first windows:
+ * - crash before consume -> reopen: content present EXACTLY ONCE
+ * - consume-then-apply-fails (the documented at-most-once tail): content
+ * ABSENT (count 0), never doubled
+ * - re-fire (double `synced`, or a later reopen): never a second application
+ *
+ * Consume-first ordering is what makes the doubled case structurally
+ * unreachable — the outbox entry is deleted before the content is applied — so
+ * these counts are the invariant that ordering buys.
+ */
+import { randomUUID } from 'node:crypto';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterEach, describe, expect, it } from 'vitest';
+import * as Y from 'yjs';
+import { UNKNOWN_BRANCH_SENTINEL } from './client-persistence';
+import { ProviderPool } from './provider-pool';
+import { readReplayOutboxEntry, writeReplayOutboxEntry } from './replay-outbox';
+
+const DUMMY_WS = 'ws://localhost:1/collab';
+
+function count(hay: string, needle: string): number {
+ if (needle === '') return 0;
+ let n = 0;
+ let i = hay.indexOf(needle);
+ while (i !== -1) {
+ n++;
+ i = hay.indexOf(needle, i + needle.length);
+ }
+ return n;
+}
+
+function buildSourceOnlyState(text: string): { delta: Uint8Array; fullState: Uint8Array } {
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, text);
+ const fullState = Y.encodeStateAsUpdate(doc);
+ const delta = Y.encodeStateAsUpdate(doc, Y.encodeStateVector(new Y.Doc()));
+ doc.destroy();
+ return { delta, fullState };
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2_000): Promise<boolean> {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ if (predicate()) return true;
+ await wait(10);
+ }
+ return predicate();
+}
+
+let pool: ProviderPool;
+afterEach(() => pool?.dispose());
+
+describe('QA-001 crash-window sweep (occurrence-count oracle, ratified consume-first)', () => {
+ it('WINDOW: crash before consume -> reopen replays the edit EXACTLY ONCE (count===1, never 2)', async () => {
+ const docName = `qa001-${randomUUID()}`;
+ const marker = `crash-before-consume-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ // Reopen (fresh tab, no in-memory buffer): the durable read path fires.
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ entry.provider.emit('synced', { state: true });
+
+ await waitFor(() => entry.provider.document.getText('source').toString().includes(marker));
+ const src = entry.provider.document.getText('source').toString();
+ expect(count(src, marker)).toBe(1); // EXACTLY once, not merely present
+ expect(await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)).toBeNull(); // consumed
+ });
+
+ it('WINDOW: consume happens but apply fails (corrupt = the between-consume-and-apply tail) -> content ABSENT (count 0), entry gone, NEVER doubled', async () => {
+ const docName = `qa001-${randomUUID()}`;
+ const real = buildSourceOnlyState('real content that will be truncated');
+ const truncated = real.fullState.slice(0, 4);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, {
+ delta: truncated,
+ fullState: truncated,
+ });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ entry.provider.emit('synced', { state: true });
+
+ // consume-regardless-of-apply: entry gone even though apply threw.
+ // Explicit async poll (NOT waitFor's sync predicate — an async predicate
+ // returns a truthy Promise and would pass vacuously).
+ let consumed = false;
+ for (let i = 0; i < 60 && !consumed; i += 1) {
+ consumed = (await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)) === null;
+ if (!consumed) await wait(10);
+ }
+ expect(consumed).toBe(true);
+ // At-most-once tail loss (the ratified trade): absent, and structurally
+ // un-doublable because the entry was deleted before the (failed) apply.
+ expect(entry.provider.document.getText('source').toString()).toBe('');
+ });
+
+ it('IDEMPOTENCE: a double `synced` fire in the SAME open applies at most once (count<=1, never 2)', async () => {
+ const docName = `qa001-${randomUUID()}`;
+ const marker = `double-fire-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ entry.observerCleanup = () => {};
+ // Fire synced twice back-to-back: consume-first must make the second a no-op.
+ entry.provider.emit('synced', { state: true });
+ entry.provider.emit('synced', { state: true });
+
+ await waitFor(() => entry.provider.document.getText('source').toString().includes(marker));
+ await wait(80); // let any second application attempt settle
+ const src = entry.provider.document.getText('source').toString();
+ expect(count(src, marker)).toBe(1); // NEVER 2 despite two synced fires
+ });
+
+ it('REOPEN after a completed recovery: no second application on the next tab (count of applications === 1 total)', async () => {
+ const docName = `qa001-${randomUUID()}`;
+ const marker = `reopen-once-${randomUUID()}`;
+ const { delta, fullState } = buildSourceOnlyState(marker);
+ await writeReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName, { delta, fullState });
+
+ pool = new ProviderPool(3, DUMMY_WS);
+ const e1 = pool.open(docName);
+ if (!e1) throw new Error('expected e1');
+ e1.observerCleanup = () => {};
+ e1.provider.emit('synced', { state: true });
+ await waitFor(() => e1.provider.document.getText('source').toString().includes(marker));
+ expect(count(e1.provider.document.getText('source').toString(), marker)).toBe(1);
+ pool.dispose();
+
+ // Second tab: outbox consumed, no re-fire; fresh doc stays empty (0 second applies).
+ pool = new ProviderPool(3, DUMMY_WS);
+ const e2 = pool.open(docName);
+ if (!e2) throw new Error('expected e2');
+ e2.observerCleanup = () => {};
+ e2.provider.emit('synced', { state: true });
+ await wait(80);
+ expect(count(e2.provider.document.getText('source').toString(), marker)).toBe(0);
+ expect(await readReplayOutboxEntry(UNKNOWN_BRANCH_SENTINEL, docName)).toBeNull();
+ });
+});
diff --git a/packages/app/src/editor/replay-outbox.test.ts b/packages/app/src/editor/replay-outbox.test.ts
new file mode 100644
index 000000000..bb5bc36fd
--- /dev/null
+++ b/packages/app/src/editor/replay-outbox.test.ts
@@ -0,0 +1,203 @@
+/**
+ * Unit tests for the durable replay outbox — the IndexedDB store that carries
+ * an unsynced edit across a tab crash in the `server-instance-mismatch`
+ * recycle window. Runs against the globally-installed `fake-indexeddb`
+ * (idb-preload setup file), which wipes all databases after each test.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ consumeReplayOutboxEntry,
+ ReplayOutboxTimeoutError,
+ readReplayOutboxEntry,
+ writeReplayOutboxEntry,
+} from './replay-outbox';
+
+function bytes(...vals: number[]): Uint8Array {
+ return new Uint8Array(vals);
+}
+
+async function hasOutboxDb(dbName: string): Promise<boolean> {
+ const dbs = await indexedDB.databases();
+ return dbs.some((d) => d.name === dbName);
+}
+
+/**
+ * Run `body` against an engine that has no `indexedDB.databases()` (Firefox
+ * < 126 / Safari < 14). Shadowing the prototype method on the instance is
+ * what the module's own capability probe reads.
+ */
+async function withoutDatabasesApi(body: () => Promise<void>): Promise<void> {
+ const factory = indexedDB as unknown as { databases?: unknown };
+ factory.databases = undefined;
+ try {
+ await body();
+ } finally {
+ delete factory.databases;
+ }
+}
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+});
+
+describe('replay-outbox', () => {
+ it('round-trips a written entry byte-for-byte', async () => {
+ await writeReplayOutboxEntry('main', 'doc-a', {
+ delta: bytes(1, 2, 3),
+ fullState: bytes(9, 8, 7, 6),
+ });
+ const read = await readReplayOutboxEntry('main', 'doc-a');
+ expect(read).not.toBeNull();
+ expect(Array.from(read?.delta ?? [])).toEqual([1, 2, 3]);
+ expect(Array.from(read?.fullState ?? [])).toEqual([9, 8, 7, 6]);
+ });
+
+ it('returns null and creates no database when no outbox exists', async () => {
+ const read = await readReplayOutboxEntry('main', 'never-written');
+ expect(read).toBeNull();
+ // A normal doc open must not litter an empty outbox database.
+ expect(await hasOutboxDb('ok-replay-outbox:main:never-written')).toBe(false);
+ });
+
+ it('a consumed entry reads back as null', async () => {
+ await writeReplayOutboxEntry('main', 'doc-b', { delta: bytes(1), fullState: bytes(2) });
+ await consumeReplayOutboxEntry('main', 'doc-b');
+ expect(await readReplayOutboxEntry('main', 'doc-b')).toBeNull();
+ });
+
+ it('consume reports whether IT removed a live record', async () => {
+ await writeReplayOutboxEntry('main', 'doc-claim', { delta: bytes(1), fullState: bytes(2) });
+ // The claim: first consumer takes the record, every later consumer of the
+ // same record is told it lost.
+ expect(await consumeReplayOutboxEntry('main', 'doc-claim')).toBe(true);
+ expect(await consumeReplayOutboxEntry('main', 'doc-claim')).toBe(false);
+ // Never written at all reads the same as already-claimed.
+ expect(await consumeReplayOutboxEntry('main', 'doc-claim-absent')).toBe(false);
+ });
+
+ it('concurrent consumers of one record: exactly one claims it', async () => {
+ await writeReplayOutboxEntry('main', 'doc-race', { delta: bytes(7), fullState: bytes(8) });
+
+ // Two same-origin tabs racing the same `(branch, docName)` token. The
+ // count+delete pair runs inside ONE readwrite transaction, and IndexedDB
+ // serializes overlapping readwrite transactions across connections, so
+ // this is an atomic compare-and-claim rather than a check-then-act that
+ // both callers could win.
+ const results = await Promise.all([
+ consumeReplayOutboxEntry('main', 'doc-race'),
+ consumeReplayOutboxEntry('main', 'doc-race'),
+ consumeReplayOutboxEntry('main', 'doc-race'),
+ ]);
+
+ expect(results.filter(Boolean)).toHaveLength(1);
+ expect(await readReplayOutboxEntry('main', 'doc-race')).toBeNull();
+ });
+
+ it('a later write overwrites an existing entry', async () => {
+ await writeReplayOutboxEntry('main', 'doc-c', { delta: bytes(1), fullState: bytes(1) });
+ await writeReplayOutboxEntry('main', 'doc-c', { delta: bytes(5, 5), fullState: bytes(6, 6) });
+ const read = await readReplayOutboxEntry('main', 'doc-c');
+ expect(Array.from(read?.delta ?? [])).toEqual([5, 5]);
+ expect(Array.from(read?.fullState ?? [])).toEqual([6, 6]);
+ });
+
+ it('scopes entries by branch and docName', async () => {
+ await writeReplayOutboxEntry('main', 'shared', { delta: bytes(1), fullState: bytes(1) });
+ expect(await readReplayOutboxEntry('feature', 'shared')).toBeNull();
+ expect(await readReplayOutboxEntry('main', 'other')).toBeNull();
+ expect(await readReplayOutboxEntry('main', 'shared')).not.toBeNull();
+ });
+
+ it('reads null for a foreign/truncated record rather than returning garbage', async () => {
+ // Plant a record whose shape is not {delta, fullState} Uint8Arrays,
+ // directly against the outbox DB's store shape (a truncated write or a
+ // record from a future schema must read as "nothing to replay").
+ await new Promise<void>((resolve, reject) => {
+ const req = indexedDB.open('ok-replay-outbox:main:garbage');
+ req.onupgradeneeded = () => req.result.createObjectStore('entry');
+ req.onsuccess = () => {
+ const db = req.result;
+ const tx = db.transaction('entry', 'readwrite');
+ tx.objectStore('entry').put({ delta: 'not-bytes', fullState: 42 }, 'buffer');
+ tx.oncomplete = () => {
+ db.close();
+ resolve();
+ };
+ tx.onerror = () => reject(tx.error);
+ };
+ req.onerror = () => reject(req.error);
+ });
+ expect(await readReplayOutboxEntry('main', 'garbage')).toBeNull();
+ });
+
+ it('consuming an absent outbox is a no-op', async () => {
+ await expect(consumeReplayOutboxEntry('main', 'absent')).resolves.toBe(false);
+ expect(await hasOutboxDb('ok-replay-outbox:main:absent')).toBe(false);
+ });
+
+ it('writes nothing on an engine with no indexedDB.databases()', async () => {
+ // Without `databases()` the read path can never probe for this record, so
+ // a write would strand a full doc-state payload in storage that nothing
+ // can consume or reclaim. The write must decline and SAY it declined, so
+ // the caller knows its buffer is RAM-only.
+ await withoutDatabasesApi(async () => {
+ const persisted = await writeReplayOutboxEntry('main', 'no-databases-api', {
+ delta: bytes(1, 2, 3),
+ fullState: bytes(4, 5, 6),
+ });
+ expect(persisted).toBe(false);
+ });
+
+ expect(await hasOutboxDb('ok-replay-outbox:main:no-databases-api')).toBe(false);
+ expect(await readReplayOutboxEntry('main', 'no-databases-api')).toBeNull();
+ });
+
+ it('rejects with a timeout rather than hanging when IndexedDB stalls', async () => {
+ // The recycle awaits the write BEFORE clearData(), so an operation that
+ // never settles strands the whole recovery: the IDB is never cleared, the
+ // providers are never recycled, the in-flight marker never clears, and
+ // flush-on-hide stays inert behind it. A stalled storage layer has to
+ // surface as a bounded failure.
+ vi.useFakeTimers();
+ vi.spyOn(indexedDB, 'databases').mockReturnValue(new Promise(() => {}));
+
+ const stalled = consumeReplayOutboxEntry('main', 'doc-stalled');
+ const assertion = expect(stalled).rejects.toBeInstanceOf(ReplayOutboxTimeoutError);
+ await vi.advanceTimersByTimeAsync(10_000);
+ await assertion;
+ });
+
+ it('reports a committed write so the caller can trust the durable copy', async () => {
+ const persisted = await writeReplayOutboxEntry('main', 'doc-persisted', {
+ delta: bytes(1),
+ fullState: bytes(2),
+ });
+ expect(persisted).toBe(true);
+ expect(await readReplayOutboxEntry('main', 'doc-persisted')).not.toBeNull();
+ });
+
+ it('commits the write transaction explicitly and still stores the entry', async () => {
+ // The whole point of this write is to be durable before `clearData()`
+ // runs, and a tab can die before the idle turn that would auto-commit it.
+ // The write path is the only one here that calls commit() explicitly, so a
+ // call on the prototype during it is attributable to that path.
+ const commitSpy = vi.spyOn(IDBTransaction.prototype, 'commit');
+ try {
+ const persisted = await writeReplayOutboxEntry('main', 'doc-explicit-commit', {
+ delta: bytes(7),
+ fullState: bytes(8),
+ });
+ expect(persisted).toBe(true);
+ expect(commitSpy).toHaveBeenCalled();
+ } finally {
+ commitSpy.mockRestore();
+ }
+
+ // Committing early must not cost durability: the entry is readable back.
+ const entry = await readReplayOutboxEntry('main', 'doc-explicit-commit');
+ expect(entry).not.toBeNull();
+ expect(Array.from(entry?.delta ?? [])).toEqual([7]);
+ expect(Array.from(entry?.fullState ?? [])).toEqual([8]);
+ });
+});
diff --git a/packages/app/src/editor/replay-outbox.ts b/packages/app/src/editor/replay-outbox.ts
new file mode 100644
index 000000000..a5f2f98b3
--- /dev/null
+++ b/packages/app/src/editor/replay-outbox.ts
@@ -0,0 +1,293 @@
+/**
+ * Durable, epoch-agnostic replay outbox for the `server-instance-mismatch`
+ * recycle.
+ *
+ * The provider pool's in-memory `bufferedUpdates` map loses its content if the
+ * tab dies inside the recycle window (`clearData()` → recycle → first
+ * `synced`). This outbox is the durable carrier: the unsynced edit's full
+ * pre-recycle state is written here BEFORE `clearData()` wipes the y-indexeddb
+ * store, and read back on the next open of the doc — surviving a tab crash at
+ * any point up to the replay.
+ *
+ * It is a SEPARATE IndexedDB database (`ok-replay-outbox:<branch>:<docName>`),
+ * NEVER the y-indexeddb `updates` store: hydrating the pre-recycle bytes back
+ * into the fresh Y.Doc is exactly the content-duplication class `clearData`
+ * exists to prevent. The reopen path reads this store explicitly and feeds the
+ * bytes through the CONTENT-level replay (rebuild a replica, splice the
+ * recovered string) rather than a Y.Doc merge.
+ *
+ * The db name is branch+docName scoped (not epoch-scoped): the post-recycle
+ * `serverInstanceId` is unknown when the buffer is captured (the client nulls
+ * its cached id and only relearns it from the reconnect handshake), so the
+ * epoch cannot be part of the key. Branch isolation mirrors the y-indexeddb
+ * naming.
+ *
+ * Durable recovery requires `indexedDB.databases()` (Baseline). On engines
+ * without it EVERY operation no-ops (degrade to RAM-only): the read/consume
+ * because they cannot probe for existence without `open` creating an empty
+ * database on a normal doc open, and the WRITE because a record no reader can
+ * ever see is a full doc-state payload stranded in storage forever. The write
+ * reports that with a `false` return so the caller knows the buffer is
+ * RAM-only.
+ *
+ * The single `(branch, docName)` record is also the CROSS-TAB exactly-once
+ * token: same-origin tabs share it, so `consumeReplayOutboxEntry` reports
+ * whether THIS caller was the one that removed a live record. Its count+delete
+ * run in one `readwrite` transaction, and IndexedDB serializes overlapping
+ * readwrite transactions across connections, which makes the pair an atomic
+ * compare-and-claim rather than a check-then-act.
+ *
+ * Consumed entries leave an empty outbox database behind (record deleted, DB
+ * kept) rather than racing a `deleteDatabase` against a concurrent reopen —
+ * a bounded, per-docName storage-hygiene cost matching the `_unknown_`-branch
+ * orphan note in `client-persistence.ts`.
+ *
+ * Every operation is deadline-bounded. The recycle path awaits the write
+ * BEFORE `clearData()`, so an IDB stall that never settles would strand the
+ * whole recovery (no clear, no recycle, `mismatchInFlight` pinned, flush-on-
+ * hide inert) — the same hazard `withClearDataTimeout` already bounds on the
+ * sibling clear. Note the bound is NOT an `onblocked` substitute: these opens
+ * are versionless, so they never request a version change and can never fire
+ * `blocked` (only `deleteDatabase` and an upgrading open can). The deadline
+ * covers the general stall, not a version-change block.
+ */
+
+const REPLAY_OUTBOX_DB_PREFIX = 'ok-replay-outbox';
+const ENTRY_STORE_NAME = 'entry';
+const ENTRY_KEY = 'buffer';
+
+/**
+ * Deadline for one outbox operation (open + transaction). Generous relative to
+ * a local IDB round-trip: this bounds a pathological stall, it is not a
+ * latency budget.
+ */
+const REPLAY_OUTBOX_TIMEOUT_MS = 5_000;
+
+/**
+ * Thrown when an outbox operation misses {@link REPLAY_OUTBOX_TIMEOUT_MS}.
+ *
+ * Exported so the recycle path can tell a STALL from an IDB error — the same
+ * `failureKind: 'timeout' | 'rejected'` split `ClientPersistenceClearTimeoutError`
+ * drives on the sibling clear. They call for different operator responses: an
+ * error is a failed operation, a timeout means the storage layer is wedged and
+ * the recovery it was gating is stuck behind it.
+ */
+export class ReplayOutboxTimeoutError extends Error {
+ constructor(operation: string, docName: string) {
+ super(`[replay-outbox] ${operation} timed out after ${REPLAY_OUTBOX_TIMEOUT_MS}ms: ${docName}`);
+ this.name = 'ReplayOutboxTimeoutError';
+ }
+}
+
+function withOutboxTimeout<T>(operation: string, docName: string, work: Promise<T>): Promise<T> {
+ return new Promise<T>((resolve, reject) => {
+ const timer = setTimeout(() => {
+ reject(new ReplayOutboxTimeoutError(operation, docName));
+ }, REPLAY_OUTBOX_TIMEOUT_MS);
+ work.then(
+ (value) => {
+ clearTimeout(timer);
+ resolve(value);
+ },
+ (err: unknown) => {
+ clearTimeout(timer);
+ reject(err);
+ },
+ );
+ });
+}
+
+/**
+ * Whether this engine can carry a durable replay buffer at all. `databases()`
+ * is the gate for every operation, not just the reads — see the module note.
+ */
+function isReplayOutboxSupported(): boolean {
+ return typeof indexedDB !== 'undefined' && typeof indexedDB.databases === 'function';
+}
+
+/**
+ * Persisted shape of one doc's unsynced-edit buffer. Mirrors the in-memory
+ * `bufferedUpdates` value, except `fullState` is always present: the outbox is
+ * only written when content-level replay is possible (over-cap docs, whose
+ * `fullState` is dropped, stay RAM-only).
+ */
+export interface ReplayOutboxEntry {
+ readonly delta: Uint8Array;
+ readonly fullState: Uint8Array;
+}
+
+function outboxDbName(branch: string, docName: string): string {
+ return `${REPLAY_OUTBOX_DB_PREFIX}:${branch}:${docName}`;
+}
+
+function openOutboxDb(dbName: string): Promise<IDBDatabase> {
+ return new Promise((resolve, reject) => {
+ // Versionless open so the store-creation upgrade only runs when the DB is
+ // first created — matching y-indexeddb's own attach pattern.
+ const req = indexedDB.open(dbName);
+ req.onupgradeneeded = () => {
+ const db = req.result;
+ if (!db.objectStoreNames.contains(ENTRY_STORE_NAME)) {
+ db.createObjectStore(ENTRY_STORE_NAME);
+ }
+ };
+ req.onsuccess = () => resolve(req.result);
+ req.onerror = () => reject(req.error);
+ });
+}
+
+/**
+ * Whether an outbox DB already exists, WITHOUT creating one. `indexedDB.open`
+ * would create+upgrade a missing DB, littering an empty outbox on every normal
+ * doc open; gating reads/consumes on this keeps that from happening. Engines
+ * without `indexedDB.databases()` (pre-Baseline) report "absent" so durable
+ * recovery degrades to RAM-only rather than pollute storage.
+ *
+ * `databases()` enumerates ALL origin databases and runs on the first `synced`
+ * of a doc open (via `readReplayOutboxEntry`), so its cost scales with the
+ * origin's total database count, not just outbox DBs. The consumed-but-kept
+ * empty outboxes (see the module note) add to that count only per recycled
+ * `(branch, docName)` — a bounded subset dwarfed by the per-epoch y-indexeddb
+ * stores this call already lists — so retaining them is a storage-hygiene cost,
+ * not an enumeration-cost regression that would justify racing a `deleteDatabase`
+ * against a concurrent reopen.
+ */
+async function outboxDbExists(dbName: string): Promise<boolean> {
+ if (!isReplayOutboxSupported()) return false;
+ const dbs = await indexedDB.databases();
+ return dbs.some((d) => d.name === dbName);
+}
+
+/**
+ * Persist one doc's unsynced-edit buffer. Called during the mismatch recycle,
+ * BEFORE `clearData()`, so a crash while the y-indexeddb store is being wiped
+ * still leaves the buffer recoverable.
+ *
+ * Resolves `true` when the record committed and a later reopen can read it
+ * back, `false` when this engine cannot carry a durable buffer at all. The
+ * caller uses that to decide whether a durable copy backs its RAM buffer.
+ */
+export async function writeReplayOutboxEntry(
+ branch: string,
+ docName: string,
+ entry: ReplayOutboxEntry,
+): Promise<boolean> {
+ // No `databases()` means no reader will ever find this record: writing it
+ // would strand a full doc-state payload in storage with nothing able to
+ // consume or reclaim it. Report RAM-only instead.
+ if (!isReplayOutboxSupported()) return false;
+ const dbName = outboxDbName(branch, docName);
+ return withOutboxTimeout(
+ 'write',
+ docName,
+ (async () => {
+ const db = await openOutboxDb(dbName);
+ try {
+ await new Promise<void>((resolve, reject) => {
+ const tx = db.transaction(ENTRY_STORE_NAME, 'readwrite');
+ tx.objectStore(ENTRY_STORE_NAME).put(
+ { delta: entry.delta, fullState: entry.fullState },
+ ENTRY_KEY,
+ );
+ tx.oncomplete = () => resolve();
+ tx.onerror = () => reject(tx.error);
+ tx.onabort = () => reject(tx.error ?? new Error('replay-outbox write aborted'));
+ // Explicitly commit rather than waiting for the auto-commit that
+ // fires when the event loop next has no pending requests. This write
+ // exists to survive a tab death in the recycle window, and that death
+ // can land before the idle turn arrives, so starting the commit now
+ // shortens the window it has to survive. Handlers are attached first
+ // so none can be missed. Guarded — not every engine implements the
+ // (Baseline) method. Matches the flush path in client-persistence.ts.
+ if (typeof tx.commit === 'function') tx.commit();
+ });
+ return true;
+ } finally {
+ db.close();
+ }
+ })(),
+ );
+}
+
+/**
+ * Read a doc's persisted buffer, or null when none exists (normal open, or a
+ * consumed outbox). Never creates a DB for a doc that has no outbox.
+ */
+export async function readReplayOutboxEntry(
+ branch: string,
+ docName: string,
+): Promise<ReplayOutboxEntry | null> {
+ if (!isReplayOutboxSupported()) return null;
+ const dbName = outboxDbName(branch, docName);
+ return withOutboxTimeout(
+ 'read',
+ docName,
+ (async () => {
+ if (!(await outboxDbExists(dbName))) return null;
+ const db = await openOutboxDb(dbName);
+ try {
+ const value = await new Promise<unknown>((resolve, reject) => {
+ const tx = db.transaction(ENTRY_STORE_NAME, 'readonly');
+ const get = tx.objectStore(ENTRY_STORE_NAME).get(ENTRY_KEY);
+ get.onsuccess = () => resolve(get.result);
+ get.onerror = () => reject(get.error);
+ });
+ if (value === undefined || value === null) return null;
+ const record = value as { delta?: unknown; fullState?: unknown };
+ // A truncated/foreign record must read as "nothing to replay" rather
+ // than feed garbage bytes into the Y.Doc apply.
+ if (!(record.delta instanceof Uint8Array) || !(record.fullState instanceof Uint8Array)) {
+ return null;
+ }
+ return { delta: record.delta, fullState: record.fullState };
+ } finally {
+ db.close();
+ }
+ })(),
+ );
+}
+
+/**
+ * Consume a doc's buffer by deleting its record, and report whether THIS
+ * caller was the one that removed a live record.
+ *
+ * That boolean is the cross-tab exactly-once claim. Same-origin tabs share one
+ * `(branch, docName)` record, so a `false` return means another tab already
+ * consumed it and owns the replay — re-applying on top would not be idempotent
+ * (see `replayBufferedContent`'s surface attribution). The count and the delete
+ * run in ONE `readwrite` transaction and IndexedDB serializes overlapping
+ * readwrite transactions across connections, so the pair is an atomic
+ * compare-and-claim, not a check-then-act.
+ *
+ * Idempotent for callers that only want the record gone (consuming an absent
+ * record resolves `false` rather than throwing).
+ */
+export async function consumeReplayOutboxEntry(branch: string, docName: string): Promise<boolean> {
+ if (!isReplayOutboxSupported()) return false;
+ const dbName = outboxDbName(branch, docName);
+ return withOutboxTimeout(
+ 'consume',
+ docName,
+ (async () => {
+ if (!(await outboxDbExists(dbName))) return false;
+ const db = await openOutboxDb(dbName);
+ try {
+ return await new Promise<boolean>((resolve, reject) => {
+ const tx = db.transaction(ENTRY_STORE_NAME, 'readwrite');
+ const store = tx.objectStore(ENTRY_STORE_NAME);
+ let claimed = false;
+ const count = store.count(ENTRY_KEY);
+ count.onsuccess = () => {
+ claimed = count.result > 0;
+ };
+ store.delete(ENTRY_KEY);
+ tx.oncomplete = () => resolve(claimed);
+ tx.onerror = () => reject(tx.error);
+ tx.onabort = () => reject(tx.error ?? new Error('replay-outbox consume aborted'));
+ });
+ } finally {
+ db.close();
+ }
+ })(),
+ );
+}
diff --git a/packages/app/src/editor/source-mode-setup.ts b/packages/app/src/editor/source-mode-setup.ts
new file mode 100644
index 000000000..f3eead340
--- /dev/null
+++ b/packages/app/src/editor/source-mode-setup.ts
@@ -0,0 +1,73 @@
+/**
+ * CodeMirror extension bundle for the collaborative source editor.
+ *
+ * This is `codemirror`'s `basicSetup` with CodeMirror's own undo history
+ * (`history()` + `historyKeymap`) deliberately omitted. The source editor binds
+ * to a shared `Y.Text` via `y-codemirror.next`, whose `Y.UndoManager` tracks
+ * only the local sync origin — remote peers and agent writes arrive under other
+ * origins and are excluded. CodeMirror's native history is origin-blind: it
+ * captures the transactions `y-codemirror` dispatches to reflect remote/agent
+ * changes into the buffer, so a native undo can revert content the user never
+ * wrote. The source editor therefore runs a single undo authority — the
+ * origin-aware `Y.UndoManager`, driven by `yUndoManagerKeymap` at the call site.
+ *
+ * Everything else mirrors `basicSetup` verbatim; keep this in sync with the
+ * `codemirror` package's `basicSetup` when that dependency is bumped.
+ */
+
+import {
+ autocompletion,
+ closeBrackets,
+ closeBracketsKeymap,
+ completionKeymap,
+} from '@codemirror/autocomplete';
+import { defaultKeymap } from '@codemirror/commands';
+import {
+ bracketMatching,
+ defaultHighlightStyle,
+ foldGutter,
+ foldKeymap,
+ indentOnInput,
+ syntaxHighlighting,
+} from '@codemirror/language';
+import { lintKeymap } from '@codemirror/lint';
+import { highlightSelectionMatches, searchKeymap } from '@codemirror/search';
+import { EditorState, type Extension } from '@codemirror/state';
+import {
+ crosshairCursor,
+ drawSelection,
+ dropCursor,
+ highlightActiveLine,
+ highlightActiveLineGutter,
+ highlightSpecialChars,
+ keymap,
+ lineNumbers,
+ rectangularSelection,
+} from '@codemirror/view';
+
+export const sourceModeSetup: Extension = [
+ lineNumbers(),
+ highlightActiveLineGutter(),
+ highlightSpecialChars(),
+ foldGutter(),
+ drawSelection(),
+ dropCursor(),
+ EditorState.allowMultipleSelections.of(true),
+ indentOnInput(),
+ syntaxHighlighting(defaultHighlightStyle, { fallback: true }),
+ bracketMatching(),
+ closeBrackets(),
+ autocompletion(),
+ rectangularSelection(),
+ crosshairCursor(),
+ highlightActiveLine(),
+ highlightSelectionMatches(),
+ keymap.of([
+ ...closeBracketsKeymap,
+ ...defaultKeymap,
+ ...searchKeymap,
+ ...foldKeymap,
+ ...completionKeymap,
+ ...lintKeymap,
+ ]),
+];
diff --git a/packages/app/src/lib/desktop-bridge-types.ts b/packages/app/src/lib/desktop-bridge-types.ts
index e72158c3f..00b9a588e 100644
--- a/packages/app/src/lib/desktop-bridge-types.ts
+++ b/packages/app/src/lib/desktop-bridge-types.ts
@@ -1477,6 +1477,12 @@ export interface OkDesktopBridge {
* JSDoc in `packages/desktop/src/shared/bridge-contract.ts`.
*/
notifyViewMenuStateChanged(state: Partial<OkEditorViewMenuStateSnapshot>): void;
+ /**
+ * Fire-and-forget push keying the window's Chromium background-throttling
+ * to its unsynced work. See canonical JSDoc in
+ * `packages/desktop/src/shared/bridge-contract.ts`.
+ */
+ notifyBackgroundThrottle(signal: { hasPendingWork: boolean; enabled: boolean }): void;
};
/**
diff --git a/packages/app/src/lib/install-client-log-forwarder.test.ts b/packages/app/src/lib/install-client-log-forwarder.test.ts
index 0b4cb8ab9..eb1f807d7 100644
--- a/packages/app/src/lib/install-client-log-forwarder.test.ts
+++ b/packages/app/src/lib/install-client-log-forwarder.test.ts
@@ -1,6 +1,7 @@
import {
RENDERER_LOG_MAX_BATCH_BYTES,
RENDERER_LOG_MAX_ENTRIES,
+ RENDERER_LOG_MAX_MESSAGE_BYTES,
} from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, test, vi } from 'vitest';
import {
@@ -137,6 +138,28 @@ describe('installClientLogForwarder', () => {
expect(entries[0]?.ts).toBe(111);
});
+ test('scrubs credentials from the captured message before forwarding', () => {
+ const fetchSpy = makeFetchSpy();
+ const { con } = install(fetchSpy);
+ const secret = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';
+ con.error(`push failed with token ${secret}`);
+ handle?.flushNow();
+ const { entries } = bodyOf(fetchSpy);
+ expect(entries[0]?.message).not.toContain(secret);
+ expect(entries[0]?.message).toContain('[REDACTED-GH-PAT]');
+ });
+
+ test('keeps the 8192-byte message cap after scrubbing', () => {
+ const fetchSpy = makeFetchSpy();
+ const { con } = install(fetchSpy);
+ con.info('x'.repeat(RENDERER_LOG_MAX_MESSAGE_BYTES + 500));
+ handle?.flushNow();
+ const message = bodyOf(fetchSpy).entries[0]?.message as string;
+ // A 4096-tightened cap would fail the lower bound; the cap stays at 8192.
+ expect(message.length).toBeGreaterThan(4096);
+ expect(message.length).toBeLessThanOrEqual(RENDERER_LOG_MAX_MESSAGE_BYTES);
+ });
+
test('still calls the original console method', () => {
const fetchSpy = makeFetchSpy();
const { con } = install(fetchSpy);
diff --git a/packages/app/src/lib/install-client-log-forwarder.ts b/packages/app/src/lib/install-client-log-forwarder.ts
index 8a14be77d..414c50bf6 100644
--- a/packages/app/src/lib/install-client-log-forwarder.ts
+++ b/packages/app/src/lib/install-client-log-forwarder.ts
@@ -26,6 +26,7 @@ import {
RENDERER_LOG_MAX_BATCH_BYTES,
RENDERER_LOG_MAX_ENTRIES,
RENDERER_LOG_MAX_MESSAGE_BYTES,
+ scrubSecrets,
truncateLogMessage,
} from '@inkeep/open-knowledge-core';
@@ -233,7 +234,11 @@ export function installClientLogForwarder(
function captureConsole(level: ClientLogEntry['level'], args: unknown[]): void {
if (inForward) return;
try {
- const message = truncateLogMessage(args.map(stringifyArg).join(' '));
+ // Scrub credentials from the free-text message at capture time — verbatim
+ // console strings bypass the server's keyed-field pino redaction, so a
+ // secret logged as plain text would otherwise reach the local sink raw.
+ // Scrub before truncating so a secret straddling the byte cap is caught.
+ const message = truncateLogMessage(scrubSecrets(args.map(stringifyArg).join(' ')));
// Only attempt the structured JSON.parse on a reasonably-sized first arg —
// a multi-MB `console.log(hugeJsonString)` would otherwise block the
// caller's hot path parsing bytes we'd discard anyway (the message is
diff --git a/packages/app/src/lib/request-storage-persistence.test.ts b/packages/app/src/lib/request-storage-persistence.test.ts
new file mode 100644
index 000000000..b450c66da
--- /dev/null
+++ b/packages/app/src/lib/request-storage-persistence.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from 'vitest';
+import { requestStoragePersistence } from './request-storage-persistence';
+
+describe('requestStoragePersistence', () => {
+ it('calls navigator.storage.persist() when available and returns its result', async () => {
+ const persist = vi.fn().mockResolvedValue(true);
+ const nav = { storage: { persist } } as unknown as Navigator;
+
+ const granted = await requestStoragePersistence(nav);
+
+ expect(persist).toHaveBeenCalledTimes(1);
+ expect(granted).toBe(true);
+ });
+
+ it('returns false without throwing when the API is absent', async () => {
+ const granted = await requestStoragePersistence({} as Navigator);
+ expect(granted).toBe(false);
+ });
+
+ it('returns false without throwing when navigator is undefined', async () => {
+ const granted = await requestStoragePersistence(undefined);
+ expect(granted).toBe(false);
+ });
+
+ it('swallows a rejecting persist() and returns false', async () => {
+ const persist = vi.fn().mockRejectedValue(new Error('insecure context'));
+ const nav = { storage: { persist } } as unknown as Navigator;
+
+ const granted = await requestStoragePersistence(nav);
+
+ expect(persist).toHaveBeenCalledTimes(1);
+ expect(granted).toBe(false);
+ });
+});
diff --git a/packages/app/src/lib/request-storage-persistence.ts b/packages/app/src/lib/request-storage-persistence.ts
new file mode 100644
index 000000000..8716f8680
--- /dev/null
+++ b/packages/app/src/lib/request-storage-persistence.ts
@@ -0,0 +1,26 @@
+/**
+ * Ask the browser once, at app init, to make this origin's storage
+ * persistent so the IndexedDB CRDT cache is less likely to be evicted under
+ * storage pressure.
+ *
+ * Best-effort and non-authoritative: the server stays the source of truth, so
+ * this only hardens the local cache — it does not change the durability
+ * posture. `navigator.storage.persist` is a heuristic on Safari, and the API
+ * is absent in some environments (older engines, jsdom, insecure contexts),
+ * where the call is skipped. The `navigator` is a parameter so tests can drive
+ * the present / absent / rejecting cases without a global stub.
+ */
+export async function requestStoragePersistence(
+ nav: Navigator | undefined = typeof navigator !== 'undefined' ? navigator : undefined,
+): Promise<boolean> {
+ try {
+ const storage = nav?.storage;
+ if (storage === undefined || typeof storage.persist !== 'function') return false;
+ return await storage.persist();
+ } catch {
+ // Some engines throw (rather than resolve false) when persistence is
+ // unavailable or the context is insecure. A hardening request that fails
+ // must never break app init.
+ return false;
+ }
+}
diff --git a/packages/app/src/lib/server-info-refresh.ts b/packages/app/src/lib/server-info-refresh.ts
index 05bdef0eb..7669ee9d7 100644
--- a/packages/app/src/lib/server-info-refresh.ts
+++ b/packages/app/src/lib/server-info-refresh.ts
@@ -18,12 +18,15 @@
* `lastDiskAckedSV` watermark so the mismatch-recycle baseline-
* selection always operates on fresh data.
*
- * Idempotent: every dispatch path no-ops on unchanged inputs
- * (`setExpectedServerInstanceId` early-returns on matching IDs;
- * `compareAndUpdateObservedBranch` returns false unless the branch
- * actually changed; `observeDiskAckBatch` overwrites in-place). Safe
- * to call on every `synced` event without producing redundant
- * recycles.
+ * Mostly idempotent: `compareAndUpdateObservedBranch` returns false
+ * unless the branch actually changed, and `observeDiskAckBatch`
+ * overwrites in-place. `setExpectedServerInstanceId` is NOT — the pool
+ * assigns unconditionally (see provider-pool.ts), so a refresh that
+ * observes a rotated server id overwrites the cached epoch even while
+ * per-doc providers are still learning of the rotation through auth
+ * rejection, and their recycle dedupe then compares against the
+ * already-updated value. Do not rely on this path to no-op on
+ * unchanged ids until the pool owns epoch transitions.
*
* Silent on failure: endpoint unavailability falls back to the
* existing recovery paths (auth-token-claim mismatch on next provider
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 3556b10fa..6a6b03722 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -648,6 +648,7 @@
["DEFAULT_EMBEDDINGS_MODEL"],
"."
],
+ "C-twqs": ["Recovered content"],
"C-xgad": ["or use a starter pack"],
"C0hoX6": ["Always included"],
"C62P6b": ["Editor selection"],
@@ -1593,9 +1594,6 @@
"UDFrWm": ["Checking GitHub connection..."],
"UGeJuP": ["Allowed values (empty = any)"],
"UL8A9w": ["Tag"],
- "ULRb5t": [
- "Adds telemetry, server state, and runtime info when available. Document names are anonymized."
- ],
"UMrOy2": ["Skill \"", ["trimmedName"], "\" created"],
"UPjaXD": ["Couldn't duplicate \"", ["0"], "\": ", ["1"]],
"UQAp48": ["Search templates"],
@@ -2215,6 +2213,9 @@
"fJgQHX": ["Failed to create file"],
"fNr-MX": ["Disable semantic search"],
"fR-Kdc": ["(project-level only)"],
+ "fRVBiq": [
+ "Adds telemetry, server state, and runtime info when available. Credentials are always removed; document names, if included, appear in cleartext (not redacted)."
+ ],
"fSRzLo": ["Show document panel"],
"fVcm9t": [["0", "plural", { "one": ["#", " doc"], "other": ["#", " docs"] }]],
"fWi7pn": ["Initialize starter pack"],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index 33d026ab0..370342bd4 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -1002,8 +1002,8 @@ msgid "Adds a managed block to {0}"
msgstr "Adds a managed block to {0}"
#: src/components/ReportBugDialogBody.tsx
-msgid "Adds telemetry, server state, and runtime info when available. Document names are anonymized."
-msgstr "Adds telemetry, server state, and runtime info when available. Document names are anonymized."
+msgid "Adds telemetry, server state, and runtime info when available. Credentials are always removed; document names, if included, appear in cleartext (not redacted)."
+msgstr "Adds telemetry, server state, and runtime info when available. Credentials are always removed; document names, if included, appear in cleartext (not redacted)."
#: src/components/InstallInClaudeDesktopDialog.tsx
msgid "Adds the OpenKnowledge skill to the <0>Claude Desktop App</0> so it's available in Chat and Cowork sessions."
@@ -7404,6 +7404,10 @@ msgstr "Reconnecting to the agent service…"
msgid "Reconnecting…"
msgstr "Reconnecting…"
+#: src/components/TimelinePanel.tsx
+msgid "Recovered content"
+msgstr "Recovered content"
+
#: src/components/AppMenubar.tsx
msgid "Redo"
msgstr "Redo"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 8e21a9180..4e006502b 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -648,6 +648,7 @@
["DEFAULT_EMBEDDINGS_MODEL"],
"."
],
+ "C-twqs": ["Ŕēćōvēŕēď ćōńţēńţ"],
"C-xgad": ["ōŕ ũśē à śţàŕţēŕ ƥàćķ"],
"C0hoX6": ["Àĺŵàŷś ĩńćĺũďēď"],
"C62P6b": ["Ēďĩţōŕ śēĺēćţĩōń"],
@@ -1593,9 +1594,6 @@
"UDFrWm": ["Ćĥēćķĩńĝ ĜĩţĤũƀ ćōńńēćţĩōń..."],
"UGeJuP": ["Àĺĺōŵēď vàĺũēś (ēḿƥţŷ = àńŷ)"],
"UL8A9w": ["Ţàĝ"],
- "ULRb5t": [
- "Àďďś ţēĺēḿēţŕŷ, śēŕvēŕ śţàţē, àńď ŕũńţĩḿē ĩńƒō ŵĥēń àvàĩĺàƀĺē. Ďōćũḿēńţ ńàḿēś àŕē àńōńŷḿĩźēď."
- ],
"UMrOy2": ["Śķĩĺĺ \"", ["trimmedName"], "\" ćŕēàţēď"],
"UPjaXD": ["Ćōũĺďń'ţ ďũƥĺĩćàţē \"", ["0"], "\": ", ["1"]],
"UQAp48": ["Śēàŕćĥ ţēḿƥĺàţēś"],
@@ -2215,6 +2213,9 @@
"fJgQHX": ["Ƒàĩĺēď ţō ćŕēàţē ƒĩĺē"],
"fNr-MX": ["Ďĩśàƀĺē śēḿàńţĩć śēàŕćĥ"],
"fR-Kdc": ["(ƥŕōĴēćţ-ĺēvēĺ ōńĺŷ)"],
+ "fRVBiq": [
+ "Àďďś ţēĺēḿēţŕŷ, śēŕvēŕ śţàţē, àńď ŕũńţĩḿē ĩńƒō ŵĥēń àvàĩĺàƀĺē. Ćŕēďēńţĩàĺś àŕē àĺŵàŷś ŕēḿōvēď; ďōćũḿēńţ ńàḿēś, ĩƒ ĩńćĺũďēď, àƥƥēàŕ ĩń ćĺēàŕţēxţ (ńōţ ŕēďàćţēď)."
+ ],
"fSRzLo": ["Śĥōŵ ďōćũḿēńţ ƥàńēĺ"],
"fVcm9t": [["0", "plural", { "one": ["#", " ďōć"], "other": ["#", " ďōćś"] }]],
"fWi7pn": ["Ĩńĩţĩàĺĩźē śţàŕţēŕ ƥàćķ"],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index e423f3320..009baba54 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -998,7 +998,7 @@ msgid "Adds a managed block to {0}"
msgstr ""
#: src/components/ReportBugDialogBody.tsx
-msgid "Adds telemetry, server state, and runtime info when available. Document names are anonymized."
+msgid "Adds telemetry, server state, and runtime info when available. Credentials are always removed; document names, if included, appear in cleartext (not redacted)."
msgstr ""
#: src/components/InstallInClaudeDesktopDialog.tsx
@@ -7400,6 +7400,10 @@ msgstr ""
msgid "Reconnecting…"
msgstr ""
+#: src/components/TimelinePanel.tsx
+msgid "Recovered content"
+msgstr ""
+
#: src/components/AppMenubar.tsx
msgid "Redo"
msgstr ""
diff --git a/packages/app/src/main.tsx b/packages/app/src/main.tsx
index 2b387a349..ccf11c9be 100644
--- a/packages/app/src/main.tsx
+++ b/packages/app/src/main.tsx
@@ -53,6 +53,7 @@ import {
shouldInstallColdMountInstrumentation,
} from '@/lib/perf/cold-mount-instrumentation';
import { installRelaunchStateBridge } from '@/lib/relaunch-store';
+import { requestStoragePersistence } from '@/lib/request-storage-persistence';
import { installShareReceivedListener } from '@/lib/share/receive-store';
import { seedInitialDocHashFromWindow } from '@/lib/single-file-initial-doc';
import { installSubscribeCardStore } from '@/lib/subscribe-card-store';
@@ -88,6 +89,11 @@ installClientFetchWrapper({
// carries version headers + same-origin routing.
installClientLogForwarder();
+// Ask once for persistent origin storage so the browser is less likely to
+// evict the IndexedDB CRDT cache under storage pressure. Best-effort and
+// non-authoritative — the server stays the source of truth.
+void requestStoragePersistence();
+
// Install cold-mount instrumentation BEFORE any editor module loads — the
// prototype patches must be in place before the first `new Editor(...)` call.
// Marks emit in DEV/test by default; the `VITE_OK_PERF_INSTRUMENT=1` env-var
diff --git a/packages/app/tests/dom/jsdom-preload.ts b/packages/app/tests/dom/jsdom-preload.ts
index adb8a2be7..14772a7b9 100644
--- a/packages/app/tests/dom/jsdom-preload.ts
+++ b/packages/app/tests/dom/jsdom-preload.ts
@@ -65,25 +65,35 @@ if (domWindow?.HTMLElement) {
domWindow.HTMLElement.prototype.scrollIntoView ||= () => {};
}
-// jsdom doesn't implement layout, so `Range` has no `getClientRects` /
-// `getBoundingClientRect`. ProseMirror measures a text Range on every
-// selection scroll (`coordsAtPos` → `singleRect`), and TipTap dispatches that
-// scroll ASYNCHRONOUSLY — so the resulting TypeError lands after the test that
-// triggered it has finished, where vitest can only report it as an unhandled
-// error and fail the whole run. Backfilling the two methods removes the throw
-// at its source; empty rects are the honest answer in a layout-free DOM, and
-// PM already treats a zero rect as "unmeasurable".
-if (domWindow?.Range && typeof domWindow.Range.prototype.getClientRects !== 'function') {
- Object.defineProperty(domWindow.Range.prototype, 'getClientRects', {
- configurable: true,
- value: () => [],
- });
-}
-if (domWindow?.Range && typeof domWindow.Range.prototype.getBoundingClientRect !== 'function') {
- Object.defineProperty(domWindow.Range.prototype, 'getBoundingClientRect', {
- configurable: true,
- value: () => ({ bottom: 0, height: 0, left: 0, right: 0, top: 0, width: 0 }),
- });
+// jsdom has no layout, so the geometry pair ProseMirror needs to place a
+// selection is missing on some node types. `singleRect` calls
+// `target.getClientRects()` and falls back to `target.getBoundingClientRect()`,
+// and a scroll-into-view that lands after a test's editor is gone surfaces as
+// an UNCAUGHT exception rather than a test failure — every test passes and the
+// run still exits non-zero. Supply both as empty/zero geometry so the fallback
+// path resolves instead of throwing. Only fills genuine gaps; a real browser
+// and any jsdom build that implements these keep their own.
+const ZERO_RECT = {
+ x: 0,
+ y: 0,
+ top: 0,
+ left: 0,
+ right: 0,
+ bottom: 0,
+ width: 0,
+ height: 0,
+ toJSON() {
+ return this;
+ },
+};
+for (const ctor of [domWindow?.Range, domWindow?.Element, domWindow?.Text]) {
+ if (!ctor) continue;
+ const proto = ctor.prototype as {
+ getClientRects?: () => unknown;
+ getBoundingClientRect?: () => unknown;
+ };
+ proto.getClientRects ||= () => [];
+ proto.getBoundingClientRect ||= () => ZERO_RECT;
}
// jsdom doesn't ship MessageChannel; React 19's scheduler uses it for postTask
diff --git a/packages/app/tests/integration/bridge-loss-injection.test.ts b/packages/app/tests/integration/bridge-loss-injection.test.ts
new file mode 100644
index 000000000..1d5efff35
--- /dev/null
+++ b/packages/app/tests/integration/bridge-loss-injection.test.ts
@@ -0,0 +1,295 @@
+/**
+ * H3 public-path loss injection: drive a paired-intake content loss through the
+ * REAL boot path — `createServer` wires the loss ring + the derive-loss reporter
+ * to the agent-write spine (`session.bridgeLossReporter`) — and assert the
+ * detector fires a content-free ring event + a restorable shadow-git checkpoint.
+ *
+ * The un-propagated window is staged on the booted server's own Y.Doc via a
+ * freshness-suppressed Observer A settlement (a component's advanced children
+ * while Y.Text lags), the same technique the derive-timing full-flow rig uses;
+ * only `Date` is faked so the real WS + async I/O proceed. The derive-timing
+ * defer guard is config-disabled so the loss path is exercised (paired vectors
+ * don't defer, but disabling it removes any interaction).
+ *
+ * Direction coverage split by achievable rung: this suite owns the B /
+ * paired-intake direction end to end for both of its vectors — the agent write
+ * (through a public HTTP path) and the passive disk intake (through the real
+ * file watcher the harness already runs). The Observer-A (fragment→Y.Text) apply
+ * direction stays injection-tested at the server rung
+ * (`bridge-loss-detector.test.ts`); its seam has no booted driver.
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
+import { getSchema, type JSONContent } from '@tiptap/core';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import type * as Y from 'yjs';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { createTestServer, getServerState, mdManager, type TestServer } from './test-harness.ts';
+
+const schema = getSchema(sharedExtensions);
+// The server serializes freshness-ON (its md-manager singleton), so a component's
+// advanced children reach the detector; the harness `mdManager` is freshness-OFF.
+const freshMdManager = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+});
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+const STALE_LINE = 'Step one bod';
+// A distinctive whole-line replacement: the pending content must be its own
+// unique segment (a 2-char edit like `bod`→`body.` collides with common
+// substrings of the replacement content and the segment diff filters it out).
+const PENDING_LINE = 'Zzz unpropagated pending sentinel keystroke.';
+
+interface LossRingEvent {
+ event: string;
+ docName: string;
+ site?: string;
+ direction?: string;
+ writerId?: string | null;
+ lostLen?: number;
+ digest?: string;
+ checkpointSha?: string;
+}
+
+function mutateFirstText(node: JSONContent, from: string, to: string): boolean {
+ if (typeof node.text === 'string' && node.text === from) {
+ node.text = to;
+ return true;
+ }
+ for (const child of node.content ?? []) {
+ if (mutateFirstText(child, from, to)) return true;
+ }
+ return false;
+}
+
+/** Freshness-ON serialize — sees a component's live children, not stale sourceRaw. */
+function serializeFragment(fragment: Y.XmlFragment): string {
+ return freshMdManager.serialize(yXmlFragmentToProseMirrorRootNode(fragment, schema).toJSON());
+}
+
+/** Read the content-free loss ring straight off disk (no server-internal import). */
+function readLossEvents(contentDir: string): LossRingEvent[] {
+ try {
+ const raw = readFileSync(
+ join(contentDir, '.ok', 'local', 'loss-capture', 'loss-current.jsonl'),
+ 'utf-8',
+ );
+ return raw
+ .split('\n')
+ .filter((line) => line.length > 0)
+ .flatMap((line) => {
+ try {
+ return [JSON.parse(line) as LossRingEvent];
+ } catch {
+ return [];
+ }
+ });
+ } catch {
+ return [];
+ }
+}
+
+async function pollForTrip(
+ contentDir: string,
+ predicate: (e: LossRingEvent) => boolean,
+ timeoutMs = 8000,
+): Promise<LossRingEvent> {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ const found = readLossEvents(contentDir).find(predicate);
+ if (found) return found;
+ await new Promise((r) => setTimeout(r, 25));
+ }
+ throw new Error('timed out waiting for a detector-trip loss-ring event');
+}
+
+/**
+ * Stage a fragment-ahead-of-Y.Text divergence on the booted server's own doc:
+ * poke Y.Text to reset the freshness clock, then advance the component children
+ * to `PENDING_LINE` while `sourceRaw` lags → Observer A settles on the stale
+ * bytes, leaving the fragment holding content Y.Text lacks.
+ */
+function stageUnpropagatedKeystroke(doc: Y.Doc, ytext: Y.Text, fragment: Y.XmlFragment): void {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(Date.now() + 10_000);
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nTrailing.\n');
+ }, 'external-peer');
+ const echo = mdManager.parse(ytext.toString()) as JSONContent;
+ expect(mutateFirstText(echo, STALE_LINE, PENDING_LINE)).toBe(true);
+ doc.transact(() => {
+ updateYFragment(doc, fragment, schema.nodeFromJSON(echo), {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ }, 'wysiwyg-echo');
+ expect(serializeFragment(fragment)).toContain(PENDING_LINE);
+ expect(ytext.toString()).not.toContain(PENDING_LINE);
+ vi.useRealTimers();
+}
+
+/** A fresh contentDir with the derive-timing defer guard disabled in `.ok/config.yml`. */
+function guardDisabledContentDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-loss-injection-'));
+ mkdirSync(join(dir, '.ok'), { recursive: true });
+ writeFileSync(join(dir, '.ok', 'config.yml'), 'bridge:\n deferGuard:\n enabled: false\n');
+ return dir;
+}
+
+describe('H3 paired-intake loss injection through public paths', () => {
+ let server: TestServer;
+
+ beforeEach(async () => {
+ server = await createTestServer({
+ contentDir: guardDisabledContentDir(),
+ gitEnabled: true,
+ // Pin persistence off-disk so a debounced flush never overwrites the staged
+ // divergence mid-test.
+ debounce: 300_000,
+ maxDebounce: 600_000,
+ });
+ }, HARNESS_BOOT_TIMEOUT_MS);
+
+ afterEach(async () => {
+ vi.useRealTimers();
+ await server.cleanup();
+ });
+
+ test('agent-write overwrite of un-propagated content trips the detector and checkpoints', async () => {
+ const docName = `loss-agent-${crypto.randomUUID().slice(0, 8)}`;
+ const created = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ markdown: GEN1, position: 'replace', docName }),
+ });
+ expect(created.status).toBe(200);
+
+ const state = getServerState(server, docName);
+ const doc = server.instance.hocuspocus.documents.get(docName) as unknown as Y.Doc;
+ stageUnpropagatedKeystroke(doc, state?.ytext as Y.Text, state?.fragment as Y.XmlFragment);
+
+ // Public path: an agent REPLACE that rebuilds the fragment over the pending
+ // keystroke — the write-surface spine threads the loss detector.
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ markdown: '## Guide\n\nIntro paragraph.\n\nReplaced body.\n',
+ position: 'replace',
+ docName,
+ }),
+ });
+ expect(res.status).toBe(200);
+
+ const trip = await pollForTrip(
+ server.contentDir,
+ (e) =>
+ e.event === 'detector-trip' &&
+ e.site === 'agent-write-intake' &&
+ e.docName === docName &&
+ Boolean(e.checkpointSha),
+ );
+ expect(trip.direction).toBe('b');
+ // At-risk bytes, not a type check: `lostLen: 0` means nothing was judged
+ // lost, which is the outcome this test exists to rule out. Bound it by the
+ // pending line the staging actually put at risk.
+ expect(trip.lostLen).toBeGreaterThanOrEqual(PENDING_LINE.length);
+ // Content-free ring: never the lost bytes.
+ expect(JSON.stringify(trip)).not.toContain(PENDING_LINE);
+
+ // The checkpoint is restorable through the ordinary history surface.
+ const hist = await fetch(`http://127.0.0.1:${server.port}/api/history?docName=${docName}`).then(
+ (r) => r.json(),
+ );
+ const row = hist.entries.find(
+ (e: { sha: string; checkpoint?: { kind?: string } }) => e.sha === trip.checkpointSha,
+ );
+ expect(row?.checkpoint?.kind).toBe('bridge-derive-loss');
+ });
+
+ /**
+ * The passive vector: nobody asked for a write. A `git pull` or an external
+ * editor save lands on a doc that is OPEN and dirty, and the intake rebuilds
+ * the fragment from the disk bytes over the un-propagated keystroke. Only the
+ * booted rung observes it end to end — the reporter the file-watcher intake
+ * receives is built inside `createServer` and handed to `applyToDoc`, so a
+ * server-rung test that passes its OWN reporter into `applyExternalChange`
+ * cannot tell whether that hand-off exists.
+ *
+ */
+ test('an out-of-band disk edit over un-propagated content trips the detector and checkpoints', async () => {
+ const docName = `loss-watcher-${crypto.randomUUID().slice(0, 8)}`;
+ const created = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ markdown: GEN1, position: 'replace', docName }),
+ });
+ expect(created.status).toBe(200);
+
+ // The agent write forces its own flush, so the file is on disk and the
+ // reconcile base points at it — the state a foreign edit diverges FROM.
+ const filePath = join(server.contentDir, `${docName}.md`);
+ await vi.waitFor(() => {
+ expect(readFileSync(filePath, 'utf-8')).toContain('Step one bod');
+ });
+ // Let the watcher consume its own-write event for that flush first. Two
+ // writes to one file inside a single watcher batch coalesce into ONE event,
+ // and the coalesced event is classified against the FIRST write's hash —
+ // the foreign edit below would be swallowed as a self-write.
+ await new Promise((r) => setTimeout(r, 1_000));
+
+ const state = getServerState(server, docName);
+ const doc = server.instance.hocuspocus.documents.get(docName) as unknown as Y.Doc;
+ const ytext = state?.ytext as Y.Text;
+ const fragment = state?.fragment as Y.XmlFragment;
+ stageUnpropagatedKeystroke(doc, ytext, fragment);
+
+ // A foreign writer (git checkout, VS Code save) edits a DIFFERENT region of
+ // the same file. The watcher's three-way merge reads `ours` from Y.Text, so
+ // the pending fragment keystroke is not in the merged content and the
+ // rebuild discards it.
+ writeFileSync(
+ filePath,
+ GEN1.replace('Intro paragraph.', 'Intro paragraph, edited out of band.'),
+ 'utf-8',
+ );
+ // The window really was still open when the disk edit landed.
+ expect(serializeFragment(fragment)).toContain(PENDING_LINE);
+ expect(ytext.toString()).not.toContain(PENDING_LINE);
+
+ const trip = await pollForTrip(
+ server.contentDir,
+ (e) =>
+ e.event === 'detector-trip' &&
+ e.site === 'file-watcher-intake' &&
+ e.docName === docName &&
+ Boolean(e.checkpointSha),
+ 15_000,
+ );
+ expect(trip.direction).toBe('b');
+ // The disk write is the writer of record, not the agent that opened the doc.
+ expect(trip.writerId).toBe('file-system');
+ expect(trip.lostLen).toBeGreaterThanOrEqual(PENDING_LINE.length);
+ expect(JSON.stringify(trip)).not.toContain(PENDING_LINE);
+
+ // Detection is not a veto: the disk edit still lands.
+ await vi.waitFor(() => {
+ expect(ytext.toString()).toContain('edited out of band');
+ });
+
+ // ...and the discarded keystroke is restorable through the ordinary
+ // history surface, which is the whole point of checkpointing it.
+ const hist = await fetch(`http://127.0.0.1:${server.port}/api/history?docName=${docName}`).then(
+ (r) => r.json(),
+ );
+ const row = hist.entries.find(
+ (e: { sha: string; checkpoint?: { kind?: string } }) => e.sha === trip.checkpointSha,
+ );
+ expect(row?.checkpoint?.kind).toBe('bridge-derive-loss');
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/bug-d-v0-14-agent-undo-under-concurrent-typing.test.ts b/packages/app/tests/integration/bug-d-v0-14-agent-undo-under-concurrent-typing.test.ts
index f30d42ed4..d0a160182 100644
--- a/packages/app/tests/integration/bug-d-v0-14-agent-undo-under-concurrent-typing.test.ts
+++ b/packages/app/tests/integration/bug-d-v0-14-agent-undo-under-concurrent-typing.test.ts
@@ -1,21 +1,15 @@
/**
- * SKIP-GUARDED: UNSKIP when the per-agent UM + agent-undo handler is wired.
+ * Mechanism illustration: the naive rebuild-from-Y.Text pattern
+ * (`syncTextToFragmentLocal`, a local replica) stomps concurrent user
+ * XmlFragment content when Y.Text is a generation behind — the same
+ * un-propagated-keystroke shape as the forward-write path.
*
- * These tests assert that the post-undo rebuild preserves user's concurrent
- * XmlFragment content: the naive rebuild-from-Y.Text pattern
- * (syncTextToFragment) destroys concurrent user XmlFragment content on the
- * undo path — identical stomp shape to the forward-write path.
- *
- * The fix deleted
- * syncTextToFragment and documented the XmlFragment-authoritative fix
- * pattern (applyAgentMarkdownWrite, precedent #10); the undo handler is
- * implemented using that pattern. See:
- * - applyAgentMarkdownWrite in agent-sessions.ts as the pickup template
- *
- * Test 1: Pure mechanism — syncTextToFragment with stale Y.Text
- * destroys XmlFragment content.
- * Test 2: realistic flow — post-undo syncTextToFragment
- * destroys new user XmlFragment keystroke.
+ * This suite pins the stomp on a REPLICA, not the production drain. The
+ * authoritative gate for the class on the real `setupServerObservers` drain is
+ * the derive-timing defer guard suite (`derive-timing-guard.test.ts`): it drives
+ * the production Observer B re-derive and asserts the pending keystroke survives
+ * (RED→GREEN) with the guard ON and stomps with it OFF. Keep these two tests as
+ * the reduced illustration of what that guard prevents.
*/
import { prependFrontmatter, stripFrontmatter } from '@inkeep/open-knowledge-core';
diff --git a/packages/app/tests/integration/composition-sweep-index.test.ts b/packages/app/tests/integration/composition-sweep-index.test.ts
new file mode 100644
index 000000000..73e62232a
--- /dev/null
+++ b/packages/app/tests/integration/composition-sweep-index.test.ts
@@ -0,0 +1,388 @@
+/**
+ * Composition sweep index (H13) — every shipped loss-hardening mechanism is
+ * observed IN COMPOSITION (the whole drain/server/client running, effect visible
+ * through a surface), not merely unit-tested in isolation. Module coverage is not
+ * composition coverage.
+ *
+ * This index enumerates the shipped mechanisms and FAILS if any lacks a
+ * registered composition row, or a row's test is missing. Each row is classified
+ * by the highest ACHIEVABLE rung:
+ * - `booted-server` — real `createServer` boot, effect observed through a
+ * public surface (HTTP / `getServerState` / the ring on
+ * disk), no internal guard import. The ideal.
+ * - `real-drain-rig` — the real `setupServerObservers` drain via the shared
+ * bridge-race rig (real production code, full composition),
+ * used where the trigger cannot be staged through a pure
+ * public HTTP path.
+ * - `client-rig` — the real client `ProviderPool` + a restartable server;
+ * the client recycle path has no server-side public surface.
+ * - `desktop-unit` — Electron main-process predicate; there is no R-server
+ * surface for it.
+ *
+ * Fidelity residuals (carried per SPEC §9.5, NOT claimed as public coverage):
+ * §9.5(1) — the re-derive backstop's echo/oscillation topology and the
+ * sustained-defer exhaustion trigger are not organically reachable
+ * through a pure public HTTP path; the real-drain rig is their rung.
+ * §9.5(3) — the desktop background-throttle behavioral observable rides the
+ * REQUIRED desktop-smoke CI tier (promoted 2026-06-26), which
+ * currently contains no throttle test; only its keying predicate is
+ * merge-gated at the unit rung.
+ * The named R7 row — typed content persists while the B re-derive loop is frozen
+ * — is present at the real-drain rig rung.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ConfigSchema } from '@inkeep/open-knowledge-core';
+import { describe, expect, test } from 'vitest';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// .../packages/app/tests/integration → .../packages
+const PACKAGES = resolve(HERE, '../../..');
+
+type Rung = 'booted-server' | 'real-drain-rig' | 'client-rig' | 'desktop-unit';
+
+interface CompositionRow {
+ /** Stable mechanism key (matches SHIPPED_MECHANISMS). */
+ readonly mechanism: string;
+ /** Package-relative path of the composition test. */
+ readonly file: string;
+ /** Distinctive substring of the composition test's title. */
+ readonly title: string;
+ readonly rung: Rung;
+ /** Required for non-`booted-server` rungs: why a pure public row is not reached. */
+ readonly residual?: string;
+}
+
+/**
+ * The canonical set of shipped loss-hardening mechanisms. A mechanism here with
+ * no composition row (below) fails the sweep; a row for a mechanism not here is
+ * stale.
+ */
+const SHIPPED_MECHANISMS = [
+ 'defer-guard',
+ 'defer-exhaustion',
+ 'loss-detector',
+ 'paired-intake-detect',
+ 'fixed-point-backstop',
+ 'loss-capture-ring',
+ 'checkpoint-restore-floor',
+ 'durable-replay-outbox',
+ 'flush-on-hide',
+ 'desktop-background-throttle',
+ 'pre-drain',
+] as const;
+
+const COMPOSITION_ROWS: readonly CompositionRow[] = [
+ {
+ mechanism: 'defer-guard',
+ file: 'app/tests/integration/derive-timing-guard-full-flow.test.ts',
+ title: 'the config-wired guard preserves an un-propagated keystroke on the real server',
+ rung: 'booted-server',
+ },
+ {
+ mechanism: 'defer-exhaustion',
+ file: 'server/src/derive-timing-exhaustion.test.ts',
+ title: 'sustained deferral preserves the keystroke until the guard force-resolves loudly',
+ rung: 'real-drain-rig',
+ residual:
+ '§9.5(1): the sustained-defer exhaustion trigger is not stageable through a pure public HTTP path.',
+ },
+ {
+ mechanism: 'loss-detector',
+ file: 'app/tests/integration/bridge-loss-injection.test.ts',
+ title: 'agent-write overwrite of un-propagated content trips the detector and checkpoints',
+ rung: 'booted-server',
+ },
+ {
+ // The disk-intake vector, deliberately NOT the agent-write test the
+ // `loss-detector` row above already anchors: the two reporter hand-offs are
+ // independently droppable, so one shared row would certify both while only
+ // one is observed.
+ mechanism: 'paired-intake-detect',
+ file: 'app/tests/integration/bridge-loss-injection.test.ts',
+ title: 'an out-of-band disk edit over un-propagated content trips the detector and checkpoints',
+ rung: 'booted-server',
+ },
+ {
+ mechanism: 'fixed-point-backstop',
+ file: 'server/src/derive-fixed-point-backstop.test.ts',
+ title:
+ 'typing during a freeze persists — the user-edit path and Y.Text stay live while the B loop is frozen',
+ rung: 'real-drain-rig',
+ residual:
+ '§9.5(1): the backstop echo/oscillation topology is not reachable at the public rung; the real production drain is its rung.',
+ },
+ {
+ mechanism: 'loss-capture-ring',
+ file: 'app/tests/integration/loss-capture-killswitch.test.ts',
+ title: 'ON (default): a defer lands a content-free guard-defer event in the ring',
+ rung: 'booted-server',
+ },
+ {
+ mechanism: 'checkpoint-restore-floor',
+ file: 'app/tests/integration/silent-checkpoint-restore.test.ts',
+ title: 'a silent extension-less checkpoint surfaces in history, reads back, and restores',
+ rung: 'booted-server',
+ },
+ {
+ mechanism: 'durable-replay-outbox',
+ file: 'app/tests/integration/replay-outbox-durable.test.ts',
+ title:
+ 'unsynced edit survives the same-tab recycle and its durable outbox is written then consumed',
+ rung: 'client-rig',
+ residual:
+ 'The client ProviderPool recycle path has no server-side public surface; the composition rung is the real client pool + a restartable server.',
+ },
+ {
+ mechanism: 'flush-on-hide',
+ file: 'app/tests/integration/editor-lifecycle-flush.test.ts',
+ title: 'force-sync flush lands a pending delta on the SERVER (IDB-only would not)',
+ rung: 'booted-server',
+ },
+ {
+ mechanism: 'desktop-background-throttle',
+ file: 'desktop/src/main/background-throttle.test.ts',
+ title: 'keeps timers alive (setBackgroundThrottling false) when work is pending and enabled',
+ rung: 'desktop-unit',
+ residual:
+ '§9.5(3): Electron main-process mechanism — the behavioral observable rides the required desktop-smoke CI tier, which contains no throttle test today; only the keying predicate is merge-gated here.',
+ },
+ {
+ mechanism: 'pre-drain',
+ file: 'app/tests/integration/pre-drain-composition.test.ts',
+ title: 'cross-block keystroke survives a paired derive while a client reconnects and resyncs',
+ rung: 'booted-server',
+ },
+];
+
+/**
+ * Every kill-switch this project ships, read off the PRODUCTION config schema
+ * at runtime rather than restated here, mapped to the mechanism it gates.
+ *
+ * `SHIPPED_MECHANISMS` and `COMPOSITION_ROWS` are both hand-maintained, so
+ * comparing them only against each other cannot notice a mechanism left out of
+ * BOTH. This is the external anchor: adding a kill-switch to `ConfigSchema`
+ * without registering its mechanism here fails the sweep. The four mechanisms
+ * with no kill-switch (`defer-exhaustion` is a bound inside the defer guard;
+ * `paired-intake-detect` rides the loss detector's classification registry;
+ * `checkpoint-restore-floor` and `durable-replay-outbox` are unconditional
+ * recovery floors) are necessarily absent from this map.
+ */
+const KILL_SWITCH_MECHANISM: Readonly<Record<string, string>> = {
+ lossCapture: 'loss-capture-ring',
+ 'bridge.backgroundThrottle': 'desktop-background-throttle',
+ 'bridge.deferGuard': 'defer-guard',
+ 'bridge.lossDetector': 'loss-detector',
+ 'bridge.fixedPoint': 'fixed-point-backstop',
+ 'bridge.preDrain': 'pre-drain',
+ 'bridge.flushOnHide': 'flush-on-hide',
+};
+
+interface ZodLike {
+ shape?: Record<string, ZodLike>;
+ def?: { innerType?: ZodLike };
+}
+
+/** Unwrap `.default()` / `.optional()` wrappers to reach the object's shape. */
+function objectShape(node: ZodLike | undefined): Record<string, ZodLike> | undefined {
+ let cur = node;
+ for (let i = 0; cur && i < 8; i++) {
+ if (cur.shape) return cur.shape;
+ cur = cur.def?.innerType;
+ }
+ return undefined;
+}
+
+/**
+ * Kill-switch paths declared in the schema SHAPE.
+ *
+ * Deliberately not `ConfigSchema.parse({})`: the `bridge` node carries a
+ * hand-written `.default({...})` literal, so parsing an empty config returns
+ * that literal's keys and a newly declared switch missing from it would slip
+ * through. The shape is the declaration itself.
+ */
+function shippedKillSwitchPaths(): string[] {
+ const root = objectShape(ConfigSchema as unknown as ZodLike) ?? {};
+ const paths: string[] = [];
+ if (root.lossCapture) paths.push('lossCapture');
+ for (const key of Object.keys(objectShape(root.bridge) ?? {})) paths.push(`bridge.${key}`);
+ return paths.sort();
+}
+
+/** Mechanisms in `shipped` with no row in `rows`. The sweep's actual predicate. */
+function uncoveredMechanisms(
+ shipped: readonly string[],
+ rows: readonly { readonly mechanism: string }[],
+): string[] {
+ const covered = new Set(rows.map((r) => r.mechanism));
+ return shipped.filter((m) => !covered.has(m));
+}
+
+/** Rows naming a mechanism that is no longer shipped. */
+function staleRows(
+ shipped: readonly string[],
+ rows: readonly { readonly mechanism: string }[],
+): string[] {
+ const live = new Set(shipped);
+ return rows.map((r) => r.mechanism).filter((m) => !live.has(m));
+}
+
+interface ResolvedCompositionTest {
+ /** A `test(...)`/`it(...)` declaration whose title contains the substring. */
+ declared: boolean;
+ /** That declaration carries a `.skip` / `.todo` / `.fails` modifier. */
+ disabled: boolean;
+ /** `expect(` calls between the declaration and the next one — a live body. */
+ assertions: number;
+}
+
+/** Drop comment lines so a title quoted in a docblock never satisfies a row. */
+function stripCommentLines(text: string): string {
+ return text
+ .split('\n')
+ .filter((line) => {
+ const t = line.trimStart();
+ return !(t.startsWith('*') || t.startsWith('//') || t.startsWith('/*') || t.startsWith('*/'));
+ })
+ .join('\n');
+}
+
+/**
+ * Resolve a row's title to a real, ENABLED, non-empty test declaration.
+ *
+ * A raw `source.includes(title)` is satisfied by the title appearing anywhere —
+ * in a docblock, in a `test.skip(...)`, or above a body that has been gutted —
+ * so a registered composition test could be switched off and the index would
+ * still certify it.
+ */
+function resolveCompositionTest(pkgRelPath: string, title: string): ResolvedCompositionTest {
+ const src = stripCommentLines(readFileSync(resolve(PACKAGES, pkgRelPath), 'utf-8'));
+ const decl = /(?<![.\w])(?:test|it)((?:\.\w+)*)\s*\(\s*(['"`])([\s\S]*?)\2/g;
+ const declarations: Array<{ modifiers: string; title: string; end: number }> = [];
+ for (const m of src.matchAll(decl)) {
+ declarations.push({
+ modifiers: m[1] ?? '',
+ title: (m[3] ?? '').replace(/\s+/g, ' ').trim(),
+ end: (m.index ?? 0) + m[0].length,
+ });
+ }
+ const needle = title.replace(/\s+/g, ' ').trim();
+ const hitIndex = declarations.findIndex((d) => d.title.includes(needle));
+ if (hitIndex === -1) return { declared: false, disabled: false, assertions: 0 };
+ const hit = declarations[hitIndex] as (typeof declarations)[number];
+ const next = declarations[hitIndex + 1];
+ const body = src.slice(hit.end, next ? next.end : src.length);
+ return {
+ declared: true,
+ disabled: /\.(skip|todo|fails|skipIf)\b/.test(hit.modifiers),
+ assertions: (body.match(/\bexpect\s*\(/g) ?? []).length,
+ };
+}
+
+describe('composition sweep index (H13)', () => {
+ test('every shipped mechanism has a composition row (fail-closed) and no rows are stale', () => {
+ const shipped = [...SHIPPED_MECHANISMS].sort();
+ expect(uncoveredMechanisms(shipped, COMPOSITION_ROWS)).toEqual([]);
+ expect(staleRows(shipped, COMPOSITION_ROWS)).toEqual([]);
+ });
+
+ /**
+ * The external anchor. Both literals above are hand-maintained IN THIS FILE,
+ * so on their own they cannot notice a mechanism omitted from both. The
+ * production config schema enumerates every kill-switch independently.
+ *
+ */
+ test('every kill-switch in the production config schema maps to a covered mechanism', () => {
+ const paths = shippedKillSwitchPaths();
+ // Guard-the-guard: the schema read must actually find the switches.
+ expect(paths.length).toBeGreaterThanOrEqual(7);
+
+ const unregistered = paths.filter((p) => KILL_SWITCH_MECHANISM[p] === undefined);
+ expect(unregistered).toEqual([]);
+
+ const mechanisms = paths.map((p) => KILL_SWITCH_MECHANISM[p] as string);
+ // Each gated mechanism is a shipped mechanism...
+ expect(mechanisms.filter((m) => !SHIPPED_MECHANISMS.includes(m as never))).toEqual([]);
+ // ...and carries a composition row.
+ expect(uncoveredMechanisms(mechanisms, COMPOSITION_ROWS)).toEqual([]);
+
+ // No mapping survives its switch being removed from the schema.
+ const live = new Set(paths);
+ expect(Object.keys(KILL_SWITCH_MECHANISM).filter((p) => !live.has(p))).toEqual([]);
+ });
+
+ test.each(COMPOSITION_ROWS)('$mechanism ($rung) has a registered composition test', (row) => {
+ const resolved = resolveCompositionTest(row.file, row.title);
+ // The title resolves to a real test declaration, that declaration is not
+ // switched off, and its body still asserts something. A substring match
+ // alone certifies a skipped or gutted test just as happily.
+ expect(resolved.declared).toBe(true);
+ expect(resolved.disabled).toBe(false);
+ expect(resolved.assertions).toBeGreaterThan(0);
+ // Every non-public rung must justify why a pure public-surface row is not
+ // reached — the honest carry, never a silent gap.
+ if (row.rung !== 'booted-server') {
+ expect(row.residual && row.residual.length > 0).toBe(true);
+ }
+ });
+
+ test('the typing-during-freeze-persists row is present', () => {
+ const freeze = COMPOSITION_ROWS.find((r) => r.mechanism === 'fixed-point-backstop');
+ expect(freeze).toBeDefined();
+ if (!freeze) return;
+ expect(freeze.title).toContain('typing during a freeze persists');
+ const resolved = resolveCompositionTest(freeze.file, freeze.title);
+ expect(resolved.declared).toBe(true);
+ expect(resolved.disabled).toBe(false);
+ expect(resolved.assertions).toBeGreaterThan(0);
+ });
+
+ test('the sweep bites: an uncovered mechanism, a stale row, a bogus title, and a disabled test', () => {
+ // Drive the SAME predicates the real cases call, not inline restatements of
+ // them — a defect in the real filter has to be visible to its own check.
+ const withNewMechanism = [...SHIPPED_MECHANISMS, '__planted_uncovered_mechanism__'];
+ expect(uncoveredMechanisms(withNewMechanism, COMPOSITION_ROWS)).toEqual([
+ '__planted_uncovered_mechanism__',
+ ]);
+ expect(
+ staleRows(SHIPPED_MECHANISMS, [...COMPOSITION_ROWS, { mechanism: '__planted_stale_row__' }]),
+ ).toEqual(['__planted_stale_row__']);
+
+ const firstRow = COMPOSITION_ROWS[0] as (typeof COMPOSITION_ROWS)[number];
+ expect(
+ resolveCompositionTest(firstRow.file, '__this composition title does not exist__').declared,
+ ).toBe(false);
+
+ // And the resolver's own discriminators, against this file's fixtures below.
+ const self = 'app/tests/integration/composition-sweep-index.test.ts';
+ expect(resolveCompositionTest(self, 'planted disabled composition fixture')).toMatchObject({
+ declared: true,
+ disabled: true,
+ });
+ expect(
+ resolveCompositionTest(self, 'planted assertion-free composition fixture'),
+ ).toMatchObject({ declared: true, disabled: false, assertions: 0 });
+ });
+
+ // Fixtures for the resolver's discriminators above. A registered composition
+ // test that is switched off, or whose body has been gutted, must not read as
+ // covered — these two prove the resolver can tell.
+ /**
+ * above reads back statically, to prove the resolver reports a `.skip`ped
+ * composition test as disabled rather than covered. Running it would defeat
+ * its only purpose.
+ */
+ test.skip('planted disabled composition fixture', () => {
+ expect(true).toBe(true);
+ });
+ /**
+ * Deliberately assertion-free — the sweep above reads it back statically to
+ * prove a gutted body does not read as covered.
+ *
+ */
+ test('planted assertion-free composition fixture', () => {
+ return;
+ });
+});
diff --git a/packages/app/tests/integration/derive-timing-guard-full-flow.test.ts b/packages/app/tests/integration/derive-timing-guard-full-flow.test.ts
new file mode 100644
index 000000000..db7a225ec
--- /dev/null
+++ b/packages/app/tests/integration/derive-timing-guard-full-flow.test.ts
@@ -0,0 +1,196 @@
+/**
+ * Full-flow coverage for the derive-timing defer guard: the guard is wired
+ * through the REAL boot path — `.ok/config.yml` (`bridge.deferGuard.enabled`,
+ * default ON) → `createServer` → the observer extension → `setupServerObservers`
+ * — and preserves an un-propagated WYSIWYG keystroke on a booted server.
+ *
+ * The un-propagated window is staged on the booted server's own Y.Doc: a
+ * freshness-suppressed Observer A settlement leaves the fragment holding a
+ * component's advanced children while Y.Text lags a generation, and a
+ * source-editor write over the live WS then drives an Observer B re-derive that
+ * would stomp it without the guard. The server runs in-process, so faking `Date`
+ * drives its freshness-quiescence window deterministically; only `Date` is
+ * faked, so the real WS + async I/O proceed normally.
+ *
+ * The byte-corruption itself only manifests under real cross-peer concurrency
+ * (the browser canaries own that rung); this pins that the guard is LIVE end to
+ * end and survives the drain-shaped re-derive on the real server.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
+import { getSchema, type JSONContent } from '@tiptap/core';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import type * as Y from 'yjs';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { createTestServer, getServerState, mdManager, type TestServer } from './test-harness.ts';
+
+const schema = getSchema(sharedExtensions);
+// The server serializes freshness-ON (its md-manager singleton), so the guard
+// sees a component's advanced children. The harness `mdManager` is freshness-OFF
+// (reads the stale sourceRaw), so verify the fragment's live children with a
+// matching freshness-ON serialize.
+const freshMdManager = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+});
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+const STALE_LINE = 'Step one bod';
+const PENDING_LINE = 'Step one body.';
+
+function mutateFirstText(node: JSONContent, from: string, to: string): boolean {
+ if (typeof node.text === 'string' && node.text === from) {
+ node.text = to;
+ return true;
+ }
+ for (const child of node.content ?? []) {
+ if (mutateFirstText(child, from, to)) return true;
+ }
+ return false;
+}
+
+/** Freshness-ON serialize — sees a component's live children, not stale sourceRaw. */
+function serializeFragment(fragment: Y.XmlFragment): string {
+ return freshMdManager.serialize(yXmlFragmentToProseMirrorRootNode(fragment, schema).toJSON());
+}
+
+/** A fresh contentDir whose `.ok/config.yml` switches the defer guard off. */
+function guardDisabledContentDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-defer-guard-off-'));
+ mkdirSync(join(dir, '.ok'), { recursive: true });
+ writeFileSync(join(dir, '.ok', 'config.yml'), 'bridge:\n deferGuard:\n enabled: false\n');
+ writeFileSync(join(dir, 'test-doc.md'), '', 'utf-8');
+ return dir;
+}
+
+describe('derive-timing guard — full-flow on a booted server', () => {
+ let server: TestServer;
+ let ownedContentDir: string | undefined;
+
+ afterEach(async () => {
+ vi.useRealTimers();
+ await server.cleanup();
+ if (ownedContentDir) rmSync(ownedContentDir, { recursive: true, force: true });
+ ownedContentDir = undefined;
+ });
+
+ test(
+ 'the config-wired guard preserves an un-propagated keystroke on the real server',
+ async () => {
+ server = await createTestServer();
+ const docName = `defer-full-${crypto.randomUUID().slice(0, 8)}`;
+ // Create + load the doc at GEN1 through the real agent-write spine (paired),
+ // so the observers attach with the config-resolved guard + loss ring.
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ markdown: GEN1, position: 'replace', docName }),
+ });
+ expect(res.status).toBe(200);
+
+ const doc = server.instance.hocuspocus.documents.get(docName) as unknown as Y.Doc;
+ expect(doc).toBeTruthy();
+ const state = getServerState(server, docName);
+ expect(state?.ytext.toString()).toContain(STALE_LINE);
+ const ytext = state?.ytext as Y.Text;
+ const fragment = state?.fragment as Y.XmlFragment;
+
+ // Drive the server's freshness clock deterministically from here.
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(Date.now() + 10_000); // quiescent baseline
+
+ // Poke Y.Text to reset the freshness-quiescence clock.
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nTrailing.\n');
+ }, 'external-peer');
+
+ // Echo drain INSIDE the window: advance the component children to the
+ // pending line while sourceRaw stays stale → Observer A serializes the
+ // stale bytes and settles, leaving the fragment ahead of Y.Text.
+ const echo = mdManager.parse(ytext.toString()) as JSONContent;
+ expect(mutateFirstText(echo, STALE_LINE, PENDING_LINE)).toBe(true);
+ doc.transact(() => {
+ updateYFragment(doc, fragment, schema.nodeFromJSON(echo), {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ }, 'wysiwyg-echo');
+ expect(serializeFragment(fragment)).toContain(PENDING_LINE);
+ expect(ytext.toString()).not.toContain(PENDING_LINE);
+
+ // Source-editor write over the live doc: drives an Observer B re-derive that
+ // would rebuild the fragment from stale Y.Text and stomp the keystroke.
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nAnother source line.\n');
+ }, 'external-peer');
+
+ // The guard deferred: the keystroke is still in the server fragment.
+ expect(serializeFragment(fragment)).toContain(PENDING_LINE);
+ },
+ HARNESS_BOOT_TIMEOUT_MS,
+ );
+
+ /**
+ * The OFF arm. Without it the ON arm alone is satisfied by a guard that is
+ * hardcoded on: the whole point of this tier is the
+ * `.ok/config.yml` → `createServer` → observers wiring, and only a run that
+ * flips the config can show that read is live. The rig-tier kill-switch pair
+ * exercises a different path.
+ *
+ */
+ test(
+ 'with the guard config-disabled the same staging stomps the keystroke',
+ async () => {
+ ownedContentDir = guardDisabledContentDir();
+ server = await createTestServer({ contentDir: ownedContentDir, keepContentDir: true });
+ ownedContentDir = server.contentDir;
+ const docName = `defer-off-${crypto.randomUUID().slice(0, 8)}`;
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ markdown: GEN1, position: 'replace', docName }),
+ });
+ expect(res.status).toBe(200);
+
+ const doc = server.instance.hocuspocus.documents.get(docName) as unknown as Y.Doc;
+ const state = getServerState(server, docName);
+ const ytext = state?.ytext as Y.Text;
+ const fragment = state?.fragment as Y.XmlFragment;
+
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(Date.now() + 10_000);
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nTrailing.\n');
+ }, 'external-peer');
+ const echo = mdManager.parse(ytext.toString()) as JSONContent;
+ expect(mutateFirstText(echo, STALE_LINE, PENDING_LINE)).toBe(true);
+ doc.transact(() => {
+ updateYFragment(doc, fragment, schema.nodeFromJSON(echo), {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ }, 'wysiwyg-echo');
+ // Precondition: the staging really did leave the fragment ahead of Y.Text,
+ // so the assertion below is about the guard and not about a no-op staging.
+ expect(serializeFragment(fragment)).toContain(PENDING_LINE);
+ expect(ytext.toString()).not.toContain(PENDING_LINE);
+
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nAnother source line.\n');
+ }, 'external-peer');
+
+ // No guard: the re-derive rebuilt the fragment from Y.Text and the
+ // un-propagated keystroke is gone. The document itself is intact — this is
+ // the specific loss the ON arm prevents, not a wiped doc.
+ const afterOff = serializeFragment(fragment);
+ expect(afterOff).not.toContain(PENDING_LINE);
+ expect(afterOff).toContain(STALE_LINE);
+ expect(afterOff).toContain('Another source line.');
+ },
+ HARNESS_BOOT_TIMEOUT_MS,
+ );
+});
diff --git a/packages/app/tests/integration/editor-lifecycle-flush.test.ts b/packages/app/tests/integration/editor-lifecycle-flush.test.ts
new file mode 100644
index 000000000..e61f94ef8
--- /dev/null
+++ b/packages/app/tests/integration/editor-lifecycle-flush.test.ts
@@ -0,0 +1,106 @@
+/**
+ * Client<->server contract for the browser-lifecycle flush/resync.
+ *
+ * The pool's per-provider gating (which docs flush, kill-switch OFF/ON) is
+ * pinned deterministically at the unit tier (provider-pool-flush-on-hide). This
+ * suite proves the part that only a real client<->server round-trip can: the
+ * flush's `forceSync` actually lands a pending delta on the SERVER (asserted
+ * via getServerState — an IDB-only landing does not satisfy it), and a
+ * backgrounded-then-visible client reconverges.
+ *
+ * The outbound-drop models a lost/throttled incremental update; it does NOT
+ * reproduce real browser background-throttling (Chrome intensive throttling /
+ * Safari App Nap), which is only observable at a browser/long-run rung and is
+ * carried as an open residual, not claimed here.
+ */
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import {
+ agentWriteMd,
+ createTestClient,
+ createTestServer,
+ getServerState,
+ HARNESS_BOOT_TIMEOUT_MS,
+ pollUntil,
+ type TestServer,
+} from './test-harness';
+
+describe('editor lifecycle flush/resync (client<->server)', () => {
+ let server: TestServer;
+ beforeAll(async () => {
+ server = await createTestServer();
+ }, HARNESS_BOOT_TIMEOUT_MS);
+ afterAll(async () => {
+ await server.cleanup();
+ });
+
+ it('force-sync flush lands a pending delta on the SERVER (IDB-only would not)', async () => {
+ const client = await createTestClient(server.port, undefined, {
+ syncControl: true,
+ skipInvariantWatcher: true,
+ });
+ try {
+ const MARKER = 'FLUSHONHIDEMARKER7c1a';
+
+ // Drop outbound so the incremental update is lost — the provider believes
+ // it sent, unsyncedChanges stays > 0, and the server never receives it.
+ client.setDropOutbound(true);
+ client.doc.transact(() => {
+ client.ytext.insert(0, MARKER);
+ });
+ expect(client.provider.unsyncedChanges).toBeGreaterThan(0);
+
+ const beforeFlush = getServerState(server, client.docName);
+ expect(beforeFlush?.ytext.toString().includes(MARKER) ?? false).toBe(false);
+
+ // The flush: stop dropping and forceSync — the exact per-provider op
+ // pool.flushOnHide() performs. Delivery is async; poll the SERVER state.
+ client.setDropOutbound(false);
+ client.provider.forceSync();
+
+ // pollUntil throws on timeout, so reaching the assertion means it landed.
+ await pollUntil(
+ () => getServerState(server, client.docName)?.ytext.toString().includes(MARKER) ?? false,
+ 5_000,
+ );
+ expect(getServerState(server, client.docName)?.ytext.toString()).toContain(MARKER);
+ } finally {
+ await client.cleanup();
+ }
+ });
+
+ it('resync-on-visible: a client that missed a server edit reconverges', async () => {
+ const client = await createTestClient(server.port, undefined, {
+ syncControl: true,
+ skipInvariantWatcher: true,
+ });
+ try {
+ const SERVER_EDIT = 'SERVEREDITWHILEHIDDEN91b2';
+
+ // Model a hidden tab missing inbound updates: pause inbound, then a
+ // separate writer changes the server doc.
+ client.pauseSync();
+ await agentWriteMd(server.port, SERVER_EDIT, {
+ docName: client.docName,
+ position: 'replace',
+ });
+
+ // The client has not seen the server edit yet.
+ expect(client.ytext.toString().includes(SERVER_EDIT)).toBe(false);
+
+ // Return to foreground: inbound resumes (throttle lifts) and the resync
+ // forceSync pulls the client up to date.
+ client.resumeSync();
+ client.provider.forceSync();
+
+ // pollUntil throws on timeout, so reaching the assertion means it converged.
+ await pollUntil(() => client.ytext.toString().includes(SERVER_EDIT), 5_000);
+ expect(client.ytext.toString()).toContain(SERVER_EDIT);
+
+ // Client doc equals server doc.
+ const serverState = getServerState(server, client.docName);
+ expect(client.ytext.toString()).toBe(serverState?.ytext.toString());
+ } finally {
+ await client.cleanup();
+ }
+ });
+});
diff --git a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
new file mode 100644
index 000000000..0db7749b4
--- /dev/null
+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
@@ -0,0 +1,222 @@
+/**
+ * CONTRACT — byte-sacred typing inside indented MDX-JSX regions.
+ *
+ * A source-mode keystroke, or a WYSIWYG-side body edit, inside an INDENTED
+ * MDX-JSX region (a <Step> nested in <Steps> with leading indentation on the
+ * tags) must NOT trigger a normalizing (de-indent) write-back into Y.Text.
+ * Server Observer A is the only surface allowed to canonicalize, and it must
+ * leave the raw indented bytes intact (per-write-path fidelity: byte-writer
+ * paths land verbatim). A de-indent / normalization write-back is a fidelity
+ * regression.
+ *
+ * Shape B (the whole <Steps> container indented) is the sentinel: it rests
+ * BEYOND normalizeBridge tolerance, so its raw bytes and their canonical
+ * serialization are not normalize-equal — the highest write-back-risk shape.
+ * Byte-sacred must still hold for it.
+ *
+ */
+
+import { setTimeout as wait } from 'node:timers/promises';
+import { normalizeBridge } from '@inkeep/open-knowledge-core';
+import { updateYFragment } from '@tiptap/y-tiptap';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentWriteMd,
+ awaitDocQuiescence,
+ createTestClient,
+ createTestServer,
+ getServerState,
+ mdManager,
+ schema,
+ type TestClient,
+ type TestServer,
+} from './test-harness';
+
+/** A genuine WYSIWYG-side fragment commit (null origin => server Observer A
+ * sees a real WYSIWYG mutation, xmlDirty=true). */
+function applyWysiwygEdit(client: TestClient, markdownAfterEdit: string): void {
+ const pmNode = schema.nodeFromJSON(mdManager.parse(markdownAfterEdit));
+ client.doc.transact(() => {
+ updateYFragment(client.doc, client.fragment, pmNode, {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ });
+}
+
+// Indented-JSX shapes (leading indentation ON the tags).
+
+// Shape A: flush-left <Steps>, 2-space-indented <Step>/</Step> tags + bodies.
+const SHAPE_A_INDENTED_STEP = [
+ '<Steps>',
+ '',
+ ' <Step>',
+ '',
+ ' Content one.',
+ '',
+ ' </Step>',
+ '',
+ ' <Step>',
+ '',
+ ' Content two.',
+ '',
+ ' </Step>',
+ '',
+ '</Steps>',
+ '',
+].join('\n');
+
+// Shape B: the ENTIRE container indented 2 spaces (every tag + body).
+const SHAPE_B_INDENTED_CONTAINER = [
+ ' <Steps>',
+ '',
+ ' <Step>',
+ '',
+ ' Content one.',
+ '',
+ ' </Step>',
+ '',
+ ' </Steps>',
+ '',
+].join('\n');
+
+// Shape C: 3-space-indented <Step> tags (an odd indent below CommonMark's
+// 4-space indented-code boundary).
+const SHAPE_C_THREE_SPACE = [
+ '<Steps>',
+ '',
+ ' <Step>',
+ '',
+ ' Content one.',
+ '',
+ ' </Step>',
+ '',
+ '</Steps>',
+ '',
+].join('\n');
+
+interface Shape {
+ name: string;
+ seed: string;
+ anchor: string;
+ /** Measured serialize/tolerance characterization the byte-sacred guarantee
+ * rests on. Shape B is the sentinel: NOT a serialize fixed point AND beyond
+ * normalizeBridge tolerance, yet byte-sacred still holds. */
+ isFixedPoint: boolean;
+ withinTolerance: boolean;
+}
+
+const SHAPES: Shape[] = [
+ {
+ name: 'A: indented <Step> tags (2-space)',
+ seed: SHAPE_A_INDENTED_STEP,
+ anchor: 'Content one',
+ isFixedPoint: true,
+ withinTolerance: true,
+ },
+ {
+ name: 'B: fully-indented <Steps> container (2-space)',
+ seed: SHAPE_B_INDENTED_CONTAINER,
+ anchor: 'Content one',
+ isFixedPoint: false,
+ withinTolerance: false,
+ },
+ {
+ name: 'C: indented <Step> tags (3-space)',
+ seed: SHAPE_C_THREE_SPACE,
+ anchor: 'Content one',
+ isFixedPoint: true,
+ withinTolerance: true,
+ },
+];
+
+describe('indented-JSX serialize + normalizeBridge tolerance characterization', () => {
+ for (const shape of SHAPES) {
+ test(`${shape.name}: serialize fixed-point + normalizeBridge tolerance are stable`, () => {
+ const canonical = mdManager.serialize(mdManager.parse(shape.seed));
+ const isFixedPoint = canonical === shape.seed;
+ const withinTolerance = normalizeBridge(shape.seed) === normalizeBridge(canonical);
+ expect(isFixedPoint).toBe(shape.isFixedPoint);
+ expect(withinTolerance).toBe(shape.withinTolerance);
+ });
+ }
+});
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+describe('byte-sacred source-mode typing inside indented JSX', () => {
+ for (const { name, seed, anchor } of SHAPES) {
+ test(`${name}: a source-mode keystroke stays byte-verbatim (no Observer-A normalization write-back)`, async () => {
+ const docName = `e2-${name.replace(/[^a-z0-9]/gi, '-')}-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ const ytext = client.doc.getText('source');
+ await awaitDocQuiescence(client.doc);
+ const landed = ytext.toString();
+
+ // Simulate a source-mode keystroke: a client-origin Y.Text insert (the
+ // default transaction origin is NOT a paired write origin — it is the
+ // CM6/source-typing channel). Insert INSIDE the indented region.
+ const at = landed.indexOf(anchor) + anchor.length;
+ expect(at).toBeGreaterThan(anchor.length); // anchor exists in landed bytes
+ client.doc.transact(() => ytext.insert(at, 'X'));
+ const expectedAfterTyping = ytext.toString(); // exactly the typed bytes
+ await awaitDocQuiescence(client.doc);
+
+ const serverBytes = getServerState(server, docName)?.ytext.toString() ?? '';
+ // The server's raw Y.Text must equal EXACTLY the typed bytes. Any
+ // de-indent / normalization write-back reddens here.
+ expect(serverBytes).toBe(expectedAfterTyping);
+ } finally {
+ await client.cleanup();
+ }
+ });
+ }
+});
+
+// The indented-JSX write-back risk names the hidden-but-mounted WYSIWYG TipTap
+// binding as the single-client trigger. Cover that channel (a fragment commit,
+// xmlDirty) on the two shapes whose indentation survives landing — including
+// Shape B, which rests beyond normalizeBridge tolerance (the highest risk).
+const WYSIWYG_SHAPES = SHAPES.filter((s) => s.name.startsWith('A') || s.name.startsWith('B'));
+
+describe('byte-sacred WYSIWYG-commit channel on indented JSX', () => {
+ for (const { name, seed } of WYSIWYG_SHAPES) {
+ test(`${name}: a WYSIWYG fragment commit does not re-indent / normalize the container in Y.Text`, async () => {
+ const docName = `e2w-${name.replace(/[^a-z0-9]/gi, '-')}-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ const ytext = client.doc.getText('source');
+ await awaitDocQuiescence(client.doc);
+ const landed = ytext.toString();
+ expect(landed).toBe(seed); // indented seed landed verbatim
+
+ // Genuine WYSIWYG-side change (fires Observer A with xmlDirty): edit the
+ // body text of the first Step.
+ applyWysiwygEdit(client, landed.replace('Content one.', 'Content one, edited.'));
+ await awaitDocQuiescence(client.doc);
+
+ const serverBytes = getServerState(server, docName)?.ytext.toString() ?? '';
+ expect(serverBytes).toContain('Content one, edited.'); // non-vacuous: edit landed
+ // The tags must NOT gain/lose indentation vs the pre-edit landed bytes
+ // (only the edited body text changes). A normalization write-back reddens.
+ expect(serverBytes).toBe(landed.replace('Content one.', 'Content one, edited.'));
+ } finally {
+ await client.cleanup();
+ }
+ });
+ }
+});
diff --git a/packages/app/tests/integration/kill-switch-sweep.test.ts b/packages/app/tests/integration/kill-switch-sweep.test.ts
new file mode 100644
index 000000000..ed46bc49d
--- /dev/null
+++ b/packages/app/tests/integration/kill-switch-sweep.test.ts
@@ -0,0 +1,187 @@
+/**
+ * Kill-switch sweep (H12) — the fail-closed index over every loss-hardening
+ * mechanism's config kill-switch.
+ *
+ * Each shipped mechanism has a project-scope `enabled` leaf in `ConfigSchema`
+ * (default ON — the mechanism IS the loss-prevention guarantee) plus a behavioral
+ * OFF test that observes inertness and an ON planted-positive twin. This sweep
+ * enumerates the kill-switch leaves straight off the parsed schema and FAILS if
+ * any leaf lacks a registered mechanism row, or any row's OFF/ON behavioral test
+ * is missing — so a new kill-switch cannot ship without its behavioral pair.
+ *
+ * Kill-switch removal criteria are STRUCTURAL, never calendar-based: a
+ * kill-switch is removed only once its mechanism's contract suites are green and
+ * no trips appear in the dogfood corpus (loss-ring bundles). No mechanism is
+ * retired on a schedule; the escape hatch stays until the evidence says the
+ * mechanism no longer needs one.
+ *
+ * The field-registry coverage (registration + scope + default-ON round-trip) is
+ * pinned separately in `core`'s `field-registry.test.ts` (project-strict leaf
+ * equality) and `schema-jsonschema.test.ts` (per-leaf default-ON parse); this
+ * sweep pins the mechanism↔behavioral-test wiring the registry cannot see.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ConfigSchema } from '@inkeep/open-knowledge-core';
+import { describe, expect, test } from 'vitest';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// .../packages/app/tests/integration → .../packages
+const PACKAGES = resolve(HERE, '../../..');
+
+interface MechanismRow {
+ /** Dotted config path of the kill-switch leaf (relative to the config root). */
+ readonly leaf: string;
+ /** Package-relative path of the behavioral OFF test file. */
+ readonly offFile: string;
+ /** A distinctive substring of the OFF test's title. */
+ readonly offTitle: string;
+ /** Package-relative path of the ON planted-positive test file. */
+ readonly onFile: string;
+ /** A distinctive substring of the ON test's title. */
+ readonly onTitle: string;
+}
+
+/**
+ * The canonical mechanism → kill-switch → behavioral-pair registry. A new
+ * kill-switch leaf that is not listed here fails the enumeration sweep below.
+ */
+const KILL_SWITCHES: readonly MechanismRow[] = [
+ {
+ leaf: 'bridge.deferGuard.enabled',
+ offFile: 'server/src/derive-timing-guard.test.ts',
+ offTitle: 'with the guard OFF the same drain stomps the keystroke',
+ onFile: 'server/src/derive-timing-guard.test.ts',
+ onTitle: 'an un-propagated WYSIWYG keystroke survives a drain-shaped re-derive',
+ },
+ {
+ leaf: 'bridge.lossDetector.enabled',
+ offFile: 'server/src/bridge-loss-detector.test.ts',
+ offTitle: 'does not trip when the loss-detector kill-switch is off',
+ onFile: 'server/src/bridge-loss-detector.test.ts',
+ onTitle: 'checkpoints + emits a detector-trip when an apply arm drops content',
+ },
+ {
+ leaf: 'bridge.fixedPoint.enabled',
+ offFile: 'server/src/derive-fixed-point-backstop.test.ts',
+ offTitle: 'kill-switch OFF: the loop churns unbounded with no trip; default-ON pinned',
+ onFile: 'server/src/derive-fixed-point-backstop.test.ts',
+ onTitle:
+ 'a normalize-equal-but-byte-different loop is not treated as converged and trips the backstop loudly',
+ },
+ {
+ leaf: 'bridge.preDrain.enabled',
+ offFile: 'server/src/derive-pre-drain.test.ts',
+ offTitle: 'kill-switch OFF: the cross-block keystroke is NOT flushed (left for the floor)',
+ onFile: 'server/src/derive-pre-drain.test.ts',
+ onTitle:
+ 'CROSS-BLOCK undo: the pending keystroke survives in Y.Text and the re-derived fragment',
+ },
+ {
+ leaf: 'bridge.flushOnHide.enabled',
+ offFile: 'app/src/editor/provider-pool-flush-on-hide.test.ts',
+ offTitle: 'is inert when the kill-switch is off (no force-sync, no IDB commit)',
+ onFile: 'app/src/editor/provider-pool-flush-on-hide.test.ts',
+ onTitle: 'force-syncs the server AND commits IDB for a doc with a pending delta',
+ },
+ {
+ leaf: 'bridge.backgroundThrottle.enabled',
+ offFile: 'desktop/src/main/background-throttle.test.ts',
+ offTitle: 'is inert when the kill-switch is OFF: applies the OS default despite pending work',
+ onFile: 'desktop/src/main/background-throttle.test.ts',
+ onTitle: 'keeps timers alive (setBackgroundThrottling false) when work is pending and enabled',
+ },
+ {
+ leaf: 'lossCapture.enabled',
+ offFile: 'app/tests/integration/loss-capture-killswitch.test.ts',
+ offTitle:
+ 'OFF (lossCapture.enabled: false): the guard still defers but the ring records nothing',
+ onFile: 'app/tests/integration/loss-capture-killswitch.test.ts',
+ onTitle: 'ON (default): a defer lands a content-free guard-defer event in the ring',
+ },
+];
+
+/** Resolve a dotted path against a parsed object; returns undefined on a miss. */
+function readPath(obj: unknown, dotted: string): unknown {
+ return dotted.split('.').reduce<unknown>((cur, key) => {
+ if (cur !== null && typeof cur === 'object' && key in (cur as Record<string, unknown>)) {
+ return (cur as Record<string, unknown>)[key];
+ }
+ return undefined;
+ }, obj);
+}
+
+/**
+ * Enumerate the kill-switch `enabled` leaves that actually exist in the parsed
+ * default config: every `bridge.<mechanism>.enabled` plus `lossCapture.enabled`.
+ * (The `lossCapture.maxBytes` tuning leaf is not a kill-switch.)
+ */
+function enumerateKillSwitchLeaves(): string[] {
+ const parsed = ConfigSchema.parse({}) as Record<string, unknown>;
+ const leaves: string[] = [];
+ const bridge = parsed.bridge as Record<string, unknown> | undefined;
+ if (bridge) {
+ for (const key of Object.keys(bridge)) {
+ const sub = bridge[key] as Record<string, unknown> | undefined;
+ if (sub && typeof sub.enabled === 'boolean') leaves.push(`bridge.${key}.enabled`);
+ }
+ }
+ const lossCapture = parsed.lossCapture as Record<string, unknown> | undefined;
+ if (lossCapture && typeof lossCapture.enabled === 'boolean') leaves.push('lossCapture.enabled');
+ return leaves.sort();
+}
+
+function fileContainsTitle(pkgRelPath: string, title: string): boolean {
+ const abs = resolve(PACKAGES, pkgRelPath);
+ const src = readFileSync(abs, 'utf-8');
+ return src.includes(title);
+}
+
+describe('kill-switch sweep (H12)', () => {
+ test('every kill-switch leaf in the schema is a registered mechanism (fail-closed) and no rows are stale', () => {
+ const declared = enumerateKillSwitchLeaves();
+ const registered = KILL_SWITCHES.map((m) => m.leaf).sort();
+
+ // Empty-scan guard: the schema must expose the full mechanism set.
+ expect(declared.length).toBeGreaterThanOrEqual(7);
+
+ // A schema kill-switch with no registered mechanism row → fail-closed.
+ const unregistered = declared.filter((leaf) => !registered.includes(leaf));
+ expect(unregistered).toEqual([]);
+
+ // A registered row whose leaf no longer exists in the schema → stale.
+ const stale = registered.filter((leaf) => !declared.includes(leaf));
+ expect(stale).toEqual([]);
+ });
+
+ test.each(KILL_SWITCHES)('$leaf is default-ON and carries an OFF + ON behavioral pair', (m) => {
+ // Default-ON pinned behaviorally: the unconfigured schema resolves the
+ // mechanism enabled.
+ const parsed = ConfigSchema.parse({});
+ expect(readPath(parsed, m.leaf)).toBe(true);
+
+ // Behavioral OFF test + ON planted-positive twin are registered.
+ expect(fileContainsTitle(m.offFile, m.offTitle)).toBe(true);
+ expect(fileContainsTitle(m.onFile, m.onTitle)).toBe(true);
+ });
+
+ test('the sweep bites: a planted uncovered leaf and a bogus title are both caught', () => {
+ // The enumerator would flag a new leaf absent from the registry.
+ const declared = enumerateKillSwitchLeaves();
+ const registered = KILL_SWITCHES.map((m) => m.leaf);
+ const withPlant = [...declared, 'bridge.__planted_uncovered__.enabled'];
+ expect(withPlant.filter((leaf) => !registered.includes(leaf))).toContain(
+ 'bridge.__planted_uncovered__.enabled',
+ );
+
+ // The title-existence check would fail for a title that is not in the file.
+ expect(
+ fileContainsTitle(
+ KILL_SWITCHES[0].offFile,
+ '__this title does not exist in the OFF test file__',
+ ),
+ ).toBe(false);
+ });
+});
diff --git a/packages/app/tests/integration/loss-capture-killswitch.test.ts b/packages/app/tests/integration/loss-capture-killswitch.test.ts
new file mode 100644
index 000000000..2f2433cf2
--- /dev/null
+++ b/packages/app/tests/integration/loss-capture-killswitch.test.ts
@@ -0,0 +1,229 @@
+/**
+ * Behavioral kill-switch coverage for the loss-capture ring through the REAL
+ * boot path: `.ok/config.yml` (`lossCapture.enabled`) → `createServer` builds
+ * (or, when disabled, does NOT build) the ring → producers write (or write to a
+ * nothing).
+ *
+ * The loss producer is the derive-timing defer guard (it records a `guard-defer`
+ * event on every defer), staged on the booted server's own Y.Doc exactly like
+ * the derive-timing full-flow rig: a freshness-suppressed Observer A settlement
+ * leaves the fragment ahead of Y.Text, then a source-editor write drives an
+ * Observer B re-derive the guard defers. Only `Date` is faked so the real WS +
+ * async I/O proceed.
+ *
+ * ON: the default config builds the ring, so the defer lands a content-free
+ * `guard-defer` event under `.ok/local/loss-capture/`. OFF: with
+ * `lossCapture.enabled: false` the ring is never built — the guard still defers
+ * (its own kill-switch is untouched, so the keystroke still survives) but records
+ * nothing. The contrast isolates the ring kill-switch from the producer.
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
+import { getSchema, type JSONContent } from '@tiptap/core';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import type * as Y from 'yjs';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { createTestServer, getServerState, mdManager, type TestServer } from './test-harness.ts';
+
+const schema = getSchema(sharedExtensions);
+// The server serializes freshness-ON (its md-manager singleton); the harness
+// `mdManager` is freshness-OFF, so verify the fragment with a matching engine.
+const freshMdManager = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+});
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+const STALE_LINE = 'Step one bod';
+const PENDING_LINE = 'Step one body.';
+const GUARD_DEFER_EVENT = 'guard-defer';
+
+function mutateFirstText(node: JSONContent, from: string, to: string): boolean {
+ if (typeof node.text === 'string' && node.text === from) {
+ node.text = to;
+ return true;
+ }
+ for (const child of node.content ?? []) {
+ if (mutateFirstText(child, from, to)) return true;
+ }
+ return false;
+}
+
+/** Freshness-ON serialize — sees a component's live children, not stale sourceRaw. */
+function serializeFragment(fragment: Y.XmlFragment): string {
+ return freshMdManager.serialize(yXmlFragmentToProseMirrorRootNode(fragment, schema).toJSON());
+}
+
+/** Read the content-free loss ring straight off disk (no server-internal import). */
+function readLossEvents(contentDir: string): Array<{ event: string; docName: string }> {
+ try {
+ const raw = readFileSync(
+ join(contentDir, '.ok', 'local', 'loss-capture', 'loss-current.jsonl'),
+ 'utf-8',
+ );
+ return raw
+ .split('\n')
+ .filter((line) => line.length > 0)
+ .flatMap((line) => {
+ try {
+ return [JSON.parse(line) as { event: string; docName: string }];
+ } catch {
+ return [];
+ }
+ });
+ } catch {
+ return [];
+ }
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * The append is async (RotatingAppender FIFO), so the ON arm polls for it. The
+ * OFF arm's "nothing was written" must wait AT LEAST as long as the ON arm is
+ * willing to wait — a shorter negative window proves only that the write had
+ * not landed yet.
+ */
+const RING_POLL_ATTEMPTS = 40;
+const RING_POLL_INTERVAL_MS = 50;
+const RING_WAIT_BUDGET_MS = RING_POLL_ATTEMPTS * RING_POLL_INTERVAL_MS;
+
+/** The ring's on-disk file, whether or not it was ever built. */
+function ringPath(contentDir: string): string {
+ return join(contentDir, '.ok', 'local', 'loss-capture', 'loss-current.jsonl');
+}
+
+/**
+ * Stage the derive-timing defer on the booted server's own doc and assert the
+ * guard deferred (the keystroke survives). The defer is the loss producer under
+ * test.
+ */
+async function stageGuardDefer(server: TestServer, docName: string): Promise<void> {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ markdown: GEN1, position: 'replace', docName }),
+ });
+ expect(res.status).toBe(200);
+
+ const doc = server.instance.hocuspocus.documents.get(docName) as unknown as Y.Doc;
+ expect(doc).toBeTruthy();
+ const state = getServerState(server, docName);
+ expect(state?.ytext.toString()).toContain(STALE_LINE);
+ const ytext = state?.ytext as Y.Text;
+ const fragment = state?.fragment as Y.XmlFragment;
+
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(Date.now() + 10_000);
+
+ // Reset the freshness-quiescence clock, then advance the component children
+ // while sourceRaw stays stale so Observer A settles ahead of Y.Text.
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nTrailing.\n');
+ }, 'external-peer');
+ const echo = mdManager.parse(ytext.toString()) as JSONContent;
+ expect(mutateFirstText(echo, STALE_LINE, PENDING_LINE)).toBe(true);
+ doc.transact(() => {
+ updateYFragment(doc, fragment, schema.nodeFromJSON(echo), {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ }, 'wysiwyg-echo');
+ expect(serializeFragment(fragment)).toContain(PENDING_LINE);
+ expect(ytext.toString()).not.toContain(PENDING_LINE);
+
+ // Source write → Observer B re-derive the guard defers (keystroke survives).
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nAnother source line.\n');
+ }, 'external-peer');
+ expect(serializeFragment(fragment)).toContain(PENDING_LINE);
+
+ // Restore real time so the async ring append (RotatingAppender FIFO) can be
+ // polled off disk without the faked clock in the way.
+ vi.useRealTimers();
+}
+
+describe('loss-capture ring — kill-switch behavioral pair', () => {
+ const owned: Array<{ server: TestServer; contentDir?: string }> = [];
+
+ afterEach(async () => {
+ vi.useRealTimers();
+ for (const { server, contentDir } of owned.splice(0)) {
+ await server.cleanup();
+ if (contentDir) rmSync(contentDir, { recursive: true, force: true });
+ }
+ });
+
+ test(
+ 'ON (default): a defer lands a content-free guard-defer event in the ring',
+ async () => {
+ const server = await createTestServer();
+ owned.push({ server });
+ const docName = `ring-on-${crypto.randomUUID().slice(0, 8)}`;
+ await stageGuardDefer(server, docName);
+
+ // Poll the ring off disk — the append is async (FIFO through the appender).
+ let events = readLossEvents(server.contentDir);
+ let elapsedMs = 0;
+ for (
+ let i = 0;
+ i < RING_POLL_ATTEMPTS && !events.some((e) => e.event === GUARD_DEFER_EVENT);
+ i++
+ ) {
+ await sleep(RING_POLL_INTERVAL_MS);
+ elapsedMs += RING_POLL_INTERVAL_MS;
+ events = readLossEvents(server.contentDir);
+ }
+ const deferEvents = events.filter((e) => e.event === GUARD_DEFER_EVENT);
+ expect(deferEvents.length).toBeGreaterThan(0);
+ expect(deferEvents[0]?.docName).toBe(docName);
+ // The observed latency of the write the OFF arm has to out-wait. Kept as
+ // an assertion so a regression that pushes the append past the shared
+ // budget shows up here rather than as a silent OFF-arm false negative.
+ expect(elapsedMs).toBeLessThan(RING_WAIT_BUDGET_MS);
+ },
+ HARNESS_BOOT_TIMEOUT_MS,
+ );
+
+ test(
+ 'OFF (lossCapture.enabled: false): the guard still defers but the ring records nothing',
+ async () => {
+ // Self-seed a contentDir whose config disables the ring, then boot on it.
+ const contentDir = mkdtempSync(join(tmpdir(), 'ok-ring-off-'));
+ mkdirSync(join(contentDir, '.ok'), { recursive: true });
+ writeFileSync(
+ join(contentDir, '.ok', 'config.yml'),
+ 'lossCapture:\n enabled: false\n',
+ 'utf-8',
+ );
+ writeFileSync(join(contentDir, 'test-doc.md'), '', 'utf-8');
+
+ const server = await createTestServer({ contentDir, keepContentDir: true });
+ owned.push({ server, contentDir: server.contentDir });
+ const docName = `ring-off-${crypto.randomUUID().slice(0, 8)}`;
+ await stageGuardDefer(server, docName);
+
+ // The producer fired (keystroke survived, asserted in stageGuardDefer), but
+ // with the ring disabled no event is ever written. Two oracles:
+ //
+ // (1) Structural, timing-free — the ring was never BUILT, so its file does
+ // not exist. Nothing about this can be satisfied by an append that is
+ // merely still in flight.
+ expect(existsSync(ringPath(server.contentDir))).toBe(false);
+
+ // (2) Temporal — out-wait the full budget the ON arm is willing to poll
+ // for, so "empty" cannot mean "not yet".
+ await sleep(RING_WAIT_BUDGET_MS);
+ expect(existsSync(ringPath(server.contentDir))).toBe(false);
+ const deferEvents = readLossEvents(server.contentDir).filter(
+ (e) => e.event === GUARD_DEFER_EVENT,
+ );
+ expect(deferEvents).toEqual([]);
+ },
+ HARNESS_BOOT_TIMEOUT_MS,
+ );
+});
diff --git a/packages/app/tests/integration/network-control.ts b/packages/app/tests/integration/network-control.ts
index 6ab5702d6..a8da424cc 100644
--- a/packages/app/tests/integration/network-control.ts
+++ b/packages/app/tests/integration/network-control.ts
@@ -15,6 +15,7 @@ type MessageCallback = (event: MessageEvent) => void;
export class ControllableWebSocket {
private inner: WebSocket;
private paused = false;
+ private droppingOutbound = false;
private inboundQueue: MessageEvent[] = [];
private onMessageHandler: MessageCallback | null = null;
private addedMessageListeners: MessageCallback[] = [];
@@ -49,6 +50,18 @@ export class ControllableWebSocket {
this.paused = true;
}
+ /**
+ * Discard outbound frames while enabled — models a lost/throttled update the
+ * provider believes it sent (`unsyncedChanges` stays > 0 with no ack, server
+ * never receives it). A later `provider.forceSync()` re-runs the sync
+ * handshake and reconciles the missing update, so this is how a test proves
+ * the flush-on-hide `forceSync` — not the incremental send — reached the
+ * server.
+ */
+ setDropOutbound(drop: boolean): void {
+ this.droppingOutbound = drop;
+ }
+
resumeInbound(): void {
this.paused = false;
while (this.inboundQueue.length > 0) {
@@ -110,6 +123,7 @@ export class ControllableWebSocket {
}
send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void {
+ if (this.droppingOutbound) return;
this.inner.send(data);
}
diff --git a/packages/app/tests/integration/origin-undoability-sweep.test.ts b/packages/app/tests/integration/origin-undoability-sweep.test.ts
new file mode 100644
index 000000000..6ba7f3288
--- /dev/null
+++ b/packages/app/tests/integration/origin-undoability-sweep.test.ts
@@ -0,0 +1,251 @@
+/**
+ * Origin-undoability sweep — the fail-closed registration contract for every
+ * content-writing transaction origin.
+ *
+ * Enumerates every origin-named constant declared under packages/{server,core,
+ * app}/src and requires each to be classified exactly once: as a content-write
+ * origin with a ruled undoability row, or as a non-content origin with a stated
+ * reason. A NEW content origin cannot ship without a row (completeness), and a
+ * removed origin cannot leave a stale row behind (no-phantom) — the two checks
+ * pin a bidirectional set equality between what source declares and what this
+ * contract classifies.
+ *
+ * The undoability rows are the published contract the timeline/undo topology
+ * and the conflict spec extend. Behavioral proof of each ruling lives in the
+ * cross-referenced suites; this sweep guarantees the table stays complete.
+ *
+ * Static readFileSync scan (no server boot), sibling to
+ * attribution-sweep-coverage.test.ts. api-extension.ts carries a NUL byte that
+ * truncates rg/grep but not readFileSync, so the scan reads it whole.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+
+/** Where an origin's writes land on the undo topology. */
+type UndoClass =
+ | 'agent-session-um' // undoable only by the server per-session Y.Text UndoManager
+ | 'agent-undo-system' // the agent-undo write itself; excluded from its own stack
+ | 'client-editor-um' // undoable by a client editor UndoManager (the human Cmd+Z path)
+ | 'system-not-undoable' // recovery/system paired write; tracked by no UndoManager
+ | 'no-undo-manager' // user-surface write captured by no UndoManager (deliberate)
+ | 'replay-not-undoable'; // recovery replay; durable but not Cmd+Z-undoable
+
+interface UndoRow {
+ undo: UndoClass;
+ why: string;
+ /** The behavioral suite(s) that pin this ruling. */
+ contract: string;
+}
+
+/**
+ * Content-writing origin CONSTANTS (mutate Y.Text('source') / Y.XmlFragment via
+ * the bridge primitives), each with its ruled undoability and the suite that
+ * pins it behaviorally.
+ */
+const ORIGIN_UNDO_CONTRACT: Record<string, UndoRow> = {
+ AGENT_WRITE_ORIGIN: {
+ undo: 'agent-session-um',
+ why: 'Typed exemplar for the agent-write origin; real writes carry the per-session session.origin. Undoable only by the server per-session UndoManager, never by a human Cmd+Z.',
+ contract: 'session-undo-manager.test.ts, agent-undo.test.ts',
+ },
+ FILE_WATCHER_ORIGIN: {
+ undo: 'system-not-undoable',
+ why: 'Disk-to-CRDT intake (paired). A system origin tracked by no UndoManager.',
+ contract: 'external-change disk intake (system origin)',
+ },
+ ROLLBACK_ORIGIN: {
+ undo: 'system-not-undoable',
+ why: 'Timeline restore rewrites body + fragment as a paired write; deliberately not client-undoable, and it stales pre-rollback client undo items.',
+ contract: 'undo-after-rollback.test.ts',
+ },
+ MANAGED_RENAME_ORIGIN: {
+ undo: 'system-not-undoable',
+ why: 'Managed-rename spine (paired). System origin tracked by no UndoManager.',
+ contract: 'attribution-sweep-coverage.test.ts (identity threading)',
+ },
+ MERMAID_SOURCE_ORIGIN: {
+ undo: 'system-not-undoable',
+ why: 'Mermaid diagram seed/reconcile into Y.Text(source); system origin, markdown bridge gated off.',
+ contract: 'mermaid-persistence (system origin)',
+ },
+ MERMAID_DIAGRAM_EDIT_ORIGIN: {
+ undo: 'client-editor-um',
+ why: 'Diagram-label commits, tracked by the MermaidDocEditor own client Y.UndoManager so Cmd+Z reverts a label edit.',
+ contract: 'MermaidDocEditor (own UndoManager)',
+ },
+ FORM_WRITE_ORIGIN: {
+ undo: 'no-undo-manager',
+ why: 'Frontmatter property-panel write to the YAML region of Y.Text; single-root, captured by no editor UndoManager.',
+ contract: 'write-surface-undo-exclusion.test.ts',
+ },
+ LINT_FIX_ORIGIN: {
+ undo: 'no-undo-manager',
+ why: 'Client markdownlint auto-fix writing Y.Text(source) directly; captured by no editor UndoManager.',
+ contract: 'write-surface-undo-exclusion.test.ts',
+ },
+ SOURCE_PASTE_ORIGIN: {
+ undo: 'no-undo-manager',
+ why: 'Chunked large source-mode paste writing Y.Text(source) directly, bypassing CM6 dispatch; captured by no editor UndoManager.',
+ contract: 'write-surface-undo-exclusion.test.ts',
+ },
+ TAB_REPLAY_ORIGIN: {
+ undo: 'replay-not-undoable',
+ why: 'Recovery replay of buffered updates onto a recycled provider. The replayed bytes are durable but not Cmd+Z-undoable — post-recycle, the last pre-hiccup edits are recovery machinery, not a fresh user action.',
+ contract: 'undo-recycle-reset.test.ts',
+ },
+};
+
+/**
+ * Content-writing origins minted by a factory rather than a constant — the
+ * per-session agent write + undo origins. Verified present by name below; not
+ * part of the constant enumeration.
+ */
+const FACTORY_ORIGIN_ROWS: Record<string, UndoRow> = {
+ createSessionOrigin: {
+ undo: 'agent-session-um',
+ why: 'Mints the per-session frozen agent-write origin (session.origin); object-identity-unique, added to the session UndoManager trackedOrigins so only that session can undo its writes.',
+ contract: 'session-undo-manager.test.ts, agent-undo.test.ts',
+ },
+ createUndoOrigin: {
+ undo: 'agent-undo-system',
+ why: 'Mints the per-session agent-undo origin (session.undoOrigin); filtered out of its own stack so undo-of-undo never stacks. Idle-LRU eviction destroys the session UndoManager, and a later undo gets the loud no-active-session refusal rather than a wrong-frame pop.',
+ contract: 'agent-undo.test.ts, agent-sessions.eviction.test.ts',
+ },
+};
+
+/**
+ * Origin constants reserved for future registrants but not yet declared in
+ * source. The conflict spec's machine-merge landing registers here when it
+ * ships; excluded from the no-phantom check because it has no source constant.
+ */
+const RESERVED_UNDO_ROWS: Record<string, UndoRow> = {
+ 'machine-merge': {
+ undo: 'system-not-undoable',
+ why: 'Reserved for the conflict spec machine-merge landing; a system paired write excluded from undo pending cross-spec convergence. Becomes an ORIGIN_UNDO_CONTRACT row when the origin ships.',
+ contract: 'reserved (conflict spec extension point)',
+ },
+};
+
+/**
+ * Origin-named constants that are NOT content-writing transaction origins, each
+ * with the reason it carries no undoability ruling.
+ */
+const NON_CONTENT_ORIGINS: Record<string, string> = {
+ OBSERVER_SYNC_ORIGIN:
+ 'The bridge itself — Observer A/B cross-CRDT self-skip; routing it through a UndoManager or the content sweep would loop.',
+ EFFECT_CAPTURE_ORIGIN:
+ 'agent-effects Y.Map ring-buffer side-channel; touches no Y.Text/XmlFragment content.',
+ CONFIG_VALIDATION_REVERT_ORIGIN:
+ 'Config-doc plane revert to last-known-good; markdown bridge bypassed, not content.',
+ CONFIG_FILE_WATCHER_ORIGIN:
+ 'Config-doc plane file-watcher intake; markdown bridge bypassed, not content.',
+ PARK_SNAPSHOT_ORIGIN:
+ 'Read-only serializeDoc wrapper; paired only so observers self-short-circuit, performs no content mutation.',
+ ORIGIN_TREE_TO_TEXT:
+ 'Client observer-direction baseline marker; the client cross-CRDT write path is deleted (precedent #14), so it drives no content write.',
+ ORIGIN_TEXT_TO_TREE:
+ 'Client observer-direction baseline marker; the client cross-CRDT write path is deleted (precedent #14), so it drives no content write.',
+ SELECTION_ORIGIN_META_KEY:
+ 'A ProseMirror selection transaction-meta key, not a Y.Doc transaction origin.',
+ DEFAULT_INTAKE_ORIGIN:
+ 'The uninstall-feedback submission source label, not a CRDT transaction origin.',
+};
+
+const HERE = import.meta.dirname;
+const SRC_ROOTS = [
+ join(HERE, '../../../server/src'),
+ join(HERE, '../../../core/src'),
+ join(HERE, '../../src'),
+];
+const AGENT_SESSIONS_PATH = join(HERE, '../../../server/src/agent-sessions.ts');
+
+/** ORIGIN as a name segment — matches FOO_ORIGIN, ORIGIN_BAR, FOO_ORIGIN_BAZ; not ORIGINAL. */
+const ORIGIN_SEGMENT = /(^|_)ORIGIN(_|$)/;
+/** `const NAME =` or `const NAME: Type =` — the type annotation is single-line. */
+const CONST_DECL = /\bconst\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?::[^=;\n]+)?=/g;
+
+function isScannedSource(fileName: string): boolean {
+ if (!fileName.endsWith('.ts') && !fileName.endsWith('.tsx')) return false;
+ return !(
+ fileName.endsWith('.test.ts') ||
+ fileName.endsWith('.test.tsx') ||
+ fileName.endsWith('.test-helper.ts') ||
+ fileName.endsWith('-test-harness.ts') ||
+ fileName.endsWith('.d.ts')
+ );
+}
+
+function walkTsFiles(dir: string, out: string[]): void {
+ for (const entry of readdirSync(dir)) {
+ if (entry === 'node_modules' || entry === 'dist') continue;
+ const full = join(dir, entry);
+ if (statSync(full).isDirectory()) walkTsFiles(full, out);
+ else if (isScannedSource(entry)) out.push(full);
+ }
+}
+
+/** Every origin-named constant declared across the scanned source trees. */
+function enumerateOriginConstants(): string[] {
+ const files: string[] = [];
+ for (const root of SRC_ROOTS) walkTsFiles(root, files);
+ const names = new Set<string>();
+ for (const file of files) {
+ const source = readFileSync(file, 'utf8');
+ if (!source.includes('ORIGIN')) continue;
+ for (const match of source.matchAll(CONST_DECL)) {
+ const name = match[1];
+ if (ORIGIN_SEGMENT.test(name)) names.add(name);
+ }
+ }
+ return [...names].sort();
+}
+
+/** Names an origin constant is unclassified by this contract. */
+function findUnclassified(originNames: string[]): string[] {
+ return originNames.filter(
+ (name) => !(name in ORIGIN_UNDO_CONTRACT) && !(name in NON_CONTENT_ORIGINS),
+ );
+}
+
+const classifiedNames = [
+ ...Object.keys(ORIGIN_UNDO_CONTRACT),
+ ...Object.keys(NON_CONTENT_ORIGINS),
+].sort();
+
+describe('origin-undoability sweep', () => {
+ const declared = enumerateOriginConstants();
+
+ test('every declared origin constant carries an undoability ruling or a non-content reason', () => {
+ // Fail-loud on an empty scan: a broken walk must never pass silently.
+ expect(declared.length).toBeGreaterThanOrEqual(15);
+ expect(findUnclassified(declared)).toEqual([]);
+ });
+
+ test('the undoability contract has no stale rows (every classified name is declared in source)', () => {
+ const stale = classifiedNames.filter((name) => !declared.includes(name));
+ expect(stale).toEqual([]);
+ });
+
+ test('the per-session factory write + undo origins are present', () => {
+ const source = readFileSync(AGENT_SESSIONS_PATH, 'utf8');
+ for (const factory of Object.keys(FACTORY_ORIGIN_ROWS)) {
+ expect(source).toContain(`function ${factory}`);
+ }
+ });
+
+ test('the sweep catches an unregistered content origin (planted positive)', () => {
+ expect(findUnclassified(['__PLANTED_UNCLASSIFIED_ORIGIN__'])).toEqual([
+ '__PLANTED_UNCLASSIFIED_ORIGIN__',
+ ]);
+ // And a name mixed in with real ones is still isolated.
+ expect(findUnclassified(['FORM_WRITE_ORIGIN', '__PLANTED_UNCLASSIFIED_ORIGIN__'])).toEqual([
+ '__PLANTED_UNCLASSIFIED_ORIGIN__',
+ ]);
+ });
+
+ test('the reserved machine-merge undo row is documented for the conflict-spec extension point', () => {
+ expect(RESERVED_UNDO_ROWS['machine-merge']?.undo).toBe('system-not-undoable');
+ });
+});
diff --git a/packages/app/tests/integration/pre-drain-composition.test.ts b/packages/app/tests/integration/pre-drain-composition.test.ts
new file mode 100644
index 000000000..1c6efbbb4
--- /dev/null
+++ b/packages/app/tests/integration/pre-drain-composition.test.ts
@@ -0,0 +1,145 @@
+/**
+ * R9 — the named worst-case composition (H15 × H9): a pending WYSIWYG keystroke
+ * concurrent with a paired-intake derive while a client reconnects and resyncs.
+ * The invariant is no SILENT loss: the keystroke survives (pre-drain, cross-block)
+ * or is checkpoint-restorable (same-block/overlap), per R1's routing, and every
+ * client converges.
+ *
+ * The un-propagated keystroke is staged directly on the booted server's doc (a
+ * component whose children advance past its stamped source under a
+ * freshness-suppressed drain) — the same real stomp shape the paired-intake
+ * suite proves. Section 9.5(2): the client-side reconnect here uses the harness
+ * sync-control seam, not real browser backgrounding.
+ */
+
+import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
+import type { JSONContent } from '@tiptap/core';
+import { getSchema } from '@tiptap/core';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import type * as Y from 'yjs';
+import {
+ agentWriteMd,
+ assertAllConverged,
+ createTestClient,
+ createTestServer,
+ getServerState,
+ HARNESS_BOOT_TIMEOUT_MS,
+ pollUntil,
+ type TestClient,
+ type TestServer,
+} from './test-harness.ts';
+
+const schema = getSchema(sharedExtensions);
+// The server serializes freshness-ON (its md-manager singleton), so a component's
+// advanced children reach the observers; a freshness-OFF manager would read the
+// stale stored source. Match it for the staging + fragment reads.
+const mdManager = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+});
+
+const GEN1 =
+ '## Guide\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n\nTail paragraph.\n';
+const STALE_LINE = 'Step one bod';
+const PENDING_LINE = 'Step one body.';
+
+function serializeFragment(fragment: Y.XmlFragment): string {
+ return mdManager.serialize(yXmlFragmentToProseMirrorRootNode(fragment, schema).toJSON());
+}
+
+function mutateFirstText(node: JSONContent, from: string, to: string): boolean {
+ if (typeof node.text === 'string' && node.text === from) {
+ node.text = to;
+ return true;
+ }
+ for (const child of node.content ?? []) {
+ if (mutateFirstText(child, from, to)) return true;
+ }
+ return false;
+}
+
+/** Leave the fragment holding PENDING_LINE while Y.Text still holds STALE_LINE. */
+function stageUnpropagatedKeystroke(doc: Y.Doc, ytext: Y.Text, fragment: Y.XmlFragment): void {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(Date.now() + 10_000);
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nTrailing.\n');
+ }, 'external-peer');
+ const echo = mdManager.parse(ytext.toString()) as JSONContent;
+ expect(mutateFirstText(echo, STALE_LINE, PENDING_LINE)).toBe(true);
+ doc.transact(() => {
+ updateYFragment(doc, fragment, schema.nodeFromJSON(echo), {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ }, 'wysiwyg-echo');
+ expect(serializeFragment(fragment)).toContain(PENDING_LINE);
+ expect(ytext.toString()).not.toContain(PENDING_LINE);
+ vi.useRealTimers();
+}
+
+describe('R9 pre-drain composition (H15 × H9)', () => {
+ let server: TestServer;
+
+ beforeEach(async () => {
+ server = await createTestServer({ gitEnabled: true, debounce: 300_000, maxDebounce: 600_000 });
+ }, HARNESS_BOOT_TIMEOUT_MS);
+
+ afterEach(async () => {
+ vi.useRealTimers();
+ await server.cleanup();
+ });
+
+ test('cross-block keystroke survives a paired derive while a client reconnects and resyncs', async () => {
+ const docName = `r9-${crypto.randomUUID().slice(0, 8)}`;
+ await agentWriteMd(server.port, GEN1, { docName, position: 'replace' });
+
+ let client: TestClient | undefined;
+ try {
+ client = await createTestClient(server.port, docName, { syncControl: true });
+
+ // Concurrent client typing (a source-mode edit), then a reconnect gap:
+ // pauseSync leaves the client behind while the server keeps advancing.
+ client.doc.transact(() => {
+ client?.ytext.insert(client.ytext.length, '\nClient typed line.\n');
+ }, 'client-source');
+ // The scenario is "the client is BEHIND after having contributed", so the
+ // typing must have reached the server before the pause. A fixed sleep
+ // silently turns this into "the client is behind having contributed
+ // nothing" whenever it is short, and every assertion below still passes.
+ await pollUntil(
+ () => getServerState(server, docName)?.md.includes('Client typed line.') ?? false,
+ 10_000,
+ );
+ client.pauseSync();
+
+ // A pending WYSIWYG keystroke on the server, cross-block from an append.
+ const state = getServerState(server, docName);
+ const doc = server.instance.hocuspocus.documents.get(docName) as unknown as Y.Doc;
+ stageUnpropagatedKeystroke(doc, state?.ytext as Y.Text, state?.fragment as Y.XmlFragment);
+
+ // The paired-intake derive: an agent append. Pre-drain flushes the
+ // non-overlapping keystroke into Y.Text before the paired transact.
+ await agentWriteMd(server.port, 'Agent appended during reconnect.', {
+ docName,
+ position: 'append',
+ });
+
+ // No silent loss on the server: the keystroke survived AND the append landed.
+ const after = getServerState(server, docName);
+ expect(after?.md).toContain(PENDING_LINE);
+ expect(after?.md).toContain('Agent appended during reconnect.');
+
+ // Resync the reconnecting client and confirm convergence — the survived
+ // keystroke, the client's earlier typing, and the agent append all reconcile.
+ client.resumeSync();
+ await assertAllConverged([client], { timeout: 10_000 });
+ expect(client.ytext.toString()).toContain(PENDING_LINE);
+ expect(client.ytext.toString()).toContain('Agent appended during reconnect.');
+ expect(client.ytext.toString()).toContain('Client typed line.');
+ } finally {
+ await client?.cleanup();
+ }
+ });
+});
diff --git a/packages/app/tests/integration/provider-pool-flush-recycle-race.test.ts b/packages/app/tests/integration/provider-pool-flush-recycle-race.test.ts
new file mode 100644
index 000000000..54a849d1d
--- /dev/null
+++ b/packages/app/tests/integration/provider-pool-flush-recycle-race.test.ts
@@ -0,0 +1,92 @@
+/**
+ * Acceptance: a hidden-flush racing a server-instance-mismatch recycle must not
+ * double-apply the unsynced delta. The recycle's buffer-replay path is the sole
+ * carrier of the un-acked edit across the epoch; `flushOnHide` must not add a
+ * second write of the same content.
+ *
+ * The edit is made WHILE DISCONNECTED so it stays unsynced vs the server
+ * (`unsyncedChanges > 0`) through the recycle — the exact state where a stray
+ * `forceSync` could race the replay. `flushOnHide` is fired across the recycle
+ * window; the `mismatchInFlight` guard skips it mid-recycle, and CRDT
+ * idempotency backs it up. The oracle is the marker's on-disk count after
+ * everything settles (the same duplication oracle the reconnect suite uses).
+ */
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterEach, describe, expect, it } from 'vitest';
+import * as Y from 'yjs';
+import { ProviderPool } from '../../src/editor/provider-pool';
+import {
+ createRestartableServer,
+ pollDiskContentStable,
+ pollUntil,
+ seedPoolServerInstanceId,
+} from './test-harness';
+
+const FIXTURE = `# Race Doc\n\nbase content\n`;
+
+const cleanups: Array<() => Promise<void> | void> = [];
+afterEach(async () => {
+ while (cleanups.length > 0) await cleanups.pop()?.();
+}, 30_000);
+
+describe('flush-on-hide racing a mismatch recycle', () => {
+ it('does not double-apply the unsynced delta (buffer-replay stays exactly-once)', async () => {
+ let server = await createRestartableServer();
+ cleanups.push(() => server.shutdown());
+ const docName = 'flush-race-doc';
+ writeFileSync(join(server.contentDir, `${docName}.md`), FIXTURE, 'utf-8');
+
+ const pool = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`);
+ cleanups.push(() => pool.dispose());
+ await seedPoolServerInstanceId(server, pool);
+ pool.open(docName);
+ pool.setActive(docName);
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);
+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 10_000, 50);
+ await wait(150);
+
+ // Disconnect first, THEN edit — the delta never reaches the server, so it
+ // is unsynced (unsyncedChanges > 0) through the recycle.
+ const MARKER = 'FLUSHRACEMARKER5f2c';
+ server.killNetwork();
+ await pollUntil(() => pool.getActive()?.syncState === 'disconnected', 5_000, 50);
+
+ const doc = pool.getActive()?.provider.document;
+ if (!doc) throw new Error('active provider missing');
+ const paragraph = new Y.XmlElement('paragraph');
+ const text = new Y.XmlText();
+ text.applyDelta([{ insert: MARKER }]);
+ paragraph.insert(0, [text]);
+ doc.getXmlFragment('default').push([paragraph]);
+ expect(pool.getActive()?.provider.unsyncedChanges).toBeGreaterThan(0);
+
+ // Interleave the hidden-flush across the recycle window.
+ pool.flushOnHide(); // disconnected: forceSync is a no-op
+ server = await server.killAndRestartOnSamePort({ downtimeMs: 400 });
+ cleanups.unshift(() => server.shutdown());
+ pool.flushOnHide(); // during reconnect/recycle: mismatchInFlight guard skips it
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);
+ await pool.awaitMismatchSettled();
+ pool.flushOnHide(); // after settle
+
+ // The marker survives in the client doc.
+ await pollUntil(
+ () =>
+ pool.getActive()?.provider.document.getText('source').toString().includes(MARKER) ?? false,
+ 5_000,
+ 50,
+ );
+
+ // …exactly once on disk (the double-apply bug would write it twice).
+ const disk = await pollDiskContentStable(
+ join(server.contentDir, `${docName}.md`),
+ (content) => content.includes(MARKER),
+ { timeoutMs: 8_000, settleMs: 400 },
+ );
+ expect((disk.match(new RegExp(MARKER, 'g')) ?? []).length).toBe(1);
+ // Baseline content is not duplicated either.
+ expect((disk.match(/# Race Doc/g) ?? []).length).toBe(1);
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
new file mode 100644
index 000000000..c1ec55a98
--- /dev/null
+++ b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
@@ -0,0 +1,54 @@
+/**
+ * The regression counters must be readable from OUTSIDE the process.
+ *
+ * `metrics.test.ts` asserts the counters in-process via `getMetrics()`, and the
+ * `/api/metrics/reconciliation` envelope test only checks that `reconcileCount`
+ * is a number. The response schema is `.loose()`, so a counter that was never
+ * added to the serialized snapshot — or one dropped from it — still yields a
+ * schema-valid 200 and an in-process test that keeps passing. The operability
+ * claim ("poll one endpoint and know no protective mechanism has been firing")
+ * lives entirely on fields nothing asserts over HTTP.
+ *
+ */
+
+import { randomUUID } from 'node:crypto';
+import { afterEach, describe, expect, test } from 'vitest';
+import { agentWriteMd, createTestServer, type TestServer } from './test-harness';
+
+let server: TestServer | undefined;
+afterEach(async () => {
+ await server?.cleanup();
+ server = undefined;
+});
+
+/** Counters whose whole purpose is external readability. */
+const REQUIRED_COUNTERS = [
+ 'deriveTimingDeferForceResolved',
+ 'reDeriveBackstopTripped',
+ 'reconcileCount',
+] as const;
+
+describe('GET /api/metrics/reconciliation exposes the regression counters', () => {
+ test('the mechanism counters survive serialization and read zero on a healthy editing session', async () => {
+ server = await createTestServer();
+ const docName = `qa039-${randomUUID().slice(0, 8)}`;
+
+ // A healthy session: an ordinary agent write, no mechanism staging.
+ await agentWriteMd(server.port, '# Healthy\n\nordinary body\n', {
+ docName,
+ position: 'replace',
+ });
+
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/reconciliation`);
+ expect(res.status).toBe(200);
+ const body = (await res.json()) as Record<string, unknown>;
+
+ // Presence: a `.loose()` schema cannot catch a dropped counter, so name them.
+ for (const counter of REQUIRED_COUNTERS) {
+ expect(typeof body[counter]).toBe('number');
+ }
+ // Healthy run: no protective mechanism has fired.
+ expect(body.deriveTimingDeferForceResolved).toBe(0);
+ expect(body.reDeriveBackstopTripped).toBe(0);
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
new file mode 100644
index 000000000..72dd3b60a
--- /dev/null
+++ b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
@@ -0,0 +1,162 @@
+/**
+ * Restore attempts against a checkpoint whose ref has been garbage-collected.
+ *
+ * The timeline hides a GC'd row, but a client holding a stale sha — a diff pane
+ * left open across a retention sweep, a copied permalink — can still POST it.
+ * Every other malformed-restore shape has an envelope test; this one does not,
+ * so the failure mode it guards (a partial restore, or a 500 where a 404
+ * belongs) is unobserved. The doc must come out byte-identical.
+ *
+ */
+
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import {
+ DEFAULT_CHECKPOINT_RETENTION,
+ gcCheckpointRefs,
+ initShadowRepo,
+ saveInMemoryCheckpoint,
+} from '@inkeep/open-knowledge-server';
+import { afterEach, describe, expect, test } from 'vitest';
+import {
+ agentWriteMd,
+ awaitWipCommits,
+ createTestServer,
+ pollDiskContentStable,
+ readTestDoc,
+ type TestServer,
+} from './test-harness';
+
+let server: TestServer | undefined;
+afterEach(async () => {
+ await server?.cleanup();
+ server = undefined;
+});
+
+const LIVE = '# Live\n\nlive body anchor\n';
+
+describe('restore after checkpoint GC', () => {
+ test('an evicted sha stays readable until the objects are pruned, then fails loudly and leaves the document byte-identical', async () => {
+ server = await createTestServer({ gitEnabled: true, commitDebounceMs: 100 });
+ const docName = `qa045-${randomUUID().slice(0, 8)}`;
+
+ await agentWriteMd(server.port, LIVE, { docName, position: 'replace' });
+ await awaitWipCommits(server, docName, 1);
+ const before = await pollDiskContentStable(
+ join(server.contentDir, `${docName}.md`),
+ (c) => c.includes('live body anchor'),
+ { timeoutMs: 5000, settleMs: 200 },
+ );
+
+ // Two checkpoints of one kind, so keep-1 evicts exactly one of them.
+ const shadow = await initShadowRepo(server.contentDir);
+ const firstSha = await saveInMemoryCheckpoint(shadow, '', {
+ kind: 'defer-exhaustion-loss',
+ docName,
+ contents: '# Older\n\nolder recovered body\n',
+ branch: 'main',
+ label: 'older recovery',
+ metadata: { deferCount: 9 },
+ });
+ const secondSha = await saveInMemoryCheckpoint(shadow, '', {
+ kind: 'defer-exhaustion-loss',
+ docName,
+ contents: '# Newer\n\nnewer recovered body\n',
+ branch: 'main',
+ label: 'newer recovery',
+ metadata: { deferCount: 9 },
+ });
+
+ // Sanity: both shas resolve BEFORE the sweep, so a 404 after it is the
+ // GC's doing and not a bad sha.
+ for (const sha of [firstSha, secondSha]) {
+ const preRead = await fetch(
+ `http://127.0.0.1:${server.port}/api/history/${sha}?docName=${encodeURIComponent(docName)}`,
+ );
+ expect(preRead.status).toBe(200);
+ }
+
+ const checkpointRefShas = (): Set<string> =>
+ 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),
+ );
+ const refsBefore = checkpointRefShas();
+
+ const gc = await gcCheckpointRefs(shadow, 'main', {
+ ...DEFAULT_CHECKPOINT_RETENTION,
+ maxDeferExhaustionLoss: 1,
+ ttlMs: 0,
+ });
+ 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.
+ 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);
+
+ // The row is gone from the timeline...
+ const histRes = await fetch(
+ `http://127.0.0.1:${server.port}/api/history?docName=${encodeURIComponent(docName)}&limit=100`,
+ );
+ const hist = (await histRes.json()) as { entries: Array<{ sha: string }> };
+ expect(hist.entries.some((e) => e.sha === evictedSha)).toBe(false);
+
+ // Dropping the ref does not destroy the object — git keeps unreferenced
+ // commits until they are pruned — so the blob is still readable by sha in
+ // the window between the retention sweep and the next prune. Pin that
+ // characterization explicitly rather than assuming the row's disappearance
+ // implies a 404.
+ const readBeforePrune = await fetch(
+ `http://127.0.0.1:${server.port}/api/history/${evictedSha}?docName=${encodeURIComponent(docName)}`,
+ );
+ expect(readBeforePrune.status).toBe(200);
+
+ // After a real prune the object is genuinely gone — this is the state a
+ // stale diff pane eventually POSTs against.
+ const gitEnv = { ...process.env, GIT_DIR: shadow.gitDir, GIT_WORK_TREE: shadow.workTree };
+ execFileSync('git', ['reflog', 'expire', '--expire=now', '--expire-unreachable=now', '--all'], {
+ cwd: shadow.workTree,
+ env: gitEnv,
+ });
+ execFileSync('git', ['gc', '--prune=now', '--quiet'], { cwd: shadow.workTree, env: gitEnv });
+
+ const readRes = await fetch(
+ `http://127.0.0.1:${server.port}/api/history/${evictedSha}?docName=${encodeURIComponent(docName)}`,
+ );
+ expect(readRes.status).toBe(404);
+
+ const rbRes = await fetch(`http://127.0.0.1:${server.port}/api/rollback`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ docName, commitSha: evictedSha }),
+ });
+ // Loud and safe: a client-visible 4xx, never a 5xx and never a partial write.
+ expect(rbRes.status).toBeGreaterThanOrEqual(400);
+ expect(rbRes.status).toBeLessThan(500);
+ const problem = (await rbRes.json()) as { type?: string };
+ expect(typeof problem.type).toBe('string');
+ expect(problem.type?.startsWith('urn:ok:error:')).toBe(true);
+
+ // 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',
+ );
+ }, 60_000);
+});
diff --git a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
new file mode 100644
index 000000000..0b9fa1ed8
--- /dev/null
+++ b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
@@ -0,0 +1,192 @@
+/**
+ * CONTRACT — client undo topology under a rollback driven on the SHIPPED path.
+ *
+ * `undo-after-rollback.test.ts` pins the same ruling against a hand-reproduced
+ * paired write (a local `document.transact(..., 'rollback-remote')` string
+ * origin). That models the wire shape but never drives the production spine, so
+ * a drift in `handleRollback` → `replaceRawBody` → `ROLLBACK_ORIGIN` — a
+ * changed origin constant, a lost `transact` wrapper, a fragment rewrite
+ * outside the paired origin — would leave the model green while Cmd+Z started
+ * eating or resurrecting restored content in the product.
+ *
+ * This closes that seam: a real booted server, a real WebSocket client whose
+ * Y.Doc carries a real Collaboration-bound editor and its fragment-scoped
+ * `Y.UndoManager`, and a real `POST /api/rollback`. The rollback arrives at the
+ * client as a genuine remote transaction, and the undo topology is asserted on
+ * what actually arrived.
+ *
+ * A behavior flip here is an undo-topology regression to investigate, not a
+ * test to silently re-baseline.
+ *
+ * WARN — this is NOT a guard on the individual lines of the rollback spine.
+ * Measured: deleting `replaceRawBody`'s `updateYFragment` re-derive, deleting
+ * its Y.Text overwrite, and clearing `ROLLBACK_ORIGIN`'s `paired: true` marker
+ * each leave this test GREEN, because the bridge watchdog re-derives the
+ * fragment behind all three. That is the watchdog doing its job, not a hole
+ * here — but it means "qa-050 is green" must never be read as "those lines are
+ * still needed". The `paired: true` marker is separately merge-gated by the
+ * static scan in `paired-write-enforcement.test.ts`; do not "simplify" any of
+ * these three on the strength of this suite passing.
+ *
+ */
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
+import type * as Y from 'yjs';
+
+import {
+ insertLocal,
+ mountCollabEditor,
+ readUndoManager,
+} from '../../src/editor/editor-rig.test-helper';
+import { installDomGlobals } from '../../src/editor/walk-currency-test-harness';
+import {
+ agentWriteMd,
+ awaitDocQuiescence,
+ awaitWipCommits,
+ createTestClient,
+ createTestServer,
+ pollUntil,
+ type TestServer,
+} from './test-harness';
+
+function countOccurrences(hay: string, needle: string): number {
+ let n = 0;
+ let i = hay.indexOf(needle);
+ while (i !== -1) {
+ n++;
+ i = hay.indexOf(needle, i + needle.length);
+ }
+ return n;
+}
+
+let restoreDom: (() => void) | null = null;
+beforeAll(() => {
+ // The real WS transport constructs its events from the GLOBAL `Event`, and
+ // node's EventTarget brand-check rejects jsdom's cross-realm one. Keep the
+ // editor rig's DOM globals but hand node's Event back.
+ const nodeEvent = globalThis.Event;
+ const nodeCustomEvent = globalThis.CustomEvent;
+ restoreDom = installDomGlobals();
+ Object.defineProperty(globalThis, 'Event', {
+ value: nodeEvent,
+ configurable: true,
+ writable: true,
+ });
+ Object.defineProperty(globalThis, 'CustomEvent', {
+ value: nodeCustomEvent,
+ configurable: true,
+ writable: true,
+ });
+}, 30_000);
+afterAll(() => {
+ restoreDom?.();
+});
+
+let server: TestServer | undefined;
+afterEach(async () => {
+ await server?.cleanup();
+ server = undefined;
+});
+
+const ORIGINAL = '# Original\n\noriginal body anchor\n';
+const SUPERSEDING = '# Superseding\n\nsuperseding body anchor\n';
+const TYPED = 'USER TYPED AFTER RESTORE POINT';
+
+describe('rollback on the shipped path leaves the client undo stack invariant', () => {
+ test('a real POST /api/rollback is not undoable, does not pop the user stack, and a stale item cannot resurrect the discarded content', async () => {
+ server = await createTestServer({ gitEnabled: true, commitDebounceMs: 100 });
+ const docName = `qa050-${randomUUID().slice(0, 8)}`;
+
+ // Version 1 — the restore target.
+ await agentWriteMd(server.port, ORIGINAL, { docName, position: 'replace' });
+ await awaitWipCommits(server, docName, 1);
+ const histRes = await fetch(
+ `http://127.0.0.1:${server.port}/api/history?docName=${encodeURIComponent(docName)}&limit=100`,
+ );
+ expect(histRes.status).toBe(200);
+ const hist = (await histRes.json()) as { entries: Array<{ sha: string }> };
+ const restoreSha = hist.entries[0]?.sha;
+ expect(restoreSha).toBeTruthy();
+
+ // Version 2 — what the rollback will discard.
+ await agentWriteMd(server.port, SUPERSEDING, { docName, position: 'replace' });
+
+ const client = await createTestClient(server.port, docName);
+ try {
+ await pollUntil(() => client.ytext.toString().includes('superseding body anchor'), 10_000);
+
+ const editor = mountCollabEditor(client.doc, []);
+ try {
+ const um = readUndoManager(editor) as Y.UndoManager;
+ expect(um).not.toBeNull();
+
+ // The user types on top of version 2 — a genuine local, tracked edit.
+ insertLocal(editor, TYPED, 1);
+ await pollUntil(() => client.ytext.toString().includes(TYPED), 10_000);
+ const stackBefore = um.undoStack.length;
+ expect(stackBefore).toBeGreaterThan(0);
+
+ // The shipped restore: real HTTP → handleRollback → replaceRawBody →
+ // ROLLBACK_ORIGIN → over the wire to this client.
+ const rbRes = await fetch(`http://127.0.0.1:${server.port}/api/rollback`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ docName, commitSha: restoreSha }),
+ });
+ expect(rbRes.status).toBe(200);
+
+ await pollUntil(() => client.ytext.toString().includes('original body anchor'), 15_000);
+ const afterRollback = client.ytext.toString();
+ expect(afterRollback).not.toContain('superseding body anchor');
+
+ // (1) The rollback was NOT captured as an undoable item — the stack sits
+ // exactly where the user's own typing left it.
+ expect(um.undoStack.length).toBe(stackBefore);
+
+ // The restore must be visible on the surface the undo will act on
+ // BEFORE the undo runs, or nothing below can discriminate.
+ await pollUntil(
+ () => editor.state.doc.textContent.includes('original body anchor'),
+ 10_000,
+ );
+
+ // `um` is FRAGMENT-scoped, so `um.undo()` mutates the XmlFragment, and
+ // client-side cross-CRDT observers are deliberate no-ops (precedent #14)
+ // — `client.ytext` therefore cannot change synchronously here. Reading it
+ // straight back re-reads state already asserted above and would pass even
+ // if the undo resurrected the discarded version or wiped the document.
+ // Every assertion below observes the FRAGMENT (what the undo mutates)
+ // and then the round trip back into Y.Text.
+ um.undo();
+ const fragAfterUndo = editor.state.doc.textContent;
+
+ // (2) Cmd+Z does not revert the restore.
+ expect(fragAfterUndo).toContain('original body anchor');
+ // (3) The pre-rollback stack item cannot resurrect the discarded version
+ // or the user's own superseded typing.
+ expect(fragAfterUndo).not.toContain('superseding body anchor');
+ expect(fragAfterUndo).not.toContain(TYPED);
+ // (4) Occurrence-count oracle on the post-undo fragment, with a lower
+ // bound: the undo neither spliced a second copy in nor emptied it.
+ expect(countOccurrences(fragAfterUndo, 'original body anchor')).toBe(1);
+ expect(fragAfterUndo.trim().length).toBeGreaterThan(0);
+
+ // (5) Anything the undo emitted round-trips: client → server Observer A
+ // → Y.Text → back. The source bytes at rest still hold the restore
+ // exactly once, with nothing resurrected.
+ await awaitDocQuiescence(client.doc, { timeoutMs: 5_000 });
+ await pollUntil(() => client.provider.unsyncedChanges === 0, 10_000);
+ const ytextAfterUndo = client.ytext.toString();
+ expect(ytextAfterUndo).toContain('original body anchor');
+ expect(ytextAfterUndo).not.toContain('superseding body anchor');
+ expect(ytextAfterUndo).not.toContain(TYPED);
+ expect(countOccurrences(ytextAfterUndo, 'original body anchor')).toBe(1);
+ } finally {
+ editor.destroy();
+ }
+ } finally {
+ await client.cleanup();
+ }
+ }, 60_000);
+});
diff --git a/packages/app/tests/integration/replay-outbox-durable.test.ts b/packages/app/tests/integration/replay-outbox-durable.test.ts
new file mode 100644
index 000000000..963aff73b
--- /dev/null
+++ b/packages/app/tests/integration/replay-outbox-durable.test.ts
@@ -0,0 +1,138 @@
+/**
+ * Durable replay-outbox across a real `server-instance-mismatch` recycle.
+ *
+ * The in-memory buffer loses an unsynced edit if the tab dies inside the
+ * recycle window. The durable outbox (`replay-outbox.ts`) closes that window:
+ * it is written to a SEPARATE IndexedDB database BEFORE `clearData()` wipes the
+ * y-indexeddb store, and consumed on reopen.
+ *
+ * SCOPE — what this test does and does not establish. It drives the real
+ * mismatch (kill network → restart server on the same port → auth reject →
+ * recycle) with an unsynced edit, in the SAME tab. The replay prefers the RAM
+ * buffer and reads the outbox only as a fallback, so on a same-tab recycle the
+ * buffer is always populated and it, not the outbox, is what carries the edit
+ * across. The outbox's role here is its LIFECYCLE — written before `clearData`,
+ * survives it, and is consumed rather than orphaned — which is exactly what the
+ * assertions below check. The carrier-of-last-resort behavior (a tab that dies
+ * mid-recycle, where the outbox is the only carrier) needs a rig that discards
+ * the RAM buffer and is not covered here.
+ *
+ * Asserts:
+ *
+ * 1. The edit survives on disk exactly once (no regression from the durable
+ * layer, no duplication).
+ * 2. The durable outbox for the doc was WRITTEN during the mismatch (its
+ * database exists afterward, proving it survived `clearData`) and its
+ * record was CONSUMED by the replay (no orphan buffer that a later open
+ * could re-apply — consume-first in the real flow).
+ */
+
+import './idb-preload';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterEach, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+import { ProviderPool } from '../../src/editor/provider-pool';
+import { readReplayOutboxEntry } from '../../src/editor/replay-outbox';
+import {
+ createRestartableServer,
+ pollDiskContentStable,
+ pollUntil,
+ seedPoolServerInstanceId,
+} from './test-harness';
+
+const SEED_MD = `# Durable Doc
+
+Base paragraph.
+`;
+
+const cleanups: Array<() => Promise<void> | void> = [];
+
+afterEach(async () => {
+ while (cleanups.length > 0) {
+ await cleanups.pop()?.();
+ }
+}, 30_000);
+
+/** Outbox databases whose key ends in the given docName. */
+async function outboxDbsForDoc(docName: string): Promise<string[]> {
+ const dbs = await indexedDB.databases();
+ return dbs
+ .map((d) => d.name)
+ .filter((n): n is string => typeof n === 'string')
+ .filter((n) => n.startsWith('ok-replay-outbox:') && n.endsWith(`:${docName}`));
+}
+
+describe('durable replay outbox across server-instance-mismatch', () => {
+ test('unsynced edit survives the same-tab recycle and its durable outbox is written then consumed', async () => {
+ let server = await createRestartableServer();
+ cleanups.push(() => server.shutdown());
+
+ const pool = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`);
+ cleanups.push(() => pool.dispose());
+ await seedPoolServerInstanceId(server, pool);
+
+ const docName = 'durable-doc';
+ writeFileSync(join(server.contentDir, `${docName}.md`), SEED_MD, 'utf-8');
+ pool.open(docName);
+ pool.setActive(docName);
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);
+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 10_000, 50);
+ await wait(150);
+
+ // A local WYSIWYG-style edit — a real Y.js mutation under the client's
+ // clientID, so it produces an unsynced delta the recycle must carry.
+ const marker = 'DURABLE-OUTBOX-MARKER-7b21';
+ const firstProvider = pool.getActive()?.provider;
+ if (!firstProvider) throw new Error('expected active provider');
+ const paragraph = new Y.XmlElement('paragraph');
+ const xmlText = new Y.XmlText();
+ xmlText.applyDelta([{ insert: marker }]);
+ paragraph.insert(0, [xmlText]);
+ firstProvider.document.getXmlFragment('default').push([paragraph]);
+
+ // Let the edit reach the server's in-memory Y.Doc, then kill the network
+ // BEFORE the persistence debounce flushes it to disk — the fresh server
+ // then rebuilds from a marker-less disk, so the durable outbox is what
+ // carries the edit across the recycle.
+ await pollUntil(() => firstProvider.unsyncedChanges === 0, 180, 10);
+ server.killNetwork();
+ await pollUntil(() => pool.getActive()?.syncState === 'disconnected', 5_000, 25);
+
+ server = await server.killAndRestartOnSamePort({ downtimeMs: 400 });
+ cleanups.unshift(() => server.shutdown());
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);
+
+ // The edit survives in the fresh client Y.Doc.
+ await pollUntil(
+ () =>
+ pool.getActive()?.provider.document.getText('source').toString().includes(marker) ?? false,
+ 5_000,
+ 50,
+ );
+
+ // The edit lands back on disk exactly once (no duplication).
+ const afterRestart = await pollDiskContentStable(
+ join(server.contentDir, `${docName}.md`),
+ (c) => c.includes(marker),
+ { timeoutMs: 8_000, settleMs: 400 },
+ );
+ expect((afterRestart.match(new RegExp(marker, 'g')) ?? []).length).toBe(1);
+ expect((afterRestart.match(/# Durable Doc/g) ?? []).length).toBe(1);
+
+ // The durable outbox was written during the mismatch (its database exists,
+ // so it survived clearData) and its record was consumed by the replay —
+ // no orphan buffer remains for a later open to re-apply.
+ const outboxDbs = await outboxDbsForDoc(docName);
+ expect(outboxDbs.length).toBeGreaterThanOrEqual(1);
+ for (const dbName of outboxDbs) {
+ const segments = dbName.split(':');
+ const branch = segments[1] ?? '';
+ expect(await readReplayOutboxEntry(branch, docName)).toBeNull();
+ }
+
+ const finalOnDisk = readFileSync(join(server.contentDir, `${docName}.md`), 'utf-8');
+ expect((finalOnDisk.match(new RegExp(marker, 'g')) ?? []).length).toBe(1);
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/silent-checkpoint-restore.test.ts b/packages/app/tests/integration/silent-checkpoint-restore.test.ts
new file mode 100644
index 000000000..c7a457122
--- /dev/null
+++ b/packages/app/tests/integration/silent-checkpoint-restore.test.ts
@@ -0,0 +1,97 @@
+/**
+ * End-to-end restore floor for silent (extension-less) checkpoints.
+ *
+ * `saveInMemoryCheckpoint` writes the recovered blob at the extension-LESS
+ * docName tree path (`<root>/foo`), because the Hocuspocus doc name that flows
+ * through the CRDT layer is already extension-less. The restore read paths
+ * (`GET /api/history`, `GET /api/history/:sha`, `POST /api/rollback`) used to
+ * probe only the extension-full disk path (`<root>/foo.md`), so a silent
+ * checkpoint's row was dropped from the timeline and its sha 404'd — the
+ * rescued content was reachable by no API at all. This drives the real HTTP
+ * handlers against a real shadow repo to prove the floor is reachable
+ * end-to-end.
+ */
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { initShadowRepo, saveInMemoryCheckpoint } from '@inkeep/open-knowledge-server';
+import { afterEach, describe, expect, test } from 'vitest';
+import {
+ agentWriteMd,
+ awaitWipCommits,
+ createTestServer,
+ pollDiskContentStable,
+ type TestServer,
+} from './test-harness';
+
+let server: TestServer | undefined;
+
+afterEach(async () => {
+ await server?.cleanup();
+ server = undefined;
+});
+
+describe('D8 silent-checkpoint restore floor (end-to-end HTTP)', () => {
+ test('a silent extension-less checkpoint surfaces in history, reads back, and restores', async () => {
+ server = await createTestServer({ gitEnabled: true, commitDebounceMs: 100 });
+ const docName = `silent-restore-${randomUUID().slice(0, 8)}`;
+
+ // Live content the user is currently editing.
+ await agentWriteMd(server.port, '# Live content\n\ncurrent body\n', {
+ docName,
+ position: 'replace',
+ });
+ await awaitWipCommits(server, docName, 1);
+
+ // Seed a silent bridge-merge-loss checkpoint the way production does:
+ // contentRoot '' → bare (extension-less) docName tree path, matching the
+ // handler's extension-less resolution twin.
+ const shadow = await initShadowRepo(server.contentDir);
+ const recovered = '# Recovered content\n\nthe keystroke that was almost lost\n';
+ const silentSha = await saveInMemoryCheckpoint(shadow, '', {
+ kind: 'bridge-merge-loss',
+ docName,
+ contents: recovered,
+ branch: 'main',
+ label: 'Before concurrent merge @ 2026-05-05T12:00:00Z',
+ metadata: { lostSubstrings: ['the keystroke'] },
+ });
+
+ // 1) The silent-kind row reaches the /api/history payload with its kind.
+ const histRes = await fetch(
+ `http://127.0.0.1:${server.port}/api/history?docName=${encodeURIComponent(docName)}&limit=100`,
+ );
+ expect(histRes.status).toBe(200);
+ const hist = (await histRes.json()) as {
+ entries: Array<{ sha: string; type: string; checkpoint?: { kind?: string } | null }>;
+ };
+ const row = hist.entries.find((e) => e.sha === silentSha);
+ expect(row).toBeDefined();
+ expect(row?.type).toBe('checkpoint');
+ expect(row?.checkpoint?.kind).toBe('bridge-merge-loss');
+
+ // 2) /api/history/:sha reads the checkpointed content back out.
+ const readRes = await fetch(
+ `http://127.0.0.1:${server.port}/api/history/${silentSha}?docName=${encodeURIComponent(docName)}`,
+ );
+ expect(readRes.status).toBe(200);
+ const read = (await readRes.json()) as { content: string };
+ expect(read.content).toBe(recovered);
+
+ // 3) /api/rollback restores the checkpointed content into the live doc via
+ // the same replaceRawBody spine as any rollback.
+ const rbRes = await fetch(`http://127.0.0.1:${server.port}/api/rollback`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ docName, commitSha: silentSha }),
+ });
+ expect(rbRes.status).toBe(200);
+
+ const disk = await pollDiskContentStable(
+ join(server.contentDir, `${docName}.md`),
+ (c) => c.includes('Recovered content'),
+ { timeoutMs: 5000, settleMs: 200 },
+ );
+ expect(disk).toContain('Recovered content');
+ expect(disk).not.toContain('current body');
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/source-mode-single-undo.test.ts b/packages/app/tests/integration/source-mode-single-undo.test.ts
new file mode 100644
index 000000000..c50bcdeaa
--- /dev/null
+++ b/packages/app/tests/integration/source-mode-single-undo.test.ts
@@ -0,0 +1,132 @@
+/**
+ * CONTRACT — source mode runs exactly ONE undo system, and it is origin-aware.
+ *
+ * The source editor binds a shared Y.Text to CodeMirror via y-codemirror.next.
+ * Its Y.UndoManager tracks only the local sync origin, so remote peers and
+ * agent writes (which arrive under other origins) are excluded from undo. The
+ * shipped wiring removes CodeMirror's native `history()` and routes Mod-z to
+ * that origin-aware manager via `yUndoManagerKeymap`; native history is
+ * origin-blind and would revert the sync plugin's remote-reflecting
+ * transactions — content the user never wrote.
+ *
+ * These rows drive a REAL CodeMirror 6 EditorView over a REAL Y.Text with the
+ * production wiring imported from source. A remote/agent write is modeled the
+ * way a provider delivers one: a diff applied under a non-binding origin (the
+ * repo's established remote-peer stand-in). The `legacy` arm pins the pre-fix
+ * dual-capture defect, so a regression back to native history flips it red
+ * rather than silently re-baselining.
+ *
+ * Fidelity residual: the real browser Mod-z keydown → keymap resolution rides
+ * the registered Playwright rung (source-mode-undo-keymap.e2e.ts); this tier
+ * exercises the keymap's bound command.
+ */
+
+import { undoDepth } from '@codemirror/commands';
+import type { EditorView } from '@codemirror/view';
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+import { installDomGlobals } from '../../src/editor/walk-currency-test-harness';
+import {
+ applyRemoteSourceEdit,
+ installCmMeasurementStubs,
+ mountSourceUndoEditor,
+ runSourceUndo,
+ type SourceUndoWiring,
+ typeInSource,
+} from './source-undo-rig.test-helper';
+
+let restoreDom: (() => void) | null = null;
+beforeAll(() => {
+ restoreDom = installDomGlobals();
+ installCmMeasurementStubs();
+}, 30_000);
+afterAll(() => {
+ restoreDom?.();
+});
+
+const cleanups: Array<() => void> = [];
+afterEach(() => {
+ while (cleanups.length > 0) cleanups.pop()?.();
+});
+
+interface Rig {
+ doc: Y.Doc;
+ ytext: Y.Text;
+ view: EditorView;
+}
+
+function mount(wiring: SourceUndoWiring, seed = ''): Rig {
+ const doc = new Y.Doc();
+ const ytext = doc.getText('source');
+ if (seed) ytext.insert(0, seed);
+ const awareness = new Awareness(doc);
+ const parent = globalThis.document.createElement('div');
+ globalThis.document.body.appendChild(parent);
+ const { view, destroy } = mountSourceUndoEditor({ ytext, awareness, wiring, parent });
+ cleanups.push(() => {
+ destroy();
+ parent.remove();
+ awareness.destroy();
+ doc.destroy();
+ });
+ return { doc, ytext, view };
+}
+
+describe('source-mode single origin-aware undo (production wiring)', () => {
+ test('a source edit registers no CodeMirror native undo history', () => {
+ const { view, ytext } = mount('production');
+
+ typeInSource(view, 'hello');
+ expect(ytext.toString()).toBe('hello');
+ // No native history state field is present, so there is exactly one undo
+ // system (the Y.UndoManager) — double capture is eliminated.
+ expect(undoDepth(view.state)).toBe(0);
+
+ runSourceUndo(view, 'production');
+ expect(view.state.doc.toString()).toBe('');
+ expect(ytext.toString()).toBe('');
+ });
+
+ test('undo reverts the user edit but never a remote write (origin-blind negative)', () => {
+ const { view, doc, ytext } = mount('production');
+
+ applyRemoteSourceEdit(doc, (t) => t.insert(0, 'REMOTE\n'));
+ expect(view.state.doc.toString()).toBe('REMOTE\n');
+
+ typeInSource(view, 'local');
+ expect(ytext.toString()).toBe('REMOTE\nlocal');
+
+ runSourceUndo(view, 'production');
+ // Only the local edit is reverted; the remote write survives.
+ expect(ytext.toString()).toBe('REMOTE\n');
+ expect(view.state.doc.toString()).toBe('REMOTE\n');
+ });
+
+ test('undo is a no-op when only remote content is present', () => {
+ const { view, doc, ytext } = mount('production');
+
+ applyRemoteSourceEdit(doc, (t) => t.insert(0, 'REMOTE\n'));
+
+ // The Y.UndoManager stack holds no local edit, so undo leaves the remote
+ // content untouched (contrast the legacy arm below).
+ runSourceUndo(view, 'production');
+ expect(ytext.toString()).toBe('REMOTE\n');
+ expect(view.state.doc.toString()).toBe('REMOTE\n');
+ });
+});
+
+describe('source-mode undo pre-fix characterization (legacy CodeMirror history)', () => {
+ test('native history reverts a remote write (the origin-blind defect this fix removes)', () => {
+ const { view, doc } = mount('legacy');
+
+ applyRemoteSourceEdit(doc, (t) => t.insert(0, 'REMOTE\n'));
+ expect(view.state.doc.toString()).toBe('REMOTE\n');
+ // Native history captured the sync plugin's remote-reflecting transaction.
+ expect(undoDepth(view.state)).toBeGreaterThan(0);
+
+ runSourceUndo(view, 'legacy');
+ // Origin-blind: the local undo destroyed a remote peer's content.
+ expect(view.state.doc.toString()).not.toContain('REMOTE');
+ });
+});
diff --git a/packages/app/tests/integration/source-undo-rig.test-helper.ts b/packages/app/tests/integration/source-undo-rig.test-helper.ts
new file mode 100644
index 000000000..c22a4b89d
--- /dev/null
+++ b/packages/app/tests/integration/source-undo-rig.test-helper.ts
@@ -0,0 +1,132 @@
+/**
+ * Shared rig for the source-mode undo contract suites.
+ *
+ * Mounts a real CodeMirror 6 EditorView bound to a real Y.Text('source') via
+ * y-codemirror.next, in either the shipped `production` wiring (sourceModeSetup
+ * + yUndoManagerKeymap → the origin-aware Y.UndoManager is the only undo
+ * authority) or the `legacy` wiring (codemirror `basicSetup`, whose native
+ * history captures the sync plugin's remote/agent-reflecting transactions).
+ * The legacy arm exists to characterize the pre-fix dual-capture behavior.
+ *
+ * Test-only module — not imported by production code.
+ */
+
+import { undo as cmNativeUndo } from '@codemirror/commands';
+import { EditorState } from '@codemirror/state';
+import { EditorView, keymap } from '@codemirror/view';
+import { basicSetup } from 'codemirror';
+import { yCollab, yUndoManagerKeymap } from 'y-codemirror.next';
+import type { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+import { sourceModeSetup } from '../../src/editor/source-mode-setup';
+
+export type SourceUndoWiring = 'production' | 'legacy';
+
+// The non-binding origin a HocuspocusProvider stamps on a remote peer's update;
+// mirrors the provider stand-in the ProseMirror walk-currency rig uses so the
+// modeled remote write is byte-shaped like production intake.
+const REMOTE_PROVIDER_ORIGIN = Object.freeze({ kind: 'source-undo-remote-provider' });
+
+/**
+ * jsdom's `Range` omits the geometry methods CodeMirror calls while measuring;
+ * install no-op stubs so a headless EditorView mounts and dispatches. Idempotent.
+ */
+export function installCmMeasurementStubs(): void {
+ const rangeProto = globalThis.Range?.prototype as Range | undefined;
+ if (!rangeProto) return;
+ Object.defineProperty(rangeProto, 'getClientRects', {
+ configurable: true,
+ value: () => [] as unknown as DOMRectList,
+ });
+ Object.defineProperty(rangeProto, 'getBoundingClientRect', {
+ configurable: true,
+ value: () => ({
+ bottom: 0,
+ height: 0,
+ left: 0,
+ right: 0,
+ top: 0,
+ width: 0,
+ x: 0,
+ y: 0,
+ toJSON: () => ({}),
+ }),
+ });
+}
+
+export interface MountedSourceUndoEditor {
+ view: EditorView;
+ /**
+ * The very `Y.UndoManager` `yCollab` binds — constructed here with the same
+ * `new Y.UndoManager(ytext)` expression yCollab uses by default, purely so
+ * callers can read `undoStack.length` and set frame boundaries with
+ * `stopCapturing()`. y-codemirror.next does not re-export `yUndoManagerFacet`
+ * or `undoDepth` from its package root, so there is no other handle on it.
+ */
+ undoManager: Y.UndoManager;
+ destroy: () => void;
+}
+
+export function mountSourceUndoEditor(opts: {
+ ytext: Y.Text;
+ awareness: Awareness;
+ wiring: SourceUndoWiring;
+ parent: HTMLElement;
+}): MountedSourceUndoEditor {
+ const undoManager = new Y.UndoManager(opts.ytext);
+ const undoWiring =
+ opts.wiring === 'production'
+ ? [
+ sourceModeSetup,
+ yCollab(opts.ytext, opts.awareness, { undoManager }),
+ keymap.of(yUndoManagerKeymap),
+ ]
+ : [basicSetup, yCollab(opts.ytext, opts.awareness, { undoManager })];
+ const view = new EditorView({
+ state: EditorState.create({ doc: opts.ytext.toString(), extensions: undoWiring }),
+ parent: opts.parent,
+ });
+ return { view, undoManager, destroy: () => view.destroy() };
+}
+
+/**
+ * Type at a position via a real CodeMirror transaction — routes through
+ * y-codemirror's sync plugin into Y.Text under the local (tracked) origin,
+ * exactly as a keystroke does. Appends at the document end by default.
+ */
+export function typeInSource(view: EditorView, text: string, at?: number): void {
+ const pos = at ?? view.state.doc.length;
+ view.dispatch({
+ changes: { from: pos, insert: text },
+ selection: { anchor: pos + text.length },
+ userEvent: 'input.type',
+ });
+}
+
+/**
+ * Apply a remote peer / agent write to `local`'s Y.Text('source') the way a
+ * provider does: replicate to a detached doc, mutate there, apply the diff back
+ * under a non-binding origin. The source editor's sync plugin reflects it into
+ * the buffer; the origin sits outside the Y.UndoManager's tracked set, so a
+ * correct source-mode undo can never revert it.
+ */
+export function applyRemoteSourceEdit(local: Y.Doc, mutate: (ytext: Y.Text) => void): void {
+ const remote = new Y.Doc();
+ Y.applyUpdate(remote, Y.encodeStateAsUpdate(local));
+ remote.transact(() => mutate(remote.getText('source')));
+ const diff = Y.encodeStateAsUpdate(remote, Y.encodeStateVector(local));
+ Y.applyUpdate(local, diff, REMOTE_PROVIDER_ORIGIN);
+ remote.destroy();
+}
+
+/**
+ * Invoke the undo command the source-mode keymap binds to Mod-z: in production
+ * the y-codemirror Y.UndoManager undo; in legacy CodeMirror's native history.
+ */
+export function runSourceUndo(view: EditorView, wiring: SourceUndoWiring): boolean {
+ if (wiring === 'production') {
+ const binding = yUndoManagerKeymap.find((b) => b.key === 'Mod-z');
+ return binding?.run?.(view) ?? false;
+ }
+ return cmNativeUndo(view);
+}
diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.ts
index d6be09e83..a79b8cae3 100644
--- a/packages/app/tests/integration/test-harness.ts
+++ b/packages/app/tests/integration/test-harness.ts
@@ -390,6 +390,8 @@ export interface TestClient {
pauseSync: () => void;
/** Resume inbound CRDT sync, draining queued messages. Only available when syncControl: true. */
resumeSync: () => void;
+ /** Drop (discard) outbound frames while enabled. Only available when syncControl: true. */
+ setDropOutbound: (drop: boolean) => void;
}
export interface CreateTestClientOptions {
@@ -461,6 +463,10 @@ export async function createTestClient(
if (!controllableWs) throw new Error('resumeSync requires syncControl: true');
controllableWs.resumeInbound();
},
+ setDropOutbound: (drop: boolean) => {
+ if (!controllableWs) throw new Error('setDropOutbound requires syncControl: true');
+ controllableWs.setDropOutbound(drop);
+ },
cleanup: async () => {
watcherDetach?.();
observerCleanup();
diff --git a/packages/app/tests/integration/undo-after-rollback.test.ts b/packages/app/tests/integration/undo-after-rollback.test.ts
new file mode 100644
index 000000000..f051dcd70
--- /dev/null
+++ b/packages/app/tests/integration/undo-after-rollback.test.ts
@@ -0,0 +1,119 @@
+/**
+ * CONTRACT — client UndoManager behavior when a timeline restore/rollback lands.
+ *
+ * Pins the ratified undo topology: a server rollback reaches the client as a
+ * remote paired write. Production rollback is `replaceRawBody` (one of the
+ * three sibling bridge-intake primitives): Y.Text delete(0,len)+insert(0,md)
+ * then `updateYFragment` re-derive, all wrapped in a single
+ * `document.transact(..., ROLLBACK_ORIGIN)`. That origin's `context.origin`
+ * is `'rollback-apply'` — NOT `ySyncPluginKey` — so the client fragment-space
+ * `Y.UndoManager` (trackedOrigins {ySyncPluginKey}) sees it as an untracked,
+ * remote-shaped transaction. Consequence: the rollback is not Cmd+Z-undoable,
+ * and a pre-rollback stack item cannot recover the content the rollback
+ * discarded. This is deliberate (precedent #38; the choice is documented at
+ * the `handleRollback` catch region in `api-extension.ts`).
+ *
+ * A behavior flip here is an undo-topology regression to investigate, not a
+ * test to silently re-baseline.
+ *
+ */
+
+import { ROLLBACK_ORIGIN } from '@inkeep/open-knowledge-server';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+
+import { replaceRawBody } from '../../../server/src/bridge-intake.ts';
+import {
+ insertLocal,
+ mountCollabEditor,
+ readUndoManager,
+} from '../../src/editor/editor-rig.test-helper';
+import { installDomGlobals } from '../../src/editor/walk-currency-test-harness';
+
+let restoreDom: (() => void) | null = null;
+beforeAll(() => {
+ restoreDom = installDomGlobals();
+}, 30_000);
+afterAll(() => {
+ restoreDom?.();
+});
+
+/**
+ * The server rollback paired write, landing on the client's ydoc through the
+ * PRODUCTION spine: `replaceRawBody` (the bridge-intake sibling primitive
+ * `handleRollback` calls) wrapped in the caller's transact under the real
+ * exported `ROLLBACK_ORIGIN`. Hand-reproducing the primitive would model the
+ * wire shape while leaving a drift in either free to go unnoticed.
+ */
+function applyRollback(ydoc: Y.Doc, targetMarkdown: string): void {
+ ydoc.transact(() => {
+ replaceRawBody(ydoc, targetMarkdown);
+ }, ROLLBACK_ORIGIN);
+}
+
+function countOccurrences(hay: string, needle: string): number {
+ let n = 0;
+ let i = hay.indexOf(needle);
+ while (i !== -1) {
+ n++;
+ i = hay.indexOf(needle, i + needle.length);
+ }
+ return n;
+}
+
+describe('client UndoManager under a timeline rollback', () => {
+ test('rollback is not undoable and a pre-rollback stack item does not recover discarded content', () => {
+ const ydoc = new Y.Doc();
+ const editor = mountCollabEditor(ydoc, []);
+ try {
+ const um = readUndoManager(editor) as Y.UndoManager;
+ expect(um).not.toBeNull();
+
+ // User types — captured on the client UM.
+ insertLocal(editor, 'USER TYPED CONTENT', 1);
+ expect(editor.state.doc.textContent).toContain('USER TYPED CONTENT');
+ const stackBefore = um.undoStack.length;
+ expect(stackBefore).toBeGreaterThan(0);
+
+ // A timeline restore lands (server → remote paired write).
+ applyRollback(ydoc, '# Rolled Back\n\nrestored body\n');
+ const captured = editor.state.doc.textContent;
+ const stackAfterRollback = um.undoStack.length;
+
+ // The rollback landed and replaced the visible content.
+ expect(captured).toContain('restored body');
+ expect(captured).not.toContain('USER TYPED CONTENT');
+ // The rollback itself was NOT captured as an undoable item: the untracked
+ // origin left the stack exactly where the user's typing put it.
+ expect(stackAfterRollback).toBe(stackBefore);
+
+ // Cmd+Z after the rollback. Every assertion below re-reads state AFTER
+ // the call — the second clause of this test's title lives here, and a
+ // snapshot taken before `undo()` cannot observe it.
+ um.undo();
+ const afterUndo = editor.state.doc.textContent;
+ // Not undoable: the restore is still what the user sees.
+ expect(afterUndo).toContain('restored body');
+ // The pre-rollback stack item did not recover the content the rollback
+ // discarded — the clause that was previously unasserted.
+ expect(afterUndo).not.toContain('USER TYPED CONTENT');
+ // Nor did it wipe the document, nor splice a second copy in.
+ expect(afterUndo.trim().length).toBeGreaterThan(0);
+ expect(countOccurrences(afterUndo, 'restored body')).toBe(1);
+ // The UM is FRAGMENT-scoped: the undo cannot have rewritten Y.Text, so
+ // the restored source bytes are untouched (Y.Text-is-truth, precedent #38).
+ expect(ydoc.getText('source').toString()).toContain('restored body');
+ expect(ydoc.getText('source').toString()).not.toContain('USER TYPED CONTENT');
+
+ // Cmd+Shift+Z. A redo of a no-op undo is itself a no-op — it must not
+ // become a back door that re-applies the discarded typing.
+ um.redo();
+ const afterRedo = editor.state.doc.textContent;
+ expect(afterRedo).toBe(afterUndo);
+ expect(afterRedo).not.toContain('USER TYPED CONTENT');
+ expect(countOccurrences(afterRedo, 'restored body')).toBe(1);
+ } finally {
+ editor.destroy();
+ }
+ });
+});
diff --git a/packages/app/tests/integration/undo-recycle-reset.test.ts b/packages/app/tests/integration/undo-recycle-reset.test.ts
new file mode 100644
index 000000000..cf41a68ac
--- /dev/null
+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts
@@ -0,0 +1,478 @@
+/**
+ * CONTRACT — client undo semantics across a provider-pool RECYCLE.
+ *
+ * Pins the ratified recycle-reset topology (recycle-reset is accepted per
+ * industry norm; the timeline is the durable recovery rail): on a recycle the
+ * pool destroys the provider + Y.Doc and re-opens with a FRESH Y.Doc
+ * (recycleDisconnectedEntry); the editor remounts, so yUndoPlugin's state.init
+ * re-runs into a fresh UndoManager with an EMPTY stack. Pre-recycle undo
+ * history is therefore gone, and replayed unsynced edits land under
+ * TAB_REPLAY_ORIGIN — which is not in the client UM's trackedOrigins, and lands
+ * in Y.Text outside the fragment-scoped UM — so they are never Cmd+Z-undoable.
+ * The observable shape ("Cmd+Z dead right after a recycle, then works") is
+ * undo applying only to content typed AFTER the recycle. Content itself
+ * survives (the server rebuilds from disk); only the undo history resets.
+ *
+ * A flip here (undo-history preservation across recycle) is an undo-topology
+ * change to re-ratify, not a test to silently re-baseline.
+ *
+ * Fidelity: this drives the REAL server-instance-mismatch recycle end to end —
+ * createRestartableServer + ProviderPool + killAndRestartOnSamePort → real auth
+ * rejection → real handleServerInstanceMismatch (buffer → clearData →
+ * recycleAllEntries) → real buffer replay on the fresh provider's first
+ * `synced`. The editor is a real Collaboration-bound editor over
+ * provider.document — the same binding production uses. The production
+ * editor-cache eviction + React remount is emulated by a pool.onEvict editor
+ * destroy() plus a fresh mountCollabEditor after the recycled provider syncs
+ * (production also mounts after the sync promise resolves, i.e. after replay
+ * ran). The clean-disconnect debounce trigger is pushed out of the window via
+ * recycleDebounceMs so the trigger under test is unambiguous; it converges on
+ * the same recycleDisconnectedEntry spine. Collaboration's restore wrapper
+ * neutralizes the upstream y-prosemirror #114 lifecycle bug on the SAME editor,
+ * so any deadness here is the recycle boundary, not #114.
+ *
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import type { Editor } from '@tiptap/core';
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+
+import {
+ insertLocal,
+ mountCollabEditor,
+ readUndoManager,
+} from '../../src/editor/editor-rig.test-helper';
+import { ProviderPool, TAB_REPLAY_ORIGIN } from '../../src/editor/provider-pool';
+import { installDomGlobals } from '../../src/editor/walk-currency-test-harness';
+import {
+ awaitDocQuiescence,
+ createRestartableServer,
+ pollUntil,
+ readTestDoc,
+ seedPoolServerInstanceId,
+} from './test-harness';
+
+const BASE_MD = '# Recycle Probe\n\nbase paragraph anchor\n';
+const DOC = 'test-doc';
+
+let restoreDom: (() => void) | null = null;
+beforeAll(() => {
+ // Node's undici WebSocket (the pool transport in this probe) constructs
+ // its 'open'/'message' events from the GLOBAL `Event` at dispatch time,
+ // and node's EventTarget brand-check rejects jsdom's cross-realm Event.
+ // installDomGlobals() overrides Event/CustomEvent for the editor rig —
+ // restore node's originals so the real WS transport keeps working
+ // (ProseMirror's headless dispatch path never constructs global Events).
+ const nodeEvent = globalThis.Event;
+ const nodeCustomEvent = globalThis.CustomEvent;
+ restoreDom = installDomGlobals();
+ Object.defineProperty(globalThis, 'Event', {
+ value: nodeEvent,
+ configurable: true,
+ writable: true,
+ });
+ Object.defineProperty(globalThis, 'CustomEvent', {
+ value: nodeCustomEvent,
+ configurable: true,
+ writable: true,
+ });
+}, 30_000);
+afterAll(() => {
+ restoreDom?.();
+});
+
+const cleanups: Array<() => Promise<void> | void> = [];
+afterEach(async () => {
+ while (cleanups.length > 0) {
+ await cleanups.pop()?.();
+ }
+});
+
+/** Structured-recovery-event capture: ProviderPool emits its recovery
+ * telemetry via `console.warn(JSON.stringify({event, ...}))`. Recording them
+ * gives measured proof of which recycle/replay branch actually ran. */
+function captureStructuredWarns(): {
+ events: Array<Record<string, unknown>>;
+ names: () => string[];
+} {
+ const original = console.warn;
+ const events: Array<Record<string, unknown>> = [];
+ console.warn = (...args: unknown[]): void => {
+ const first = args[0];
+ if (typeof first === 'string') {
+ try {
+ const parsed: unknown = JSON.parse(first);
+ if (parsed !== null && typeof parsed === 'object' && 'event' in parsed) {
+ events.push(parsed as Record<string, unknown>);
+ }
+ } catch {
+ /* not a structured event */
+ }
+ }
+ original.apply(console, args as Parameters<typeof console.warn>);
+ };
+ cleanups.push(() => {
+ console.warn = original;
+ });
+ return { events, names: () => events.map((e) => String(e.event)) };
+}
+
+interface Rig {
+ srv: { handle: Awaited<ReturnType<typeof createRestartableServer>> };
+ pool: ProviderPool;
+ editor: Editor;
+ um: Y.UndoManager;
+ events: Array<Record<string, unknown>>;
+ eventNames: () => string[];
+ /** Origins of every update applied to the post-recycle fresh Y.Doc. */
+ freshDocUpdateOrigins: unknown[];
+ /** docNames evicted (destroyEntry → fireEvict) — recycle proof. */
+ evictedDocNames: string[];
+}
+
+/**
+ * Boot server + pool + a real Collaboration editor on the pool provider's
+ * Y.Doc, synced on BASE_MD. Wires the production-shaped eviction hook:
+ * on evict, destroy the bound editor (editor-cache analog) and attach an
+ * update-origin probe to the fresh entry's Y.Doc via queueMicrotask —
+ * recycleDisconnectedEntry runs destroy→reopen synchronously, so the
+ * microtask sees the fresh doc before any WS I/O can deliver updates.
+ */
+async function bootRig(): Promise<Rig> {
+ const { events, names } = captureStructuredWarns();
+ const handle = await createRestartableServer();
+ const srv = { handle };
+ cleanups.push(() => srv.handle.shutdown());
+ writeFileSync(join(srv.handle.contentDir, `${DOC}.md`), BASE_MD, 'utf-8');
+ await wait(250); // file-watcher pickup (T14 precedent)
+
+ const pool = new ProviderPool(3, `ws://127.0.0.1:${srv.handle.port}/collab`, {
+ // Pin the recycle trigger under test to `server-instance-mismatch`
+ // (§2e trigger 2). The clean-disconnect 4s debounce (trigger 1) would
+ // otherwise race the reconnect across our restart window; both
+ // triggers converge on recycleDisconnectedEntry anyway.
+ recycleDebounceMs: 60_000,
+ });
+ cleanups.push(() => pool.dispose());
+ // Production boot shape: client claims the live serverInstanceId in its
+ // auth token; after a restart the claim is stale → mismatch fires.
+ await seedPoolServerInstanceId(srv.handle, pool);
+
+ pool.open(DOC);
+ pool.setActive(DOC);
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);
+
+ const entry = pool.getActive();
+ if (!entry || entry.kind !== 'active') throw new Error('no active entry after sync');
+
+ // Production binding shape (TiptapEditor.tsx:331): Collaboration over
+ // provider.document. Mounted after first sync, as production does
+ // (Suspense gates the editor mount on the syncPromise).
+ const editor = mountCollabEditor(entry.provider.document, []);
+ const live = { editor, destroyed: false };
+ cleanups.push(() => {
+ if (!live.destroyed) live.editor.destroy();
+ });
+ const um = readUndoManager(editor);
+ if (!um) throw new Error('no UndoManager on collab editor');
+
+ const freshDocUpdateOrigins: unknown[] = [];
+ const evictedDocNames: string[] = [];
+ pool.onEvict((docName) => {
+ evictedDocNames.push(docName);
+ // editor-cache analog: destroy the editor bound to the evicted doc
+ // BEFORE provider.destroy() tears the Y.Doc down.
+ if (docName === DOC && !live.destroyed) {
+ live.editor.destroy();
+ live.destroyed = true;
+ }
+ queueMicrotask(() => {
+ const fresh = pool.getActive();
+ if (fresh && fresh.kind === 'active' && fresh.provider.document !== entry.provider.document) {
+ fresh.provider.document.on('update', (_update: Uint8Array, origin: unknown) => {
+ freshDocUpdateOrigins.push(origin);
+ });
+ }
+ });
+ });
+
+ return {
+ srv,
+ pool,
+ editor,
+ um,
+ events,
+ eventNames: names,
+ freshDocUpdateOrigins,
+ evictedDocNames,
+ };
+}
+
+/**
+ * ClientIDs whose local clock is AHEAD of the recycle baseline — i.e. work the
+ * baseline does not cover and the recycle therefore has to carry.
+ *
+ * Compared as state vectors, deliberately not as `encodeStateAsUpdate` byte
+ * length: an update always carries the doc's full delete set, so a doc with any
+ * deletion in it never encodes down to an empty envelope even when the baseline
+ * already covers every struct. Byte length would read "unacked" forever and the
+ * gate below would never bite.
+ *
+ * The baseline is the one `replayBufferedContent` computes against:
+ * `lastDiskAckedSV`, falling back to `lastServerSyncedSV`.
+ */
+function unackedClientsAtBaseline(entry: {
+ lastDiskAckedSV: Uint8Array | null;
+ lastServerSyncedSV: Uint8Array | null;
+ provider: { document: Y.Doc };
+}): number[] {
+ const baseline = entry.lastDiskAckedSV ?? entry.lastServerSyncedSV;
+ if (!baseline) return [...Y.encodeStateVector(entry.provider.document).keys()];
+ const acked = Y.decodeStateVector(baseline);
+ const live = Y.decodeStateVector(Y.encodeStateVector(entry.provider.document));
+ const ahead: number[] = [];
+ for (const [client, clock] of live) {
+ if ((acked.get(client) ?? 0) < clock) ahead.push(client);
+ }
+ return ahead;
+}
+
+/**
+ * Type + propagate: fragment → server Observer A → Y.Text → L1 disk flush, then
+ * doc quiescence + unsyncedChanges drained. On return the edit is DURABLE — it
+ * is on disk and fully sent — and both facts are asserted here rather than
+ * timed.
+ *
+ * It is NOT acknowledged into the recycle baseline, and this helper does not
+ * try to make it so. `lastServerSyncedSV` refreshes only on a provider `synced`
+ * event, which does not re-fire for a local edit, so no amount of waiting moves
+ * an edit into it; `lastDiskAckedSV` advances on disk-ack but lags the doc's
+ * current state. An earlier version of this comment claimed the opposite —
+ * "leaves the edit ACKED in lastServerSyncedSV" — and asserting that claim
+ * times out. The unacked window is the state the recycle exists to survive, so
+ * `restartAndAwaitRecycledSync` pins it at the moment it matters.
+ */
+async function typeAndPropagate(rig: Rig, text: string): Promise<void> {
+ insertLocal(rig.editor, text, 1);
+ const entry = rig.pool.getActive();
+ if (!entry) throw new Error('no active entry');
+ await pollUntil(() => readTestDoc(rig.srv.handle.contentDir, DOC).includes(text), 10_000, 100);
+ await awaitDocQuiescence(entry.provider.document, { timeoutMs: 5_000 });
+ await pollUntil(() => entry.provider.unsyncedChanges === 0, 10_000, 50);
+ expect(readTestDoc(rig.srv.handle.contentDir, DOC)).toContain(text);
+ expect(entry.provider.unsyncedChanges).toBe(0);
+}
+
+/** Kill network, optionally run `whileDown`, restart on the same port (new
+ * ServerInstance ⇒ new serverInstanceId ⇒ stale auth claim ⇒ REAL
+ * `server-instance-mismatch` recycle), then wait for the recycled entry —
+ * a NEW provider + NEW Y.Doc — to sync. Returns the fresh entry. */
+async function restartAndAwaitRecycledSync(
+ rig: Rig,
+ whileDown?: () => void,
+): Promise<{ provider: { document: Y.Doc; isSynced: boolean } }> {
+ const before = rig.pool.getActive();
+ if (!before || before.kind !== 'active') throw new Error('no active entry pre-restart');
+ const providerBefore = before.provider;
+
+ rig.srv.handle.killNetwork();
+ // Let the provider observe the transport close before editing offline.
+ await pollUntil(() => rig.pool.getActive()?.syncState === 'disconnected', 5_000, 25);
+ whileDown?.();
+
+ // SCENARIO GATE — the recycle must be BUFFER-CARRIED, not disk-carried.
+ //
+ // The durability claim this suite defends is that work the server has not
+ // acknowledged survives a recycle; the RAM buffer and the durable outbox are
+ // the carriers for exactly that window. If the staging ever drifts so the
+ // recycle baseline already covers the doc, the restart rebuild alone restores
+ // everything, nothing is carried, and every assertion downstream still passes
+ // — the suite would silently downgrade to the easy case. Fail loudly instead.
+ const unackedClients = unackedClientsAtBaseline(before);
+ expect(
+ unackedClients.length,
+ 'recycle staging drifted to the ACKED/disk-carried case: the baseline already covers the doc, so neither the replay buffer nor the durable outbox carries anything and this suite is no longer testing the unacked window',
+ ).toBeGreaterThan(0);
+
+ rig.srv.handle = await rig.srv.handle.killAndRestartOnSamePort({ downtimeMs: 400 });
+
+ await pollUntil(
+ () => {
+ const e = rig.pool.getActive();
+ return e?.kind === 'active' && e.provider !== providerBefore && e.provider.isSynced === true;
+ },
+ 20_000,
+ 50,
+ );
+ const fresh = rig.pool.getActive();
+ if (!fresh || fresh.kind !== 'active') throw new Error('no recycled entry');
+ if (fresh.provider.document === providerBefore.document) {
+ throw new Error('expected a FRESH Y.Doc after recycle');
+ }
+ return fresh;
+}
+
+describe('client undo across a provider-pool recycle', () => {
+ test('baseline (no recycle): typing is captured and undo reverts it', async () => {
+ const rig = await bootRig();
+
+ insertLocal(rig.editor, 'M1-TYPED-MARKER', 1);
+ expect(rig.editor.state.doc.textContent).toContain('M1-TYPED-MARKER');
+ expect(rig.um.undoStack.length).toBeGreaterThan(0);
+
+ const popped = rig.um.undo();
+ expect(popped).not.toBeNull();
+ // The typed content is reverted; base content is untouched.
+ expect(rig.editor.state.doc.textContent).not.toContain('M1-TYPED-MARKER');
+ expect(rig.editor.state.doc.textContent).toContain('base paragraph anchor');
+ }, 30_000);
+
+ test('after a recycle, the fresh UndoManager starts empty and undo is a no-op', async () => {
+ const rig = await bootRig();
+
+ await typeAndPropagate(rig, 'M2-PRE-RECYCLE-TYPED ');
+ const umA = rig.um;
+ const stackBeforeRecycle = umA.undoStack.length;
+ expect(stackBeforeRecycle).toBeGreaterThan(0);
+
+ const fresh = await restartAndAwaitRecycledSync(rig);
+
+ // Production remount: fresh editor over the fresh provider.document,
+ // mounted after the recycled provider synced.
+ const editorB = mountCollabEditor(fresh.provider.document, []);
+ cleanups.push(() => editorB.destroy());
+ const umB = readUndoManager(editorB);
+ if (!umB) throw new Error('no UM on post-recycle editor');
+
+ const textAfterRecycle = editorB.state.doc.textContent;
+ const stackAfterRecycle = umB.undoStack.length;
+ const redoAfterRecycle = umB.redoStack.length;
+ const popped = umB.undo();
+ const textAfterUndo = editorB.state.doc.textContent;
+
+ // The recycle ran via the real mismatch path.
+ expect(rig.eventNames()).toContain('ok-client-cache-epoch-mismatch');
+ expect(rig.evictedDocNames).toContain(DOC);
+ // Content survived (server rebuilt from disk, which had the edit)…
+ expect(textAfterRecycle).toContain('M2-PRE-RECYCLE-TYPED');
+ expect(textAfterRecycle).toContain('base paragraph anchor');
+ // …but the undo history did NOT: fresh manager, empty stacks.
+ expect(umB).not.toBe(umA);
+ expect(stackAfterRecycle).toBe(0);
+ expect(redoAfterRecycle).toBe(0);
+ // Cmd+Z immediately after the recycle does nothing.
+ expect(popped).toBeNull();
+ expect(textAfterUndo).toBe(textAfterRecycle);
+ }, 30_000);
+
+ test('a replayed unsynced edit lands under TAB_REPLAY_ORIGIN and is not undoable', async () => {
+ const rig = await bootRig();
+ const umA = rig.um;
+ const stackBeforeOffline = umA.undoStack.length;
+
+ // Offline WYSIWYG edit: lands in the FRAGMENT only (server Observer A
+ // is unreachable, so Y.Text never receives it — the un-drained edit
+ // shape replayBufferedContent's `ytextClean && !fragClean` branch
+ // recovers).
+ let stackAfterOfflineType = -1;
+ const fresh = await restartAndAwaitRecycledSync(rig, () => {
+ insertLocal(rig.editor, 'M3-UNSYNCED-EDIT ', 1);
+ stackAfterOfflineType = umA.undoStack.length;
+ });
+
+ // Give the replay + its post-splice sync a beat, then measure.
+ const freshDoc = fresh.provider.document;
+ await pollUntil(
+ () => freshDoc.getText('source').toString().includes('M3-UNSYNCED-EDIT'),
+ 10_000,
+ 50,
+ );
+ const ytextHasEdit = freshDoc.getText('source').toString().includes('M3-UNSYNCED-EDIT');
+ const replayOriginSeen = rig.freshDocUpdateOrigins.some((o) => o === TAB_REPLAY_ORIGIN);
+
+ // Production remount timing: editor mounts after the recycled provider
+ // synced — the replay (first-`synced` listener) has already run.
+ const editorB = mountCollabEditor(freshDoc, []);
+ cleanups.push(() => editorB.destroy());
+ const umB = readUndoManager(editorB);
+ if (!umB) throw new Error('no UM on post-recycle editor');
+
+ const stackAtMount = umB.undoStack.length;
+
+ // The replay wrote Y.TEXT; the editor renders the FRAGMENT. The edit
+ // becomes visible only after the real server Observer B derives the
+ // fragment from Y.Text and syncs it back as a remote update.
+ let editorShowsEditAfterRoundTrip = false;
+ try {
+ await pollUntil(
+ () => editorB.state.doc.textContent.includes('M3-UNSYNCED-EDIT'),
+ 10_000,
+ 100,
+ );
+ editorShowsEditAfterRoundTrip = true;
+ } catch {
+ editorShowsEditAfterRoundTrip = false;
+ }
+ const stackAfterRoundTrip = umB.undoStack.length;
+ const popped = umB.undo();
+ const editStillPresentAfterUndo = editorB.state.doc.textContent.includes('M3-UNSYNCED-EDIT');
+
+ // Pre-recycle: the offline WYSIWYG edit WAS captured by the old UM.
+ expect(stackAfterOfflineType).toBeGreaterThan(stackBeforeOffline);
+ // The real mismatch recycle + content-level replay ran.
+ expect(rig.eventNames()).toContain('ok-client-cache-epoch-mismatch');
+ expect(rig.eventNames()).toContain('ok-buffer-replay-content-applied');
+ // Replayed bytes DID land (in Y.Text), under the real TAB_REPLAY_ORIGIN.
+ expect(ytextHasEdit).toBe(true);
+ expect(replayOriginSeen).toBe(true);
+ // The fresh UM captured NONE of it — not at mount, not after the
+ // Observer-B fragment round-trip (remote origin ∉ trackedOrigins).
+ expect(stackAtMount).toBe(0);
+ expect(editorShowsEditAfterRoundTrip).toBe(true);
+ expect(stackAfterRoundTrip).toBe(0);
+ // Cmd+Z cannot undo the replayed edit.
+ expect(popped).toBeNull();
+ expect(editStillPresentAfterUndo).toBe(true);
+ }, 30_000);
+
+ test('after a recycle, undo works only for content typed after the recycle', async () => {
+ const rig = await bootRig();
+ await typeAndPropagate(rig, 'M4-PRE-RECYCLE-TYPED ');
+
+ const fresh = await restartAndAwaitRecycledSync(rig);
+ const editorB = mountCollabEditor(fresh.provider.document, []);
+ cleanups.push(() => editorB.destroy());
+ const umB = readUndoManager(editorB);
+ if (!umB) throw new Error('no UM on post-recycle editor');
+
+ // Try #1 (immediately after recycle): dead.
+ const try1 = umB.undo();
+ const textAfterTry1 = editorB.state.doc.textContent;
+
+ // User keeps working: NEW content accumulates on the fresh stack.
+ insertLocal(editorB, 'M4-POST-RECYCLE-NEW ', 1);
+ const stackAfterNewTyping = umB.undoStack.length;
+
+ // Try #2: works — but only for the NEW content.
+ const try2 = umB.undo();
+ const textAfterTry2 = editorB.state.doc.textContent;
+
+ // Try #3: dead again — the recycle boundary is a hard floor; undo can
+ // never reach pre-recycle content.
+ const try3 = umB.undo();
+ const textAfterTry3 = editorB.state.doc.textContent;
+
+ expect(try1).toBeNull();
+ expect(textAfterTry1).toContain('M4-PRE-RECYCLE-TYPED');
+ expect(stackAfterNewTyping).toBeGreaterThan(0);
+ expect(try2).not.toBeNull();
+ expect(textAfterTry2).not.toContain('M4-POST-RECYCLE-NEW');
+ expect(textAfterTry2).toContain('M4-PRE-RECYCLE-TYPED');
+ expect(try3).toBeNull();
+ expect(textAfterTry3).toContain('M4-PRE-RECYCLE-TYPED');
+ expect(textAfterTry3).toContain('base paragraph anchor');
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/undo-rederive-survival.test.ts b/packages/app/tests/integration/undo-rederive-survival.test.ts
new file mode 100644
index 000000000..532172048
--- /dev/null
+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts
@@ -0,0 +1,231 @@
+/**
+ * CONTRACT — client WYSIWYG undo survives editor plugin churn, and the
+ * derive-from-Y.Text primitive reports the un-propagated fragment content its
+ * rebuild discards.
+ *
+ * Two pins:
+ *
+ * 1. Plugin-churn undo survival. The upstream y-prosemirror plugin-lifecycle
+ * bug (UndoManager destroyed on plugin reconfigure) IS present in the
+ * pinned y-tiptap dist: yUndoPlugin's state.init mints the UndoManager
+ * once; the plugin view's destroy() calls undoManager.destroy();
+ * EditorState.reconfigure reuses the existing plugin field, so init never
+ * re-runs and the manager is never re-minted. TipTap's Collaboration
+ * extension neutralizes it — its addProseMirrorPlugins wraps the plugin
+ * view so destroy() snapshots trackedOrigins + observers into
+ * undoManager.restore, and the next view creation re-attaches the doc
+ * afterTransaction capture handler. OK relies on this (the
+ * ok/cache/undo-manager-read-failed guard in editor-cache). Production
+ * hits this reconfigure on every mount: a deferred registerPlugin for the
+ * agent-write flash, unregistered on cleanup. Contract: undo stays alive
+ * across registerPlugin / unregisterPlugin driven through the PUBLIC
+ * editor interface.
+ *
+ * 2. Derive-from-Y.Text loss DETECTION. The production
+ * `deriveFragmentFromYtext` (imported, not reproduced) rebuilds the
+ * fragment from Y.Text's bytes, so a WYSIWYG keystroke still living only
+ * in the fragment is discarded by the rebuild. The contract this pins is
+ * NOT that the stomp happens — pinning the bug leaves the test green if
+ * the bug is fixed — but that the primitive's `detect` branch OBSERVES it:
+ * the reporter names the discarded line and hands back a restore payload
+ * that still carries it. That branch is the loss detection this program
+ * adds, and a reproduced copy of the derive body structurally cannot see it.
+ *
+ * A flip in pin 1 (undo dies on plugin churn) is an undo-topology regression.
+ *
+ */
+
+import { prependFrontmatter } from '@inkeep/open-knowledge-core';
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+
+import { deriveFragmentFromYtext } from '../../../server/src/bridge-intake.ts';
+import type { DeriveLossObservation } from '../../../server/src/bridge-loss-detector.ts';
+import { detectPairedIntakeLoss } from '../../../server/src/bridge-loss-detector.ts';
+import {
+ insertLocal,
+ mountCollabEditor,
+ readUndoManager,
+} from '../../src/editor/editor-rig.test-helper';
+import { installDomGlobals } from '../../src/editor/walk-currency-test-harness';
+import { mdManager, schema } from './test-harness';
+
+let restoreDom: (() => void) | null = null;
+beforeAll(() => {
+ restoreDom = installDomGlobals();
+}, 30_000);
+afterAll(() => {
+ restoreDom?.();
+});
+
+/** A harmless PM plugin to force a plugins-array reconfigure. */
+function makeHarmlessPlugin(name: string): Plugin {
+ return new Plugin({ key: new PluginKey(name) });
+}
+
+describe('client undo survives editor plugin churn', () => {
+ test('baseline: typing then undo reverts the edit (undo alive without any reconfigure)', () => {
+ const ydoc = new Y.Doc();
+ const editor = mountCollabEditor(ydoc, []);
+ try {
+ const um = readUndoManager(editor);
+ expect(um).not.toBeNull();
+
+ insertLocal(editor, 'hello world', 1);
+ expect(editor.state.doc.textContent).toContain('hello world');
+ expect((um as Y.UndoManager).undoStack.length).toBeGreaterThan(0);
+
+ (um as Y.UndoManager).undo();
+ expect(editor.state.doc.textContent).not.toContain('hello world');
+ } finally {
+ editor.destroy();
+ }
+ });
+
+ test('registerPlugin before the first keystroke does not kill undo', () => {
+ const ydoc = new Y.Doc();
+ const editor = mountCollabEditor(ydoc, []);
+ try {
+ const umBefore = readUndoManager(editor) as Y.UndoManager;
+ expect(umBefore).not.toBeNull();
+
+ // The doc's live afterTransaction capture handlers before the reconfigure.
+ const obs = (ydoc as unknown as { _observers: Map<string, Set<unknown>> })._observers;
+ const beforeHandlers = obs.get('afterTransaction')?.size ?? 0;
+
+ // The production trigger: a deferred registerPlugin fires right after
+ // mount, before the user has typed.
+ editor.registerPlugin(makeHarmlessPlugin('probe-flash'));
+
+ const umAfter = readUndoManager(editor) as Y.UndoManager;
+ const afterHandlers = obs.get('afterTransaction')?.size ?? 0;
+
+ insertLocal(editor, 'typed after register', 1);
+ const captured = umAfter.undoStack.length;
+ umAfter.undo();
+ const revertedByUndo = !editor.state.doc.textContent.includes('typed after register');
+
+ // state.init did NOT re-run, so the manager object is the same (the
+ // upstream lifecycle-bug surface)...
+ expect(umAfter).toBe(umBefore);
+ // ...but the capture handler was restored (destroy re-added it)...
+ expect(afterHandlers).toBe(beforeHandlers);
+ // ...so the post-reconfigure edit IS captured and undo IS alive.
+ expect(captured).toBeGreaterThan(0);
+ expect(revertedByUndo).toBe(true);
+ } finally {
+ editor.destroy();
+ }
+ });
+
+ test('register + unregister churn also preserves undo', () => {
+ const ydoc = new Y.Doc();
+ const editor = mountCollabEditor(ydoc, []);
+ try {
+ const key = new PluginKey('probe-removable');
+ editor.registerPlugin(new Plugin({ key }));
+ editor.unregisterPlugin(key);
+
+ const um = readUndoManager(editor) as Y.UndoManager;
+ insertLocal(editor, 'edit after churn', 1);
+ const captured = um.undoStack.length;
+ um.undo();
+ const reverted = !editor.state.doc.textContent.includes('edit after churn');
+ expect(captured).toBeGreaterThan(0);
+ expect(reverted).toBe(true);
+ } finally {
+ editor.destroy();
+ }
+ });
+});
+
+function applyToFragment(doc: Y.Doc, frag: Y.XmlFragment, md: string, origin?: string): void {
+ const parsed = mdManager.parse(md);
+ const pmNode = schema.nodeFromJSON(parsed);
+ doc.transact(() => {
+ updateYFragment(doc, frag, pmNode, { mapping: new Map(), isOMark: new Map() });
+ }, origin);
+}
+
+function serializeFrag(frag: Y.XmlFragment): string {
+ return mdManager.serialize(yXmlFragmentToProseMirrorRootNode(frag, schema).toJSON());
+}
+
+describe('the derive-from-Y.Text primitive reports what its rebuild discards', () => {
+ /**
+ * Stage the loss window the primitive's detector exists for: Y.Text holds an
+ * agent write, the fragment additionally holds a keystroke Observer A has not
+ * propagated yet, and the post-undo re-derive is about to rebuild over it.
+ *
+ * The undo itself is modelled with a Y.Text-scoped `Y.UndoManager` — the
+ * primitive's documented pre-state contract is "ytext already holds the
+ * post-undo bytes", and the shipped `applyAgentUndo` spine that produces them
+ * is covered at its own rung in `agent-undo.test.ts`. What is under test here
+ * is the primitive itself, imported from production.
+ *
+ */
+ test('a re-derive over an un-propagated keystroke reports it as lost with a restore payload', () => {
+ const doc = new Y.Doc();
+ const ytext = doc.getText('source');
+ const frag = doc.getXmlFragment('default');
+
+ const base = '# Doc\n\nuser paragraph\n';
+ doc.transact(() => ytext.insert(0, prependFrontmatter('', base)), 'seed');
+ applyToFragment(doc, frag, base, 'seed');
+
+ // Agent write captured under an UndoManager tracking Y.Text.
+ const um = new Y.UndoManager(ytext, {
+ trackedOrigins: new Set(['agent']),
+ captureTimeout: 0,
+ });
+ doc.transact(() => {
+ ytext.insert(ytext.toString().length, '\nagent line\n');
+ deriveFragmentFromYtext(doc);
+ }, 'agent');
+
+ // Concurrent user keystroke lands in the FRAGMENT only (Observer A debounce
+ // window: Y.Text does not yet have it).
+ applyToFragment(
+ doc,
+ frag,
+ '# Doc\n\nuser paragraph\n\nagent line\n\nfresh keystroke\n',
+ 'user',
+ );
+ expect(serializeFrag(frag)).toContain('fresh keystroke');
+ expect(ytext.toString()).not.toContain('fresh keystroke');
+
+ // Agent-undo: revert Y.Text agent items, then re-derive fragment from Y.Text
+ // WITH the detector wired — the baseline is the pre-undo Y.Text, so content
+ // the undo legitimately removed is excluded from the loss verdict.
+ const baselineFullMd = ytext.toString();
+ const observations: DeriveLossObservation[] = [];
+ um.undo();
+ doc.transact(() => {
+ deriveFragmentFromYtext(doc, undefined, {
+ baselineFullMd,
+ report: (obs) => observations.push(obs),
+ });
+ }, 'agent-undo');
+
+ // The detector ran exactly once for the one derive.
+ expect(observations).toHaveLength(1);
+ const lost = detectPairedIntakeLoss(observations[0] as DeriveLossObservation);
+
+ // It names the never-propagated keystroke...
+ expect(lost.join('\n')).toContain('fresh keystroke');
+ // ...and NOT the agent line, which the undo removed on purpose — a detector
+ // that reported every removed line would be noise, not a loss signal.
+ expect(lost.join('\n')).not.toContain('agent line');
+ // The restore payload still carries the discarded content, so the checkpoint
+ // floor built on it has something to restore.
+ expect(observations[0]?.restorePayload).toContain('fresh keystroke');
+
+ const finalFrag = serializeFrag(frag);
+ // Undo intent honored: the agent line is gone from the fragment too.
+ expect(finalFrag).not.toContain('agent line');
+ // Non-vacuity: the rebuild produced a real document, not an empty one.
+ expect(finalFrag).toContain('user paragraph');
+ });
+});
diff --git a/packages/app/tests/integration/write-surface-undo-exclusion.test.ts b/packages/app/tests/integration/write-surface-undo-exclusion.test.ts
new file mode 100644
index 000000000..b7e8f8ca5
--- /dev/null
+++ b/packages/app/tests/integration/write-surface-undo-exclusion.test.ts
@@ -0,0 +1,185 @@
+/**
+ * CONTRACT — the named write-surface origins are excluded from the editor's
+ * undo. A frontmatter form write, a markdownlint auto-fix, and a chunked
+ * source paste each stamp a distinct single-root local origin that no editor
+ * UndoManager tracks, so a user's Cmd+Z reverts the user's own keystrokes and
+ * never one of these programmatic writes.
+ *
+ * Drives a REAL CodeMirror 6 EditorView over a REAL Y.Text with the production
+ * source-mode wiring (the origin-aware y-codemirror Y.UndoManager is the only
+ * undo authority).
+ *
+ * Two things make the rows discriminating rather than a restatement of "an
+ * arbitrary object is not the tracked origin":
+ *
+ * 1. A TRACKED control row runs the identical shape with real keystrokes.
+ * Two typed frames drain under two undos, so the harness demonstrably
+ * does drain frames on a second undo — which is the only reason a
+ * write-surface row surviving that second undo means anything.
+ * 2. The lint-fix row calls the PRODUCTION `applyLintFixes`, so the origin
+ * under test is the shipped module-local constant rather than a
+ * reconstruction of it.
+ *
+ * Residual: the chunked-paste origin is reachable only behind a >500 kB
+ * HTML-conversion paste, so that row still reconstructs the shipped shape;
+ * the origin-undoability sweep pins that the real constant exists and stays
+ * classified.
+ */
+
+import type { EditorView } from '@codemirror/view';
+import { FORM_WRITE_ORIGIN } from '@inkeep/open-knowledge-core';
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+import { applyLintFixes } from '../../src/editor/apply-lint-fix';
+import { installDomGlobals } from '../../src/editor/walk-currency-test-harness';
+import {
+ installCmMeasurementStubs,
+ mountSourceUndoEditor,
+ runSourceUndo,
+ typeInSource,
+} from './source-undo-rig.test-helper';
+
+let restoreDom: (() => void) | null = null;
+beforeAll(() => {
+ restoreDom = installDomGlobals();
+ installCmMeasurementStubs();
+}, 30_000);
+afterAll(() => {
+ restoreDom?.();
+});
+
+const cleanups: Array<() => void> = [];
+afterEach(() => {
+ while (cleanups.length > 0) cleanups.pop()?.();
+});
+
+function mount(): { doc: Y.Doc; ytext: Y.Text; view: EditorView; um: Y.UndoManager } {
+ const doc = new Y.Doc();
+ const ytext = doc.getText('source');
+ const awareness = new Awareness(doc);
+ const parent = globalThis.document.createElement('div');
+ globalThis.document.body.appendChild(parent);
+ const { view, undoManager, destroy } = mountSourceUndoEditor({
+ ytext,
+ awareness,
+ wiring: 'production',
+ parent,
+ });
+ cleanups.push(() => {
+ destroy();
+ parent.remove();
+ awareness.destroy();
+ doc.destroy();
+ });
+ return { doc, ytext, view, um: undoManager };
+}
+
+/** The shipped single-root local write shape (`source: 'local'`, not paired). */
+function reconstructLocalOrigin(originLabel: string): unknown {
+ return Object.freeze({
+ source: 'local' as const,
+ skipStoreHooks: false,
+ context: Object.freeze({ origin: originLabel }),
+ });
+}
+
+interface WriteSurfaceCase {
+ name: string;
+ /** Perform the programmatic write that must never become an undoable frame. */
+ write: (doc: Y.Doc, ytext: Y.Text) => void;
+}
+
+const CASES: WriteSurfaceCase[] = [
+ {
+ name: 'frontmatter form-write',
+ write: (doc, ytext) => {
+ doc.transact(() => ytext.insert(0, 'SURVIVES\n'), FORM_WRITE_ORIGIN);
+ },
+ },
+ {
+ // The PRODUCTION entry point. `applyLintFixes` stamps its own module-local
+ // `LINT_FIX_ORIGIN` internally, so nothing about the origin is modelled
+ // here — a change to that constant's shape lands in this row.
+ name: 'markdownlint auto-fix',
+ write: (doc, ytext) => {
+ doc.transact(() => ytext.insert(0, 'SURVIVES \n'), 'seed-with-trailing-spaces');
+ const applied = applyLintFixes({ document: doc }, [
+ {
+ range: { start: { line: 0, character: 8 }, end: { line: 0, character: 10 } },
+ newText: '',
+ },
+ ]);
+ expect(applied).toBe(true);
+ },
+ },
+ {
+ name: 'chunked source paste',
+ write: (doc, ytext) => {
+ doc.transact(() => ytext.insert(0, 'SURVIVES\n'), reconstructLocalOrigin('source-paste'));
+ },
+ },
+];
+
+describe('write-surface origins are excluded from source-mode undo', () => {
+ /**
+ * The control. Without it, every row below is satisfied by ANY origin the
+ * UndoManager does not track — including `{}` — because nothing shows the
+ * second undo is capable of draining a frame in the first place.
+ *
+ */
+ test('control: two tracked keystroke frames DO drain under two undos', () => {
+ const { view, ytext, um } = mount();
+
+ typeInSource(view, 'first');
+ // y-codemirror's UndoManager coalesces edits inside one capture window;
+ // `stopCapturing` is what makes these two SEPARATE frames.
+ um.stopCapturing();
+ typeInSource(view, '-second', ytext.length);
+ expect(ytext.toString()).toBe('first-second');
+ expect(um.undoStack.length).toBe(2);
+
+ expect(runSourceUndo(view, 'production')).toBe(true);
+ expect(ytext.toString()).toBe('first');
+ expect(um.undoStack.length).toBe(1);
+
+ // The second undo drains a further frame — the discriminator every row
+ // below relies on.
+ expect(runSourceUndo(view, 'production')).toBe(true);
+ expect(ytext.toString()).toBe('');
+ expect(um.undoStack.length).toBe(0);
+ });
+
+ for (const testCase of CASES) {
+ test(`a ${testCase.name} survives repeated source-mode undo`, () => {
+ const { doc, ytext, view, um } = mount();
+
+ // A programmatic write under the write-surface origin — never a keystroke.
+ testCase.write(doc, ytext);
+ const programmatic = ytext.toString();
+ expect(programmatic).toBe('SURVIVES\n');
+ expect(view.state.doc.toString()).toBe(programmatic);
+ // The direct oracle: the write produced NO undoable frame at all.
+ expect(um.undoStack.length).toBe(0);
+
+ // A real user keystroke — routed under the tracked local sync origin.
+ um.stopCapturing();
+ typeInSource(view, 'typed', ytext.length);
+ expect(ytext.toString()).toBe(`${programmatic}typed`);
+ // Exactly one frame: the keystroke's. Were the write-surface origin
+ // tracked, the stopCapturing boundary above would have left two.
+ expect(um.undoStack.length).toBe(1);
+
+ // First undo reverts the keystroke; the write-surface content stays.
+ expect(runSourceUndo(view, 'production')).toBe(true);
+ expect(ytext.toString()).toBe(programmatic);
+ expect(um.undoStack.length).toBe(0);
+
+ // A second undo cannot touch the write-surface content — it never became
+ // an undoable frame. The control above proves a second undo WOULD drain a
+ // tracked frame, so surviving it is a fact about the origin.
+ runSourceUndo(view, 'production');
+ expect(ytext.toString()).toBe(programmatic);
+ });
+ }
+});
diff --git a/packages/app/tests/stress/file-tree-create.e2e.ts b/packages/app/tests/stress/file-tree-create.e2e.ts
index 5031140c4..bff0670ea 100644
--- a/packages/app/tests/stress/file-tree-create.e2e.ts
+++ b/packages/app/tests/stress/file-tree-create.e2e.ts
@@ -253,6 +253,7 @@ async function installDelayedDesktopSessionBridge(
editor: {
notifyActiveTargetChanged: () => {},
notifyViewMenuStateChanged: () => {},
+ notifyBackgroundThrottle: () => {},
},
sidebar: {
expandAll: () => unsubscribe,
diff --git a/packages/app/tests/stress/fixtures/handoff-mocks.ts b/packages/app/tests/stress/fixtures/handoff-mocks.ts
index 18df4245c..6fcbb753c 100644
--- a/packages/app/tests/stress/fixtures/handoff-mocks.ts
+++ b/packages/app/tests/stress/fixtures/handoff-mocks.ts
@@ -591,6 +591,7 @@ export async function installHandoffMocks(page: Page, cfg: HandoffMockConfig): P
editor: {
notifyActiveTargetChanged: (): void => {},
notifyViewMenuStateChanged: (): void => {},
+ notifyBackgroundThrottle: (): void => {},
},
startup: {
reportMarks: (): void => {},
diff --git a/packages/app/tests/stress/source-mode-undo-keymap.e2e.ts b/packages/app/tests/stress/source-mode-undo-keymap.e2e.ts
new file mode 100644
index 000000000..619dd0d2c
--- /dev/null
+++ b/packages/app/tests/stress/source-mode-undo-keymap.e2e.ts
@@ -0,0 +1,69 @@
+/**
+ * Source-mode undo keymap — real browser end to end.
+ *
+ * The source editor's only undo authority is the origin-aware y-codemirror
+ * 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.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { Page } from '@playwright/test';
+import { expect, test, waitForActiveProviderSynced as waitForProvider } from './_helpers';
+
+const SENTINEL = 'undo-me-sentinel-xyz';
+
+/**
+ * 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.
+ */
+const REDO_CHORD = process.platform === 'darwin' ? 'Meta+Shift+z' : 'Control+y';
+
+/** 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() ?? '');
+}
+
+test.describe('source-mode undo keymap', () => {
+ let docName: string;
+
+ test.beforeEach(async ({ page, api }) => {
+ docName = `test-source-undo-${randomUUID().slice(0, 8)}`;
+ await api.createPage(`${docName}.md`);
+ await page.goto(`/#/${docName}`);
+ await waitForProvider(page);
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ await page.getByRole('radio', { name: 'Markdown source' }).click();
+ await page.waitForSelector('.cm-content', { timeout: 10_000 });
+ });
+
+ test('Mod-z in source mode reverts the user typing via the origin-aware undo', 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);
+ });
+
+ 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);
+
+ 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);
+ });
+});
diff --git a/packages/app/tests/stress/timeline-recovered-restore.e2e.ts b/packages/app/tests/stress/timeline-recovered-restore.e2e.ts
new file mode 100644
index 000000000..f8f88f6a6
--- /dev/null
+++ b/packages/app/tests/stress/timeline-recovered-restore.e2e.ts
@@ -0,0 +1,97 @@
+/**
+ * Timeline recovered-content restore — real-browser click-restore journey.
+ *
+ * A silent rescue checkpoint (the observer bridge writes these on a content-loss
+ * event) must surface in the Timeline as an ordinary "Recovered content" version
+ * and restore its content into the live editor through the same
+ * `POST /api/rollback` spine as any older version. This is the browser-tier
+ * proof of the timeline recovery floor: the recovered content actually lands in
+ * the ProseMirror editor over a real WebSocket + real shadow-git rollback — the
+ * fidelity no jsdom mount reaches. The confirm-dialog gating and the rollback
+ * request shape are pinned deterministically in `TimelinePanel.dom.test.tsx`;
+ * commit timing decides whether this journey hits the instant or the confirmed
+ * restore path, so it handles both.
+ *
+ * Requires: Playwright browsers installed. Per-worker dev server (git enabled
+ * via `OK_TEST_GIT_ENABLED=1`) from the `workerServer` fixture.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { resolveShadowDir } from '@inkeep/open-knowledge-core/shadow-repo-layout';
+import { saveInMemoryCheckpoint } from '@inkeep/open-knowledge-server';
+import { expect, test } from './_helpers';
+
+test.describe('timeline recovered-content restore', () => {
+ test('a silent rescue checkpoint restores its content from the timeline', async ({
+ page,
+ api,
+ workerServer,
+ }) => {
+ const docName = `recovered-${randomUUID().slice(0, 8)}`;
+ const liveMarker = `LIVE-BODY-${randomUUID().slice(0, 8)}`;
+ const rescuedMarker = `RESCUED-BODY-${randomUUID().slice(0, 8)}`;
+ const liveBody = `# Live heading\n\n${liveMarker}\n`;
+ const rescued = `# Rescued heading\n\n${rescuedMarker}\n`;
+
+ // Seed the live doc the user is currently editing.
+ await api.createPage(`${docName}.md`);
+ await api.replaceDoc(docName, liveBody);
+
+ // Seed a silent bridge-merge-loss checkpoint into the SAME shadow repo the
+ // dev server reads — the way the observer bridge does on a real loss. The
+ // dev server (a separate process) holds the shadow writer lock, so open a
+ // lock-free handle rather than initShadowRepo: a checkpoint is a single
+ // atomic write to a ref keyed by its own commit sha, so it can't collide
+ // with the server's WIP writes. The extension-less `contentRoot: ''` + bare
+ // docName matches production's Hocuspocus doc name (the restore floor).
+ const shadowDir = resolveShadowDir(workerServer.contentDir);
+ const silentSha = await saveInMemoryCheckpoint(
+ { gitDir: shadowDir, workTree: workerServer.contentDir },
+ '',
+ {
+ kind: 'bridge-merge-loss',
+ docName,
+ contents: rescued,
+ branch: 'main',
+ label: 'Before concurrent merge',
+ metadata: { lostSubstrings: [rescuedMarker] },
+ },
+ );
+ expect(silentSha).toHaveLength(40);
+
+ // Open the doc; the editor shows the live content first.
+ await page.goto(`/#/${docName}`);
+ await page.waitForFunction(() => Boolean(window.__activeProvider?.isSynced), null, {
+ timeout: 15_000,
+ });
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ const editor = page.locator('.ProseMirror:not(.composer-prosemirror)');
+ await expect(editor.getByText(liveMarker)).toBeVisible();
+
+ // Open the Timeline tab — the rescue checkpoint surfaces as an ordinary
+ // "Recovered content" row (internals-free label, no badge).
+ await page.getByRole('tab', { name: 'Timeline' }).click();
+ const recoveredRow = page
+ .getByTestId('timeline-entry-open')
+ .filter({ hasText: 'Recovered content' });
+ await expect(recoveredRow).toBeVisible();
+ // The internal checkpoint kind never leaks into the UI.
+ await expect(page.getByText('bridge-merge-loss')).toHaveCount(0);
+
+ // Restore it. Depending on commit timing the row may be newest (instant) or
+ // have later edits above it (confirm dialog) — handle both; the gating
+ // itself is pinned in the dom test.
+ await recoveredRow.getByTestId('timeline-entry-restore').click();
+ await page
+ .getByTestId('timeline-entry-restore-confirm')
+ .click({ timeout: 4_000 })
+ .catch(() => {
+ // No dialog → instant restore already fired (row was newest).
+ });
+
+ // The recovered content lands in the editor via the real rollback + CRDT
+ // round-trip; the previous live body is gone.
+ await expect(editor.getByText(rescuedMarker)).toBeVisible({ timeout: 15_000 });
+ await expect(editor.getByText(liveMarker)).toHaveCount(0);
+ });
+});
diff --git a/packages/cli/src/commands/bug-report-redact.ts b/packages/cli/src/commands/bug-report-redact.ts
index 83e2d55cd..a4f28fcbc 100644
--- a/packages/cli/src/commands/bug-report-redact.ts
+++ b/packages/cli/src/commands/bug-report-redact.ts
@@ -1,93 +1,13 @@
/**
- * Secret/PII redaction for `ok bug-report` bundles. Extracted from
- * `bug-report.ts` so it can be unit-tested directly — `bug-report.ts` imports
- * `cli.ts`, which parses argv at module load, so it can't be imported in a test.
+ * Secret/PII redaction for `ok bug-report` bundles. The pattern list is now
+ * canonical in `@inkeep/open-knowledge-core` (shared with the renderer
+ * console-capture forwarder so the two can't drift); this module re-exports it
+ * under the bundle-assembly names its callers already use.
*
* This is the ship-path backstop for the on-disk diagnostics logs (which now
* include captured renderer/browser console output): `redactContent` runs over
* every bundled file before it leaves the machine. It is best-effort pattern
- * matching, not a guarantee — see the JWT / URL-credential note below.
+ * matching, not a guarantee.
*/
-interface SecretPattern {
- name: string;
- regex: RegExp;
- replacement: string;
-}
-
-const SECRET_PATTERNS: readonly SecretPattern[] = [
- { name: 'macos-home-path', regex: /\/Users\/[^/]+\//g, replacement: '~/' },
- { name: 'linux-home-path', regex: /\/home\/[^/]+\//g, replacement: '~/' },
- {
- name: 'github-pat',
- regex: /\b(ghp_|gho_|ghu_|ghs_|ghr_)[A-Za-z0-9]{36,}\b/g,
- replacement: '[REDACTED-GH-PAT]',
- },
- {
- name: 'aws-access-key',
- regex: /\b(AKIA|ASIA|ABIA)[A-Z2-7]{16}\b/g,
- replacement: '[REDACTED-AWS-KEY]',
- },
- {
- name: 'anthropic-key',
- regex: /\bsk-ant-api03-[A-Za-z0-9_-]{20,}\b/g,
- replacement: '[REDACTED-ANTHROPIC]',
- },
- { name: 'openai-key', regex: /\bsk-[A-Za-z0-9]{20,}\b/g, replacement: '[REDACTED-OPENAI]' },
- {
- name: 'bearer-token',
- regex: /([Aa]uthorization:\s*[Bb]earer\s+)\S+/g,
- replacement: '$1[REDACTED]',
- },
- // JWTs (header.payload.signature; header + payload are base64url of `{`) and
- // credentials embedded in URLs (`scheme://user:pass@host`, e.g. token push
- // URLs / DB connection strings). Added because client-side console capture
- // now routes free-text renderer output into the bundled logs. No trailing
- // `\b` on the JWT — base64url's `-`/`_` aren't word chars, so a signature
- // ending in one wouldn't have a word boundary after it; the greedy class
- // consumes the whole signature instead.
- {
- name: 'jwt',
- regex: /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
- replacement: '[REDACTED-JWT]',
- },
- {
- name: 'url-credentials',
- regex: /:\/\/[^/\s:@]+:[^/\s:@]+@/g,
- replacement: '://[REDACTED]@',
- },
-];
-
-/** Names of the redaction patterns, for the bundle's privacy summary. */
-export const SECRET_PATTERN_NAMES: readonly string[] = SECRET_PATTERNS.map((p) => p.name);
-
-/** Apply {@link SECRET_PATTERNS} line by line; report which patterns matched. */
-export function redactContent(content: string): {
- redacted: string;
- patterns: string[];
- lineCount: number;
-} {
- const matchedPatterns = new Set<string>();
- let linesChanged = 0;
- const lines = content.split('\n');
-
- const redactedLines = lines.map((line) => {
- let modified = line;
- for (const { name, regex, replacement } of SECRET_PATTERNS) {
- regex.lastIndex = 0;
- if (regex.test(modified)) {
- matchedPatterns.add(name);
- linesChanged++;
- regex.lastIndex = 0;
- modified = modified.replace(regex, replacement);
- }
- }
- return modified;
- });
-
- return {
- redacted: redactedLines.join('\n'),
- patterns: [...matchedPatterns],
- lineCount: linesChanged,
- };
-}
+export { redactSecrets as redactContent, SECRET_PATTERN_NAMES } from '@inkeep/open-knowledge-core';
diff --git a/packages/cli/src/commands/diagnose-bundle-options.test.ts b/packages/cli/src/commands/diagnose-bundle-options.test.ts
new file mode 100644
index 000000000..4961e8e00
--- /dev/null
+++ b/packages/cli/src/commands/diagnose-bundle-options.test.ts
@@ -0,0 +1,60 @@
+/**
+ * Option wiring for `ok diagnose bundle`.
+ *
+ * The redaction switch is a Commander boolean-negation pair with two sharp
+ * edges. Declaration order decides the default: a lone `--no-redact` defaults
+ * `redact` to true, but declaring the positive form first suppresses that and
+ * leaves it undefined. And a spelling Commander does not know is collected as
+ * an unknown option, which `parse()` turns into a hard error whose "did you
+ * mean" suggestion names the negated form — steering a user who asked for
+ * redaction into an unredacted bundle.
+ *
+ * `parseOptions` is the classifier `parse()` consults for both, so the wiring
+ * can be driven against the real command object without firing the action
+ * handler (which would collect a bundle off the cwd).
+ */
+
+import type { Command } from 'commander';
+import { describe, expect, test } from 'vitest';
+import { diagnoseCommand } from './diagnose.ts';
+
+function bundleCommand(): Command {
+ const bundle = diagnoseCommand().commands.find((c) => c.name() === 'bundle');
+ if (bundle === undefined) throw new Error('`bundle` subcommand missing from `ok diagnose`');
+ return bundle;
+}
+
+function parse(argv: string[]): { redact: unknown; unknown: string[] } {
+ const cmd = bundleCommand();
+ const { unknown } = cmd.parseOptions(argv);
+ return { redact: cmd.opts().redact, unknown };
+}
+
+describe('ok diagnose bundle — redaction switch', () => {
+ test('redacts when neither spelling is passed', () => {
+ expect(parse([])).toEqual({ redact: true, unknown: [] });
+ });
+
+ test('--no-redact opts out', () => {
+ expect(parse(['--no-redact'])).toEqual({ redact: false, unknown: [] });
+ });
+
+ test('--redact is accepted and keeps redaction on', () => {
+ expect(parse(['--redact'])).toEqual({ redact: true, unknown: [] });
+ });
+
+ test('--redact stays known when it follows another flag', () => {
+ expect(parse(['--yes', '--redact'])).toEqual({ redact: true, unknown: [] });
+ });
+
+ test('the last spelling on the command line wins', () => {
+ expect(parse(['--redact', '--no-redact']).redact).toBe(false);
+ expect(parse(['--no-redact', '--redact']).redact).toBe(true);
+ });
+
+ test('both spellings are listed in --help', () => {
+ const help = bundleCommand().helpInformation();
+ expect(help).toMatch(/^\s+--redact\s+\S/m);
+ expect(help).toMatch(/^\s+--no-redact\s+\S/m);
+ });
+});
diff --git a/packages/cli/src/commands/diagnose-bundle.test.ts b/packages/cli/src/commands/diagnose-bundle.test.ts
index 622e6c672..ad641d957 100644
--- a/packages/cli/src/commands/diagnose-bundle.test.ts
+++ b/packages/cli/src/commands/diagnose-bundle.test.ts
@@ -189,14 +189,15 @@ describe('runDiagnoseBundle — prompt + summary', () => {
await runDiagnoseBundle({ contentDir, yes: true }, deps);
const allLogs = captured.logs.join('\n');
- expect(allLogs).toContain('content summary');
+ expect(allLogs).toContain('what leaves this machine');
expect(allLogs).toContain('Files:');
expect(allLogs).toContain('Total size:');
- expect(allLogs).toContain('doc.name attributes:');
+ expect(allLogs).toContain('Document names:');
expect(allLogs).toContain('Content-dir path:');
+ expect(allLogs).toContain('Credentials:');
expect(allLogs).toContain('Server status:');
// Includes the count from the seeded spans file.
- expect(allLogs).toMatch(/doc\.name attributes:\s+1 occurrence/);
+ expect(allLogs).toMatch(/Document names:\s+included in cleartext \(1 doc\.name occurrence/);
});
test('prompt accepted with "y" → zip written', async () => {
@@ -241,6 +242,107 @@ describe('runDiagnoseBundle — prompt + summary', () => {
});
});
+// ---------------------------------------------------------------------------
+// consent summary — the copy has to match what actually ships
+// ---------------------------------------------------------------------------
+
+/**
+ * The summary is the only place a user is told what a bundle contains before
+ * they hand it to someone. It has to name each thing that leaves separately:
+ * doc names ship in cleartext even on the redacted path, so a single blanket
+ * "Redacted: yes" reads as a promise the bundle does not keep.
+ */
+describe('runDiagnoseBundle — consent summary', () => {
+ const SECRET = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';
+
+ function seedSpans(contentDir: string): void {
+ writeAt(
+ contentDir,
+ '.ok/local/telemetry/spans-current.jsonl',
+ `${JSON.stringify({
+ resourceSpans: [
+ {
+ scopeSpans: [
+ {
+ spans: [
+ {
+ attributes: [
+ { key: 'doc.name', value: { stringValue: 'q3-layoff-plan' } },
+ { key: 'fs.path', value: { stringValue: `${contentDir}/q3-layoff-plan.md` } },
+ { key: 'ok.note', value: { stringValue: `token ${SECRET}` } },
+ ],
+ },
+ ],
+ },
+ ],
+ },
+ ],
+ })}\n`,
+ );
+ }
+
+ test('default run names doc names as cleartext, the path as masked, and counts the scrub', async () => {
+ const contentDir = makeTmpDir();
+ seedSpans(contentDir);
+ const { deps, captured } = makeRunnerDeps();
+
+ await runDiagnoseBundle({ contentDir, yes: true }, deps);
+ const allLogs = captured.logs.join('\n');
+
+ expect(allLogs).toMatch(/Document names:\s+included in cleartext/);
+ expect(allLogs).toContain('masked as <CONTENT_DIR>');
+ expect(allLogs).not.toContain('but still present in some files');
+
+ const scrubbed = allLogs.match(
+ /Credentials:\s+scrubbed known credential formats \((\d+) line\(s\) across (\d+) file\(s\)\)/,
+ );
+ expect(scrubbed).not.toBeNull();
+ expect(Number(scrubbed?.[1])).toBeGreaterThan(0);
+ expect(Number(scrubbed?.[2])).toBeGreaterThan(0);
+
+ // The blanket claim is gone: nothing in the summary asserts the bundle as
+ // a whole is redacted while doc names ship raw.
+ expect(allLogs).not.toContain('Redacted:');
+ });
+
+ test('--no-redact run says the path is visible and credentials are not scrubbed', async () => {
+ const contentDir = makeTmpDir();
+ seedSpans(contentDir);
+ const { deps, captured } = makeRunnerDeps();
+
+ await runDiagnoseBundle({ contentDir, yes: true, redact: false }, deps);
+ const allLogs = captured.logs.join('\n');
+
+ expect(allLogs).toMatch(/Document names:\s+included in cleartext/);
+ expect(allLogs).toContain(`visible (${resolve(contentDir)})`);
+ expect(allLogs).toContain('NOT scrubbed (--no-redact): tokens and keys ship verbatim');
+ expect(allLogs).not.toContain('masked as <CONTENT_DIR>');
+ });
+
+ test('the summary describes the bundle that was actually written', async () => {
+ const contentDir = makeTmpDir();
+ seedSpans(contentDir);
+ const { deps, captured } = makeRunnerDeps();
+
+ const result = await runDiagnoseBundle({ contentDir, yes: true }, deps);
+ const allLogs = captured.logs.join('\n');
+
+ // Every claim above is only worth anything if the zip agrees with it.
+ const extractDir = makeTmpDir('ok-bundle-extract-');
+ execSync(
+ `unzip -q ${JSON.stringify(result.outputPath ?? '')} -d ${JSON.stringify(extractDir)}`,
+ );
+ const spans = readFileSync(join(extractDir, 'telemetry', 'spans-current.jsonl'), 'utf-8');
+
+ expect(allLogs).toMatch(/Document names:\s+included in cleartext/);
+ expect(spans).toContain('q3-layoff-plan');
+ expect(allLogs).toContain('masked as <CONTENT_DIR>');
+ expect(spans).not.toContain(contentDir);
+ expect(allLogs).toMatch(/Credentials:\s+scrubbed/);
+ expect(spans).not.toContain(SECRET);
+ });
+});
+
// ---------------------------------------------------------------------------
// --out flag
// ---------------------------------------------------------------------------
@@ -272,10 +374,10 @@ describe('runDiagnoseBundle — --out flag', () => {
// --redact end-to-end
// ---------------------------------------------------------------------------
-describe('runDiagnoseBundle — --redact', () => {
- test('hashes doc names and strips contentDir in zipped JSONLs; manifest carries inverse map', async () => {
+describe('runDiagnoseBundle — redaction', () => {
+ test('redacts by default: masks contentDir and scrubs credentials while doc names ship raw', async () => {
const contentDir = makeTmpDir();
- // Seed a fixture with a known doc name + the content-dir path.
+ const secret = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';
const otlpLine = JSON.stringify({
resourceSpans: [
{
@@ -286,6 +388,7 @@ describe('runDiagnoseBundle — --redact', () => {
attributes: [
{ key: 'doc.name', value: { stringValue: 'fixture-doc' } },
{ key: 'fs.path', value: { stringValue: `${contentDir}/foo.md` } },
+ { key: 'ok.note', value: { stringValue: `token ${secret}` } },
],
},
],
@@ -298,39 +401,34 @@ describe('runDiagnoseBundle — --redact', () => {
const { deps } = makeRunnerDeps();
const out = join(makeTmpDir('ok-bundle-out-'), 'redacted.zip');
- const result = await runDiagnoseBundle({ contentDir, out, yes: true, redact: true }, deps);
+ const result = await runDiagnoseBundle({ contentDir, out, yes: true }, deps);
expect(result.outputPath).toBe(out);
- // Extract the zip and inspect.
const extractDir = makeTmpDir('ok-bundle-extract-');
execSync(`unzip -q ${JSON.stringify(out)} -d ${JSON.stringify(extractDir)}`);
const zippedSpans = readFileSync(join(extractDir, 'telemetry', 'spans-current.jsonl'), 'utf-8');
- // (a) doc-name-shaped values were replaced with doc:<8hex>.
- expect(zippedSpans).not.toContain('fixture-doc');
- expect(zippedSpans).toMatch(/"doc:[a-f0-9]{8}"/);
-
- // (b) absolute content-dir prefix was replaced with <CONTENT_DIR>.
+ // Doc names ship raw under Detailed-diagnostics consent — no hashing.
+ expect(zippedSpans).toContain('fixture-doc');
+ expect(zippedSpans).not.toMatch(/doc:[a-f0-9]{8}/);
+ // The absolute content-dir prefix is masked.
expect(zippedSpans).not.toContain(contentDir);
expect(zippedSpans).toContain('<CONTENT_DIR>/foo.md');
+ // Credentials are scrubbed unconditionally.
+ expect(zippedSpans).not.toContain(secret);
+ expect(zippedSpans).toContain('[REDACTED-GH-PAT]');
- // (c) manifest.json.redaction.docNameMapSidecar references an out-of-zip
- // sidecar; the inverse map itself never lives inside the zip.
const manifest = JSON.parse(readFileSync(join(extractDir, 'manifest.json'), 'utf-8'));
expect(manifest.redaction.applied).toBe(true);
- expect(manifest.redaction.docNameMapSidecar).toMatch(/\.docnames\.json$/);
+ expect(manifest.redaction).not.toHaveProperty('docNameMapSidecar');
expect(manifest.redaction).not.toHaveProperty('docNameMap');
- // The manifest's absolutePath is masked when redaction is on, so the
- // recipient never sees the raw user-home path either.
+ expect(manifest.redaction.secretScrub.redactedLineCount).toBeGreaterThan(0);
expect(manifest.contentDir.absolutePath).toBe('<CONTENT_DIR>');
// pathSha256 stays as the SHA-256 of the original path for correlation.
expect(manifest.contentDir.pathSha256).toMatch(/^[0-9a-f]{64}$/);
- // The sidecar exists next to the zip and contains the inverse map.
- const sidecarPath = join(dirname(out), manifest.redaction.docNameMapSidecar);
- expect(existsSync(sidecarPath)).toBe(true);
- const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf-8'));
- expect(Object.values(sidecar.docNameMap)).toContain('fixture-doc');
+ // No inverse-map sidecar is written next to the zip anymore.
+ expect(existsSync(join(dirname(out), 'redacted.docnames.json'))).toBe(false);
});
test('original on-disk JSONL files under .ok/local/ are NOT modified by --redact', async () => {
@@ -376,8 +474,9 @@ describe('runDiagnoseBundle — --redact', () => {
expect(logsOnDisk).toContain('original-log-doc');
});
- test('--redact off by default leaves manifest.redaction.applied=false', async () => {
+ test('--no-redact writes a raw bundle: doc names, content-dir, and credentials all visible', async () => {
const contentDir = makeTmpDir();
+ const secret = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';
const otlpLine = JSON.stringify({
resourceSpans: [
{
@@ -385,7 +484,11 @@ describe('runDiagnoseBundle — --redact', () => {
{
spans: [
{
- attributes: [{ key: 'doc.name', value: { stringValue: 'visible' } }],
+ attributes: [
+ { key: 'doc.name', value: { stringValue: 'visible' } },
+ { key: 'fs.path', value: { stringValue: `${contentDir}/foo.md` } },
+ { key: 'ok.note', value: { stringValue: `token ${secret}` } },
+ ],
},
],
},
@@ -397,17 +500,21 @@ describe('runDiagnoseBundle — --redact', () => {
const { deps } = makeRunnerDeps();
const out = join(makeTmpDir('ok-bundle-out-'), 'plain.zip');
- await runDiagnoseBundle({ contentDir, out, yes: true }, deps);
+ await runDiagnoseBundle({ contentDir, out, yes: true, redact: false }, deps);
const extractDir = makeTmpDir('ok-bundle-extract-');
execSync(`unzip -q ${JSON.stringify(out)} -d ${JSON.stringify(extractDir)}`);
const zippedSpans = readFileSync(join(extractDir, 'telemetry', 'spans-current.jsonl'), 'utf-8');
+ // Positive control: without redaction the planted secret + content-dir are
+ // present, proving the scrub-on path actually removes them (not a scan of
+ // an empty/wrong file).
expect(zippedSpans).toContain('visible');
+ expect(zippedSpans).toContain(secret);
+ expect(zippedSpans).toContain(contentDir);
const manifest = JSON.parse(readFileSync(join(extractDir, 'manifest.json'), 'utf-8'));
expect(manifest.redaction.applied).toBe(false);
- expect(manifest.redaction.docNameMapSidecar).toBeNull();
- expect(manifest.redaction).not.toHaveProperty('docNameMap');
+ expect(manifest.redaction).not.toHaveProperty('docNameMapSidecar');
expect(manifest.contentDir.absolutePath).toBe(resolve(contentDir));
});
});
diff --git a/packages/cli/src/commands/diagnose.ts b/packages/cli/src/commands/diagnose.ts
index 0c47dba5f..732b70741 100644
--- a/packages/cli/src/commands/diagnose.ts
+++ b/packages/cli/src/commands/diagnose.ts
@@ -486,9 +486,10 @@ export interface RunDiagnoseBundleOpts {
/** Skip the y/N prompt and write unconditionally. */
yes?: boolean;
/**
- * Apply `--redact`: hash `doc.name` attribute values in staged JSONLs and
- * replace the absolute content-dir prefix with the literal `<CONTENT_DIR>`
- * token. Originals under `<contentDir>/.ok/local/` are NOT modified — the
+ * Redaction of the staged copies: scrub credentials (secret patterns) and
+ * mask the absolute content-dir prefix as `<CONTENT_DIR>`. Defaults to ON;
+ * `false` (the `--no-redact` opt-out) writes a raw bundle. Doc names ship raw
+ * either way. Originals under `<contentDir>/.ok/local/` are NOT modified — the
* redactor mutates only the staged copies inside the bundle.
*/
redact?: boolean;
@@ -559,6 +560,39 @@ function isAffirmative(answer: string): boolean {
return a === 'y' || a === 'yes';
}
+/**
+ * How the content-dir path ends up in the zip. `redacted` says the mask ran;
+ * `contentDirVisible` is the empirical post-mask scan. They can disagree — the
+ * mask covers `telemetry/`, `logs/`, `process/`, and `state/`, while `note.txt`
+ * is staged after it — so the disagreement is reported rather than assumed
+ * away. The consent prompt is only worth printing if it describes the bytes
+ * that actually leave.
+ */
+function describeContentDirPath(collected: CollectedBundle): string {
+ const { summary, manifest } = collected;
+ if (summary.redacted) {
+ return summary.contentDirVisible
+ ? 'masked as <CONTENT_DIR>, but still present in some files'
+ : 'masked as <CONTENT_DIR>';
+ }
+ return summary.contentDirVisible
+ ? `visible (${manifest.contentDir.absolutePath})`
+ : 'not present';
+}
+
+/**
+ * Credential scrubbing rides the same `redact` switch as the path mask, so
+ * `--no-redact` ships tokens verbatim. That is the point of a raw bundle, but
+ * the user has to be told before they hand it to anyone.
+ */
+function describeCredentials(collected: CollectedBundle): string {
+ const scrub = collected.manifest.redaction.secretScrub;
+ if (scrub === undefined) {
+ return pc.yellow('NOT scrubbed (--no-redact): tokens and keys ship verbatim');
+ }
+ return `scrubbed known credential formats (${scrub.redactedLineCount} line(s) across ${scrub.redactions.length} file(s))`;
+}
+
function printSummary(
log: (msg: string) => void,
collected: CollectedBundle,
@@ -566,19 +600,15 @@ function printSummary(
): void {
const { summary, manifest } = collected;
log('');
- log(pc.bold('ok diagnose bundle — content summary'));
+ log(pc.bold('ok diagnose bundle — what leaves this machine'));
log('');
log(` Files: ${summary.fileCount}`);
log(` Total size: ${formatBytes(summary.totalBytes)} uncompressed`);
log(
- ` doc.name attributes: ${summary.docNameCount} occurrence(s) in telemetry${
- summary.redacted ? ' (values hashed)' : ''
- }`,
+ ` Document names: included in cleartext (${summary.docNameCount} doc.name occurrence(s) in telemetry)`,
);
- log(
- ` Content-dir path: ${summary.contentDirVisible ? `visible (${manifest.contentDir.absolutePath})` : 'not visible'}`,
- );
- log(` Redacted: ${summary.redacted ? 'yes' : 'no'}`);
+ log(` Content-dir path: ${describeContentDirPath(collected)}`);
+ log(` Credentials: ${describeCredentials(collected)}`);
log(` Server status: ${manifest.serverStatus}`);
log(` Output: ${outputPath}`);
log('');
@@ -620,11 +650,16 @@ export async function runDiagnoseBundle(
processDir = await runProcess(opts.pid);
}
+ // Redact by default: mask the content-dir path and scrub credentials from
+ // the staged copies. `--no-redact` (opts.redact === false) opts out for a raw
+ // local dump the user inspects themselves. Doc names ship raw either way.
+ const redact = opts.redact !== false;
const collected = await collectBundle({
contentDir: opts.contentDir,
projectDir: opts.projectDir,
processDir,
- redact: opts.redact === true,
+ redact,
+ scrubSecrets: redact,
deps: deps.collectDeps,
});
@@ -711,7 +746,17 @@ export function diagnoseCommand(): Command {
)
.option('--out <path>', 'Write the zip to this path instead of the default location')
.option('--yes', 'Skip the y/N prompt')
- .option('--redact', 'Hash doc names and strip the content-dir prefix from the staged bundle')
+ // Declaration ORDER is load-bearing in Commander: a lone `--no-redact`
+ // defaults `opts.redact` to true, but declaring the positive form FIRST
+ // suppresses that default and leaves it undefined. `--no-redact` therefore
+ // stays first, and `--redact` is the explicit no-op alias that keeps the
+ // pre-flip spelling working instead of erroring with a "did you mean
+ // --no-redact?" hint that would steer the user to the opposite behavior.
+ .option(
+ '--no-redact',
+ 'Write a raw bundle: skip credential scrubbing and content-dir path masking',
+ )
+ .option('--redact', 'Scrub credentials and mask the content-dir path (the default)')
.action(async (opts: { pid?: string; out?: string; yes?: boolean; redact?: boolean }) => {
let pid: number | undefined;
if (opts.pid !== undefined) {
@@ -733,7 +778,7 @@ export function diagnoseCommand(): Command {
pid,
out: opts.out,
yes: opts.yes === true,
- redact: opts.redact === true,
+ redact: opts.redact,
});
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
diff --git a/packages/cli/src/diagnose/bundle-redact.test.ts b/packages/cli/src/diagnose/bundle-redact.test.ts
index 83602682a..8bd092cb2 100644
--- a/packages/cli/src/diagnose/bundle-redact.test.ts
+++ b/packages/cli/src/diagnose/bundle-redact.test.ts
@@ -1,26 +1,22 @@
/**
- * Unit tests for the bundle redactor.
+ * Unit tests for the bundle content-dir masker.
*
- * The redactor walks staged JSONL + JSON files under a bundle's staging dir
- * and produces:
- * - doc.name attribute values replaced by `doc:<8 hex>` sha256 hashes
- * - the absolute content-dir prefix replaced with the literal `<CONTENT_DIR>`
- * - a stable per-bundle inverse map (`hashed → original`) for `manifest.json`
+ * The masker walks staged JSONL + JSON + plain files under a bundle's staging
+ * dir and replaces the absolute content-dir prefix, wherever it appears, with
+ * the literal `<CONTENT_DIR>` token. Doc names / titles are NOT anonymized —
+ * they ship raw under the user's Detailed-diagnostics consent (credentials are
+ * handled by the separate secret-pattern scrub).
*
* Tests use real disk fixtures (no fs mocks) since the module's job is
- * filesystem-shaped. We seed JSONL + JSON in a tmpdir, call the redactor,
- * and assert on the rewritten files + the returned map.
+ * filesystem-shaped. We seed files in a tmpdir, call the masker, and assert on
+ * the rewritten files.
*/
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { afterEach, describe, expect, test } from 'vitest';
-import {
- _recordHashForTests,
- type RedactStagedBundleResult,
- redactStagedBundle,
-} from './bundle-redact.ts';
+import { redactStagedBundle } from './bundle-redact.ts';
const tmpDirs: string[] = [];
@@ -48,12 +44,8 @@ function readStaged(stagingDir: string, relPath: string): string {
return readFileSync(join(stagingDir, relPath), 'utf-8');
}
-// ---------------------------------------------------------------------------
-// OTLP attribute-pair shape gets doc.name hashed
-// ---------------------------------------------------------------------------
-
-describe('redactStagedBundle — tracer bullet', () => {
- test('hashes the OTLP attribute-pair `doc.name` stringValue', () => {
+describe('redactStagedBundle — doc names ship raw', () => {
+ test('leaves an OTLP `doc.name` attribute value unhashed', () => {
const stagingDir = makeStagingDir();
const otlpLine = JSON.stringify({
resourceSpans: [
@@ -61,9 +53,7 @@ describe('redactStagedBundle — tracer bullet', () => {
scopeSpans: [
{
spans: [
- {
- attributes: [{ key: 'doc.name', value: { stringValue: 'my-secret-doc' } }],
- },
+ { attributes: [{ key: 'doc.name', value: { stringValue: 'meetings/plan' } }] },
],
},
],
@@ -72,190 +62,39 @@ describe('redactStagedBundle — tracer bullet', () => {
});
writeStaged(stagingDir, 'telemetry/spans-current.jsonl', `${otlpLine}\n`);
- const result = redactStagedBundle({ stagingDir, contentDir: '/Users/test/notes' });
+ redactStagedBundle({ stagingDir, contentDir: '/Users/test/notes' });
const after = readStaged(stagingDir, 'telemetry/spans-current.jsonl');
- expect(after).not.toContain('my-secret-doc');
- expect(after).toMatch(/"doc:[a-f0-9]{8}"/);
-
- // The inverse map records hashed → original.
- const entries = Object.entries(result.docNameMap);
- expect(entries).toHaveLength(1);
- const [hashed, original] = entries[0] ?? ['', ''];
- expect(original).toBe('my-secret-doc');
- expect(hashed).toMatch(/^doc:[a-f0-9]{8}$/);
- });
-});
-
-// ---------------------------------------------------------------------------
-// Pino flat-key shape + nested objects
-// ---------------------------------------------------------------------------
-
-describe('redactStagedBundle — Pino + nested shapes', () => {
- test('hashes a Pino flat-key `doc.name` value in a log record', () => {
- const stagingDir = makeStagingDir();
- const pinoLine = JSON.stringify({
- level: 30,
- time: 1716908521000,
- 'doc.name': 'pino-secret',
- msg: 'wrote doc',
- });
- writeStaged(stagingDir, 'logs/server-current.jsonl', `${pinoLine}\n`);
-
- const result = redactStagedBundle({ stagingDir, contentDir: '/Users/test/notes' });
-
- const after = readStaged(stagingDir, 'logs/server-current.jsonl');
- expect(after).not.toContain('pino-secret');
- const parsed = JSON.parse(after.trim());
- expect(parsed['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
- expect(Object.values(result.docNameMap)).toContain('pino-secret');
+ expect(after).toContain('meetings/plan');
+ expect(after).not.toMatch(/doc:[a-f0-9]{8}/);
});
- test('hashes a `doc.name` nested inside a structured Pino log object', () => {
+ test('leaves a Pino flat-key `doc.name` and a presence `currentDoc` raw', () => {
const stagingDir = makeStagingDir();
- const pinoLine = JSON.stringify({
- level: 30,
- msg: 'handler',
- req: { url: '/api/x', 'doc.name': 'nested-doc' },
- });
+ const pinoLine = JSON.stringify({ level: 30, 'doc.name': 'notes/journal', msg: 'wrote doc' });
writeStaged(stagingDir, 'logs/server-current.jsonl', `${pinoLine}\n`);
-
- redactStagedBundle({ stagingDir, contentDir: '/x' });
-
- const after = JSON.parse(readStaged(stagingDir, 'logs/server-current.jsonl').trim());
- expect(after.req['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
- expect(after.req['doc.name']).not.toBe('nested-doc');
- });
-
- test('preserves non-doc-name attributes inside an OTLP attribute array', () => {
- const stagingDir = makeStagingDir();
- const otlpLine = JSON.stringify({
- resourceSpans: [
- {
- scopeSpans: [
- {
- spans: [
- {
- attributes: [
- { key: 'http.method', value: { stringValue: 'GET' } },
- { key: 'doc.name', value: { stringValue: 'secret-x' } },
- { key: 'http.status_code', value: { intValue: 200 } },
- ],
- },
- ],
- },
- ],
- },
- ],
- });
- writeStaged(stagingDir, 'telemetry/spans-current.jsonl', `${otlpLine}\n`);
+ writeStaged(
+ stagingDir,
+ 'state/agent-presence.json',
+ JSON.stringify({
+ presence: { 'agent-a1': { currentDoc: 'meetings/secret-standup', ts: 1 } },
+ }),
+ );
redactStagedBundle({ stagingDir, contentDir: '/Users/test/notes' });
- const after = JSON.parse(readStaged(stagingDir, 'telemetry/spans-current.jsonl').trim());
- const attrs = after.resourceSpans[0].scopeSpans[0].spans[0].attributes;
- expect(attrs[0]).toEqual({ key: 'http.method', value: { stringValue: 'GET' } });
- expect(attrs[1].key).toBe('doc.name');
- expect(attrs[1].value.stringValue).toMatch(/^doc:[a-f0-9]{8}$/);
- expect(attrs[2]).toEqual({ key: 'http.status_code', value: { intValue: 200 } });
- });
-
- test('walks doc.name in resource-level and event-level OTLP attributes too', () => {
- const stagingDir = makeStagingDir();
- const otlpLine = JSON.stringify({
- resourceSpans: [
- {
- resource: {
- attributes: [{ key: 'doc.name', value: { stringValue: 'res-doc' } }],
- },
- scopeSpans: [
- {
- spans: [
- {
- events: [
- {
- attributes: [{ key: 'doc.name', value: { stringValue: 'evt-doc' } }],
- },
- ],
- },
- ],
- },
- ],
- },
- ],
- });
- writeStaged(stagingDir, 'telemetry/spans-current.jsonl', `${otlpLine}\n`);
-
- const result = redactStagedBundle({ stagingDir, contentDir: '/x' });
-
- const after = readStaged(stagingDir, 'telemetry/spans-current.jsonl');
- expect(after).not.toContain('res-doc');
- expect(after).not.toContain('evt-doc');
- expect(Object.values(result.docNameMap).sort()).toEqual(['evt-doc', 'res-doc']);
- });
-
- test('preserves the partial trailing line untouched (AC8 SIGKILL resilience)', () => {
- const stagingDir = makeStagingDir();
- const completeLine = JSON.stringify({
- resourceSpans: [
- {
- scopeSpans: [
- { spans: [{ attributes: [{ key: 'doc.name', value: { stringValue: 'a' } }] }] },
- ],
- },
- ],
- });
- // Two complete lines + one unterminated trailing fragment (mid-write).
- const body = `${completeLine}\n${completeLine}\n{"resourceSpans"`;
- writeStaged(stagingDir, 'telemetry/spans-current.jsonl', body);
-
- redactStagedBundle({ stagingDir, contentDir: '/x' });
-
- const after = readStaged(stagingDir, 'telemetry/spans-current.jsonl');
- // Trailing fragment preserved verbatim — recipients skip it the same way.
- expect(after.endsWith('{"resourceSpans"')).toBe(true);
- // Both complete lines were redacted.
- expect(after).not.toContain('"a"');
- });
-
- test('non-string doc.name values pass through unchanged (only strings hash)', () => {
- // A doc.name attribute with an intValue (theoretically possible) should
- // NOT be hashed. The redactor only touches stringValue/string forms.
- const stagingDir = makeStagingDir();
- const otlpLine = JSON.stringify({
- resourceSpans: [
- {
- scopeSpans: [
- {
- spans: [
- {
- attributes: [{ key: 'doc.name', value: { intValue: 12345 } }],
- },
- ],
- },
- ],
- },
- ],
- });
- writeStaged(stagingDir, 'telemetry/spans-current.jsonl', `${otlpLine}\n`);
-
- const result = redactStagedBundle({ stagingDir, contentDir: '/x' });
-
- const after = JSON.parse(readStaged(stagingDir, 'telemetry/spans-current.jsonl').trim());
- expect(after.resourceSpans[0].scopeSpans[0].spans[0].attributes[0]).toEqual({
- key: 'doc.name',
- value: { intValue: 12345 },
- });
- expect(result.docNameMap).toEqual({});
+ expect(JSON.parse(readStaged(stagingDir, 'logs/server-current.jsonl').trim())['doc.name']).toBe(
+ 'notes/journal',
+ );
+ expect(
+ JSON.parse(readStaged(stagingDir, 'state/agent-presence.json')).presence['agent-a1']
+ .currentDoc,
+ ).toBe('meetings/secret-standup');
});
});
-// ---------------------------------------------------------------------------
-// contentDir → <CONTENT_DIR> substring substitution
-// ---------------------------------------------------------------------------
-
-describe('redactStagedBundle — contentDir substitution', () => {
- test('replaces contentDir prefix in span string-value attributes', () => {
+describe('redactStagedBundle — contentDir masking', () => {
+ test('replaces the contentDir prefix in an OTLP string-value attribute', () => {
const stagingDir = makeStagingDir();
const contentDir = '/Users/test/my-notes';
const otlpLine = JSON.stringify({
@@ -265,12 +104,7 @@ describe('redactStagedBundle — contentDir substitution', () => {
{
spans: [
{
- attributes: [
- {
- key: 'fs.path',
- value: { stringValue: '/Users/test/my-notes/foo.md' },
- },
- ],
+ attributes: [{ key: 'fs.path', value: { stringValue: `${contentDir}/foo.md` } }],
},
],
},
@@ -283,317 +117,171 @@ describe('redactStagedBundle — contentDir substitution', () => {
redactStagedBundle({ stagingDir, contentDir });
const after = readStaged(stagingDir, 'telemetry/spans-current.jsonl');
- expect(after).not.toContain('/Users/test/my-notes');
+ expect(after).not.toContain(contentDir);
expect(after).toContain('<CONTENT_DIR>/foo.md');
});
- test('replaces all occurrences of contentDir in a single string field', () => {
+ test('replaces every occurrence of contentDir in a single string field', () => {
const stagingDir = makeStagingDir();
const contentDir = '/Users/test/notes';
const pinoLine = JSON.stringify({
level: 30,
- msg: 'opened /Users/test/notes/a then /Users/test/notes/b',
+ msg: `opened ${contentDir}/a then ${contentDir}/b`,
});
writeStaged(stagingDir, 'logs/server-current.jsonl', `${pinoLine}\n`);
redactStagedBundle({ stagingDir, contentDir });
- const after = JSON.parse(readStaged(stagingDir, 'logs/server-current.jsonl').trim());
- expect(after.msg).toBe('opened <CONTENT_DIR>/a then <CONTENT_DIR>/b');
+ expect(JSON.parse(readStaged(stagingDir, 'logs/server-current.jsonl').trim()).msg).toBe(
+ 'opened <CONTENT_DIR>/a then <CONTENT_DIR>/b',
+ );
});
- test('replaces contentDir in state/runtime.json string fields', () => {
+ test('masks contentDir in state/runtime.json via the JSON walker', () => {
const stagingDir = makeStagingDir();
const contentDir = '/Users/test/notes';
writeStaged(
stagingDir,
'state/runtime.json',
- `${JSON.stringify({ ok: { workingDir: '/Users/test/notes' } }, null, 2)}\n`,
+ `${JSON.stringify({ ok: { workingDir: contentDir } }, null, 2)}\n`,
);
redactStagedBundle({ stagingDir, contentDir });
const after = readStaged(stagingDir, 'state/runtime.json');
- expect(after).not.toContain('/Users/test/notes');
+ expect(after).not.toContain(contentDir);
expect(after).toContain('<CONTENT_DIR>');
});
- test('replaces contentDir in state/.txt plain files (substring only)', () => {
+ test('masks contentDir in a state/.txt plain file', () => {
const stagingDir = makeStagingDir();
const contentDir = '/Users/test/notes';
writeStaged(
stagingDir,
'state/shadow-head.txt',
- 'deadbee /Users/test/notes/foo\nbabecake /Users/test/notes/bar\n',
- );
-
- redactStagedBundle({ stagingDir, contentDir });
-
- const after = readStaged(stagingDir, 'state/shadow-head.txt');
- expect(after).toBe('deadbee <CONTENT_DIR>/foo\nbabecake <CONTENT_DIR>/bar\n');
- });
-
- test('replaces contentDir in state/agent-presence.json walker pass', () => {
- const stagingDir = makeStagingDir();
- const contentDir = '/Users/test/notes';
- writeStaged(
- stagingDir,
- 'state/agent-presence.json',
- `${JSON.stringify({
- agents: [
- {
- agentId: 'a1',
- 'doc.name': 'live-doc',
- workingDir: '/Users/test/notes',
- },
- ],
- })}`,
- );
-
- const result = redactStagedBundle({ stagingDir, contentDir });
-
- const after = JSON.parse(readStaged(stagingDir, 'state/agent-presence.json'));
- expect(after.agents[0].workingDir).toBe('<CONTENT_DIR>');
- expect(after.agents[0]['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
- expect(Object.values(result.docNameMap)).toContain('live-doc');
- });
-
- test('hashes the real `currentDoc` field the presence endpoint emits', () => {
- // The live `/api/metrics/agent-presence` wire body carries the doc path
- // under `currentDoc`, not `doc.name`. The walker must hash that exact key
- // so a staged presence artifact never leaks the doc a human is editing.
- const stagingDir = makeStagingDir();
- const contentDir = '/Users/test/notes';
- writeStaged(
- stagingDir,
- 'state/agent-presence.json',
- `${JSON.stringify({
- presence: {
- 'agent-a1': {
- displayName: 'Claude',
- icon: 'claude',
- color: '#abc',
- currentDoc: 'meetings/secret-standup',
- mode: 'writing',
- ts: 1,
- },
- },
- })}`,
- );
-
- const result = redactStagedBundle({ stagingDir, contentDir });
-
- const after = JSON.parse(readStaged(stagingDir, 'state/agent-presence.json'));
- expect(after.presence['agent-a1'].currentDoc).toMatch(/^doc:[a-f0-9]{8}$/);
- expect(JSON.stringify(after)).not.toContain('meetings/secret-standup');
- expect(Object.values(result.docNameMap)).toContain('meetings/secret-standup');
- });
-
- test('leaves a null `currentDoc` untouched (only strings hash)', () => {
- const stagingDir = makeStagingDir();
- const contentDir = '/Users/test/notes';
- writeStaged(
- stagingDir,
- 'state/agent-presence.json',
- `${JSON.stringify({
- presence: { 'agent-a1': { currentDoc: null, mode: 'idle', ts: 1 } },
- })}`,
+ `deadbee ${contentDir}/foo\nbabecake ${contentDir}/bar\n`,
);
redactStagedBundle({ stagingDir, contentDir });
- const after = JSON.parse(readStaged(stagingDir, 'state/agent-presence.json'));
- expect(after.presence['agent-a1'].currentDoc).toBeNull();
- });
-
- test('hashes doc.name values in state/agent-effects.json via the walker pass', () => {
- const stagingDir = makeStagingDir();
- const contentDir = '/Users/test/notes';
- writeStaged(
- stagingDir,
- 'state/agent-effects.json',
- `${JSON.stringify({
- effects: [
- {
- 'doc.name': 'meetings/standup',
- entries: [{ sessionId: 'agent-a1', agentType: 'claude', ts: 1, insertedChars: 4 }],
- },
- ],
- })}`,
+ expect(readStaged(stagingDir, 'state/shadow-head.txt')).toBe(
+ 'deadbee <CONTENT_DIR>/foo\nbabecake <CONTENT_DIR>/bar\n',
);
-
- const result = redactStagedBundle({ stagingDir, contentDir });
-
- const after = JSON.parse(readStaged(stagingDir, 'state/agent-effects.json'));
- expect(after.effects[0]['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
- expect(after.effects[0].entries[0].sessionId).toBe('agent-a1');
- expect(Object.values(result.docNameMap)).toContain('meetings/standup');
});
- test('hashes doc.name values in state/watcher-recent.jsonl via the line-wise walker', () => {
+ test('masks contentDir in state/watcher-recent.jsonl line-by-line', () => {
const stagingDir = makeStagingDir();
const contentDir = '/Users/test/notes';
const lines = [
JSON.stringify({
ts: 1,
decision: 'dispatched',
- kind: 'create',
- 'doc.name': '.../meetings/standup.md',
- pathRole: 'content-md',
+ absPath: `${contentDir}/meetings/standup.md`,
}),
JSON.stringify({
ts: 2,
decision: 'drop-filter-excluded',
- kind: 'update',
- 'doc.name': '.../dist/output.md',
- pathRole: 'content-md',
+ absPath: `${contentDir}/dist/o.md`,
}),
];
writeStaged(stagingDir, 'state/watcher-recent.jsonl', `${lines.join('\n')}\n`);
- const result = redactStagedBundle({ stagingDir, contentDir });
+ redactStagedBundle({ stagingDir, contentDir });
const after = readStaged(stagingDir, 'state/watcher-recent.jsonl');
- expect(after).not.toContain('standup');
- expect(after).not.toContain('output.md');
+ expect(after).not.toContain(contentDir);
const parsed = after
.trim()
.split('\n')
.map((line) => JSON.parse(line));
- expect(parsed[0]['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
+ expect(parsed[0].absPath).toBe('<CONTENT_DIR>/meetings/standup.md');
expect(parsed[0].decision).toBe('dispatched');
- expect(parsed[1]['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
- expect(Object.values(result.docNameMap)).toContain('.../meetings/standup.md');
});
- test('strings that do not include contentDir are passed through verbatim', () => {
+ test('preserves a partial trailing JSONL line untouched (SIGKILL resilience)', () => {
const stagingDir = makeStagingDir();
const contentDir = '/Users/test/notes';
- const pinoLine = JSON.stringify({ level: 30, msg: 'unrelated message' });
- writeStaged(stagingDir, 'logs/server-current.jsonl', `${pinoLine}\n`);
+ const complete = JSON.stringify({ msg: `at ${contentDir}/a` });
+ writeStaged(stagingDir, 'telemetry/spans-current.jsonl', `${complete}\n${complete}\n{"msg"`);
redactStagedBundle({ stagingDir, contentDir });
- const after = JSON.parse(readStaged(stagingDir, 'logs/server-current.jsonl').trim());
- expect(after.msg).toBe('unrelated message');
+ const after = readStaged(stagingDir, 'telemetry/spans-current.jsonl');
+ expect(after.endsWith('{"msg"')).toBe(true);
+ expect(after).not.toContain(`${contentDir}/a`);
+ expect(after).toContain('<CONTENT_DIR>/a');
});
- test('stable per-bundle: same input → same hash; map has one entry', () => {
+ test('masks contentDir in a corrupt (unparseable) state JSON via the whole-file fallback', () => {
const stagingDir = makeStagingDir();
- const sharedLine = JSON.stringify({
- 'doc.name': 'same',
- msg: 'one',
- });
- const sharedLine2 = JSON.stringify({
- 'doc.name': 'same',
- msg: 'two',
- });
- writeStaged(stagingDir, 'logs/server-current.jsonl', `${sharedLine}\n${sharedLine2}\n`);
+ const contentDir = '/Users/test/notes';
+ const torn = `{ "active-doc": "notes/plan", "contentDir": "${contentDir}", /* corrupt`;
+ writeStaged(stagingDir, 'state/agent-presence.json', torn);
- const result = redactStagedBundle({ stagingDir, contentDir: '/x' });
+ redactStagedBundle({ stagingDir, contentDir });
- const after = readStaged(stagingDir, 'logs/server-current.jsonl').trim().split('\n');
- const p1 = JSON.parse(after[0] ?? '');
- const p2 = JSON.parse(after[1] ?? '');
- expect(p1['doc.name']).toBe(p2['doc.name']);
- expect(Object.keys(result.docNameMap)).toHaveLength(1);
+ const after = readStaged(stagingDir, 'state/agent-presence.json');
+ expect(after).not.toContain(contentDir);
+ expect(after).toContain('<CONTENT_DIR>');
+ // Doc name in the torn fragment still ships raw.
+ expect(after).toContain('notes/plan');
});
- test('distinct doc names produce distinct hashes and map entries', () => {
+ test('non-string leaves pass through unchanged', () => {
const stagingDir = makeStagingDir();
- const a = JSON.stringify({ 'doc.name': 'a' });
- const b = JSON.stringify({ 'doc.name': 'b' });
- const c = JSON.stringify({ 'doc.name': 'c' });
- writeStaged(stagingDir, 'logs/server-current.jsonl', `${a}\n${b}\n${c}\n`);
-
- const result = redactStagedBundle({ stagingDir, contentDir: '/x' });
- expect(Object.keys(result.docNameMap)).toHaveLength(3);
- expect(Object.values(result.docNameMap).sort()).toEqual(['a', 'b', 'c']);
- // Hashes are deterministic but distinct.
- const hashes = Object.keys(result.docNameMap);
- expect(new Set(hashes).size).toBe(3);
+ const otlpLine = JSON.stringify({
+ resourceSpans: [
+ {
+ scopeSpans: [
+ { spans: [{ attributes: [{ key: 'http.status_code', value: { intValue: 200 } }] }] },
+ ],
+ },
+ ],
+ });
+ writeStaged(stagingDir, 'telemetry/spans-current.jsonl', `${otlpLine}\n`);
+
+ redactStagedBundle({ stagingDir, contentDir: '/x' });
+
+ const after = JSON.parse(readStaged(stagingDir, 'telemetry/spans-current.jsonl').trim());
+ expect(after.resourceSpans[0].scopeSpans[0].spans[0].attributes[0]).toEqual({
+ key: 'http.status_code',
+ value: { intValue: 200 },
+ });
});
- test('empty staging dir produces an empty docNameMap', () => {
+ test('a string with no contentDir substring is passed through verbatim', () => {
const stagingDir = makeStagingDir();
- const result = redactStagedBundle({ stagingDir, contentDir: '/x' });
- expect(result.docNameMap).toEqual({});
+ const pinoLine = JSON.stringify({ level: 30, msg: 'unrelated message' });
+ writeStaged(stagingDir, 'logs/server-current.jsonl', `${pinoLine}\n`);
+
+ redactStagedBundle({ stagingDir, contentDir: '/Users/test/notes' });
+
+ expect(JSON.parse(readStaged(stagingDir, 'logs/server-current.jsonl').trim()).msg).toBe(
+ 'unrelated message',
+ );
});
- test('empty contentDir does not insert tokens between characters', () => {
- // Defensive guard against a degenerate config that hands the redactor an
- // empty string. Without the guard, split('').join('<CONTENT_DIR>') would
- // explode every string into per-character tokens.
+ test('an empty contentDir does not insert tokens between characters', () => {
+ // Defensive guard against a degenerate config that hands the masker an
+ // empty string. Without it, split('').join('<CONTENT_DIR>') would explode
+ // every string into per-character tokens.
const stagingDir = makeStagingDir();
const pinoLine = JSON.stringify({ level: 30, msg: 'abc' });
writeStaged(stagingDir, 'logs/server-current.jsonl', `${pinoLine}\n`);
redactStagedBundle({ stagingDir, contentDir: '' });
- const after = JSON.parse(readStaged(stagingDir, 'logs/server-current.jsonl').trim());
- expect(after.msg).toBe('abc');
- });
-});
-
-describe('hashOrLookup — collision detection', () => {
- test('first occurrence of a hash claims the inverse-map entry; subsequent distinct collisions go to docNameCollisions', () => {
- // We exercise the internal recordHash helper directly because finding
- // two distinct doc names that produce the same sha256 8-hex prefix
- // is infeasible. The unit test pins the *behavior* a real collision
- // would trigger — first value wins the docNameMap slot; later distinct
- // colliding values are surfaced separately so the user does not silently
- // lose one original from the inverse map.
- const ctx = {
- contentDir: '/tmp/c',
- docNameMap: {} as Record<string, string>,
- originalToHashed: new Map<string, string>(),
- docNameCollisions: {} as Record<string, string[]>,
- };
- _recordHashForTests(ctx, 'first-value', 'collide');
- _recordHashForTests(ctx, 'second-value', 'collide');
- _recordHashForTests(ctx, 'third-value', 'collide');
- // Repeat shouldn't double-record.
- _recordHashForTests(ctx, 'second-value', 'collide');
- expect(ctx.docNameMap.collide).toBe('first-value');
- expect(ctx.docNameCollisions.collide).toEqual(['second-value', 'third-value']);
+ expect(JSON.parse(readStaged(stagingDir, 'logs/server-current.jsonl').trim()).msg).toBe('abc');
});
- test('repeated record of the same value is a no-op (idempotent)', () => {
- const ctx = {
- contentDir: '/tmp/c',
- docNameMap: {} as Record<string, string>,
- originalToHashed: new Map<string, string>(),
- docNameCollisions: {} as Record<string, string[]>,
- };
- _recordHashForTests(ctx, 'value', 'h');
- _recordHashForTests(ctx, 'value', 'h');
- expect(ctx.docNameMap.h).toBe('value');
- expect(ctx.docNameCollisions).toEqual({});
- });
-
- test('RedactStagedBundleResult surfaces an empty docNameCollisions when nothing collides', () => {
- // No collision-free workspace should pay for collision tracking; the
- // field is present on the result type so consumers can rely on it,
- // but should be an empty object when no real collision occurred.
- const stagingDir = mkdtempSync(resolve(tmpdir(), 'ok-redact-collision-'));
- tmpDirs.push(stagingDir);
- mkdirSync(join(stagingDir, 'telemetry'));
- mkdirSync(join(stagingDir, 'logs'));
- mkdirSync(join(stagingDir, 'state'));
- writeFileSync(
- join(stagingDir, 'telemetry', 'spans-current.jsonl'),
- `${JSON.stringify({ 'doc.name': 'unique-doc' })}\n`,
- );
- const result: RedactStagedBundleResult = redactStagedBundle({
- stagingDir,
- contentDir: '/nonexistent',
- });
- expect(result.docNameCollisions).toEqual({});
+ test('empty staging dir is a no-op', () => {
+ const stagingDir = makeStagingDir();
+ expect(() => redactStagedBundle({ stagingDir, contentDir: '/x' })).not.toThrow();
});
});
describe('redactStagedBundle — process/ subdirectory', () => {
- test('strips content-dir prefix from process/metadata.json', () => {
+ test('masks the content-dir prefix in process/metadata.json', () => {
const stagingDir = makeStagingDir();
mkdirSync(join(stagingDir, 'process'));
const contentDir = '/Users/jane/secret-vault';
@@ -610,7 +298,7 @@ describe('redactStagedBundle — process/ subdirectory', () => {
expect(after.pid).toBe(12345);
});
- test('strips content-dir prefix from process/lsof.txt', () => {
+ test('masks the content-dir prefix in process/lsof.txt', () => {
const stagingDir = makeStagingDir();
mkdirSync(join(stagingDir, 'process'));
const contentDir = '/Users/jane/secret-vault';
@@ -627,81 +315,17 @@ describe('redactStagedBundle — process/ subdirectory', () => {
expect(after).toContain('<CONTENT_DIR>');
expect(after).toContain('/usr/bin/node');
});
-
- test('hashes doc.name values inside process/*.jsonl files', () => {
- const stagingDir = makeStagingDir();
- mkdirSync(join(stagingDir, 'process'));
- const line = JSON.stringify({ 'doc.name': 'sensitive-folder/note' });
- writeStaged(stagingDir, 'process/process-stats.jsonl', `${line}\n`);
-
- redactStagedBundle({ stagingDir, contentDir: '/no-match' });
-
- const after = readStaged(stagingDir, 'process/process-stats.jsonl').trim();
- const parsed = JSON.parse(after);
- expect(parsed['doc.name']).toMatch(/^doc:[0-9a-f]{8}$/);
- });
-
- test('substring-scrubs doc names from a corrupt state/agent-presence.json under --redact', () => {
- const stagingDir = makeStagingDir();
- const contentDir = '/Users/test/notes';
- const secretDoc = 'private-folder/auth-doc';
-
- // Telemetry walked FIRST populates ctx.originalToHashed via the
- // OTLP attribute-pair walker, so the substring scrub knows what
- // literal to look for once the JSON walker hits the corrupt state.
- const otlpLine = JSON.stringify({
- resourceSpans: [
- {
- scopeSpans: [
- {
- spans: [{ attributes: [{ key: 'doc.name', value: { stringValue: secretDoc } }] }],
- },
- ],
- },
- ],
- });
- writeStaged(stagingDir, 'telemetry/spans-current.jsonl', `${otlpLine}\n`);
-
- const torn = `{ "active-doc": "${secretDoc}", "contentDir": "${contentDir}", "uptimeMs": 12345, /* corrupt`;
- writeStaged(stagingDir, 'state/agent-presence.json', torn);
-
- const result = redactStagedBundle({ stagingDir, contentDir });
-
- const after = readStaged(stagingDir, 'state/agent-presence.json');
- expect(after).not.toContain(secretDoc);
- expect(after).not.toContain(contentDir);
- expect(after).toContain('<CONTENT_DIR>');
- expect(after).toMatch(/doc:[0-9a-f]{8}/);
- expect(Object.values(result.docNameMap)).toContain(secretDoc);
- });
});
describe('redactStagedBundle — cross-platform basename dispatch', () => {
test('stdlib pin: node:path.win32.basename strips backslash-joined Windows paths to the file name', async () => {
- // Stdlib documentation pin — NOT an end-to-end test of the production
- // dispatch through redactStagedBundle. The production dispatch (with
- // POSIX paths) is covered by the "replaces contentDir in state/
- // agent-presence.json walker pass" test above and the corrupt-
- // state-file test in the process/ describe block; both call
- // redactStagedBundle and assert the JSON walker route fires (doc.name
- // hashed). The Windows leg of the dispatch can't be exercised from a
- // macOS host (Node's default `import { basename } from 'node:path'`
- // resolves to path.posix.basename at runtime; only path.win32.basename
- // honors backslashes regardless of host), so this test pins the
- // stdlib contract the production fix relies on — when Node runs on
- // Windows, the same `import { basename }` resolves to path.win32.basename
- // and the dispatch routes correctly.
+ // Stdlib documentation pin — the production dispatch routes state files to
+ // the JSON walker by basename, and Node's default `basename` resolves to
+ // path.win32 on Windows. Can't exercise the Windows leg from a POSIX host,
+ // so this pins the stdlib contract the dispatch relies on.
const { posix, win32 } = await import('node:path');
- expect(win32.basename('C:\\Users\\jane\\stage\\state\\agent-presence.json')).toBe(
- 'agent-presence.json',
- );
expect(win32.basename('C:\\stage\\state\\runtime.json')).toBe('runtime.json');
- // POSIX path is unchanged on both variants (no regression).
- expect(posix.basename('/Users/jane/stage/state/agent-presence.json')).toBe(
- 'agent-presence.json',
- );
- expect(win32.basename('/Users/jane/stage/state/agent-presence.json')).toBe(
- 'agent-presence.json',
- );
+ expect(posix.basename('/Users/jane/stage/state/runtime.json')).toBe('runtime.json');
+ expect(win32.basename('/Users/jane/stage/state/runtime.json')).toBe('runtime.json');
});
});
diff --git a/packages/cli/src/diagnose/bundle-redact.ts b/packages/cli/src/diagnose/bundle-redact.ts
index 184a456d3..c77f76179 100644
--- a/packages/cli/src/diagnose/bundle-redact.ts
+++ b/packages/cli/src/diagnose/bundle-redact.ts
@@ -1,42 +1,28 @@
/**
- * Bundle redactor. Walks the staged copies of telemetry / log / state files
- * and applies two transforms:
- *
- * 1. Doc-name hashing — values keyed by `doc.name` (OTLP attribute-pair shape
- * `{key, value:{stringValue}}` and Pino-flat `{ "doc.name": "..." }`)
- * become `doc:<8 hex>`, derived from sha256(value) truncated to
- * 8 hex chars.
- *
- * 2. Content-dir prefix substitution — the absolute content-dir path,
- * wherever it appears as a substring of any string value, is replaced
- * with the literal token `<CONTENT_DIR>`.
+ * Bundle content-dir masker. Walks the staged copies of telemetry / log / state
+ * files and replaces the absolute content-dir path, wherever it appears as a
+ * substring of any string value, with the literal token `<CONTENT_DIR>` — so a
+ * shared bundle doesn't leak the user's home-directory layout.
*
* Mutates the staged copies in place; the originals under
* `<contentDir>/.ok/local/{telemetry,logs}/` are untouched — the collector
* already stages copies before invoking this module.
*
- * Stable per bundle: the same input value always hashes to the same output
- * within one invocation, and only one inverse-map entry is produced per
- * distinct input. The map is returned for the caller (collectBundle) to
- * persist into `manifest.json.redaction.docNameMap`.
+ * Doc names / titles are NOT anonymized here: they ship raw under the user's
+ * explicit Detailed-diagnostics consent. Credentials are scrubbed by the
+ * separate secret-pattern pass (`scrubStagedSecrets`), which rides the same
+ * `redact` switch this masker does. Every sharing surface (`ok bug-report`,
+ * the in-app bug report) pins that switch on; `ok diagnose bundle --no-redact`
+ * is the one opt-out, and it produces a deliberately raw local dump where a
+ * token stays legible because a bundle that quietly mangles credentials cannot
+ * be used to diagnose an auth failure. The `ok diagnose bundle` consent
+ * summary states which of the two the user is about to write.
*/
-import { createHash } from 'node:crypto';
import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { basename, join } from 'node:path';
const CONTENT_DIR_TOKEN = '<CONTENT_DIR>';
-const HASH_PREFIX = 'doc:';
-const HASH_HEX_LEN = 8;
-// Keys whose values are treated as doc-name-shaped. The OTLP attribute pair
-// form sets `key` to one of these and stores the value under `value.stringValue`;
-// the Pino flat form sets the key directly on the log record. Single source
-// for both shapes — extending DOC_NAME_KEYS covers both at once. `currentDoc`
-// is the workspace-relative doc path carried by `agent-presence.json` entries;
-// hashing it keeps a redacted presence artifact from leaking the doc a human
-// was editing (same anonymization guarantee the `doc.name`-keyed effects
-// artifact already gets).
-const DOC_NAME_KEYS = new Set(['doc.name', 'currentDoc']);
export interface RedactStagedBundleOpts {
/** Absolute path to the staging dir (contains telemetry/, logs/, state/). */
@@ -45,72 +31,8 @@ export interface RedactStagedBundleOpts {
contentDir: string;
}
-export interface RedactStagedBundleResult {
- /** Stable per-bundle inverse map: hashed → original value. */
- docNameMap: Record<string, string>;
- /**
- * Collisions detected while building `docNameMap`. Keyed by the colliding
- * hash; value is the list of *additional* originals (beyond the one stored
- * in `docNameMap`) that hashed to the same 8-hex prefix. Empty `{}` when
- * no collision occurred. With 32 bits of hash space, collisions are
- * vanishingly rare for typical workspaces (<1k doc names), but recording
- * them keeps the contract honest for very large corpora and prevents
- * silent loss of an original from the inverse map.
- */
- docNameCollisions: Record<string, string[]>;
-}
-
interface RedactCtx {
contentDir: string;
- docNameMap: Record<string, string>;
- originalToHashed: Map<string, string>;
- docNameCollisions: Record<string, string[]>;
-}
-
-function hashDocName(value: string): string {
- // sha256 truncated to 8 hex (32 bits). The token is ephemeral: its inverse
- // map ships inside the same bundle, so only per-bundle determinism and low
- // collision probability matter (typical workspaces carry <1k doc names), not
- // a specific algorithm or byte layout. A fixed-length digest is required
- // because Node's OpenSSL rejects a BLAKE2 `outputLength` option
- // (ERR_OSSL_EVP_NOT_XOF_OR_INVALID_LENGTH), which the published Node CLI hits.
- const digest = createHash('sha256').update(value).digest('hex');
- return `${HASH_PREFIX}${digest.slice(0, HASH_HEX_LEN)}`;
-}
-
-/**
- * Record a value under a hash in the inverse map. First value wins the
- * `docNameMap[hash]` slot; subsequent distinct values that hash to the same
- * key land in `docNameCollisions[hash]` so they're never silently lost.
- * Idempotent: repeating the same value is a no-op.
- *
- * Exported as `_recordHashForTests` for collision-path unit testing — real
- * 32-bit hash collisions are infeasible to generate as test fixtures.
- */
-function recordHash(ctx: RedactCtx, value: string, hashed: string): void {
- const prev = ctx.docNameMap[hashed];
- if (prev === undefined) {
- ctx.docNameMap[hashed] = value;
- return;
- }
- if (prev === value) return;
- const existing = ctx.docNameCollisions[hashed];
- if (existing) {
- if (!existing.includes(value)) existing.push(value);
- } else {
- ctx.docNameCollisions[hashed] = [value];
- }
-}
-
-export const _recordHashForTests = recordHash;
-
-function hashOrLookup(value: string, ctx: RedactCtx): string {
- const cached = ctx.originalToHashed.get(value);
- if (cached !== undefined) return cached;
- const hashed = hashDocName(value);
- ctx.originalToHashed.set(value, hashed);
- recordHash(ctx, value, hashed);
- return hashed;
}
function replaceContentDir(value: string, contentDir: string): string {
@@ -127,18 +49,11 @@ function isObject(v: unknown): v is Record<string, unknown> {
}
/**
- * Recursively redact a parsed JSON node. Returns a new tree; does not mutate
- * the input. Two key transforms:
- *
- * - OTLP attribute-pair: `{key: "doc.name", value: {stringValue: X}}`
- * becomes `{key: "doc.name", value: {stringValue: doc:<8hex>(X)}}`. The
- * hash short-circuits any further descent into `value.stringValue` so the
- * prefix-substitution pass never sees the secret.
- * - Pino flat: any property whose key is in DOC_NAME_KEYS and whose value
- * is a string is hashed in place.
- *
- * All other strings get the content-dir substring substitution; non-string
- * leaves pass through.
+ * Recursively mask a parsed JSON node. Returns a new tree; does not mutate the
+ * input. Every string leaf gets the content-dir substring substitution; the
+ * structural walk (rather than a whole-file string replace) keeps the mask
+ * correct when the path is JSON-escaped, e.g. a backslash-separated Windows
+ * path stored as `\\` inside a JSON string.
*/
function redactValue(node: unknown, ctx: RedactCtx): unknown {
if (typeof node === 'string') {
@@ -150,57 +65,13 @@ function redactValue(node: unknown, ctx: RedactCtx): unknown {
if (!isObject(node)) {
return node;
}
-
- const otlpStringValue =
- typeof node.key === 'string' &&
- DOC_NAME_KEYS.has(node.key) &&
- isObject(node.value) &&
- typeof (node.value as Record<string, unknown>).stringValue === 'string'
- ? ((node.value as Record<string, unknown>).stringValue as string)
- : null;
-
const result: Record<string, unknown> = {};
for (const [k, v] of Object.entries(node)) {
- if (otlpStringValue !== null && k === 'value' && isObject(v)) {
- const hashed = hashOrLookup(otlpStringValue, ctx);
- result[k] = { ...v, stringValue: hashed };
- } else if (DOC_NAME_KEYS.has(k) && typeof v === 'string') {
- result[k] = hashOrLookup(v, ctx);
- } else {
- result[k] = redactValue(v, ctx);
- }
+ result[k] = redactValue(v, ctx);
}
return result;
}
-/**
- * Best-effort substring scrub for content the JSON walker couldn't descend
- * into. Replaces every previously-seen doc name (as recorded in
- * `ctx.originalToHashed` by earlier-walked files) with its hashed value, so a
- * corrupt or torn JSON / JSONL fragment doesn't leak names the
- * structural walker would have masked. The pipeline always walks
- * `telemetry`/`logs`/`process` before `state`, so by the time a state file's
- * unparseable fallback runs the map is populated for any doc that appeared in
- * a structured record.
- *
- * Iteration order is longest-first to avoid shadow-mask races when one doc
- * name is a substring of another (e.g. `notes/foo` vs `notes/foo-bar`):
- * substituting `notes/foo` first would mutate the longer literal mid-scan.
- */
-function substringScrubDocNames(content: string, ctx: RedactCtx): string {
- if (ctx.originalToHashed.size === 0) return content;
- const ordered = Array.from(ctx.originalToHashed.entries()).sort(
- ([a], [b]) => b.length - a.length,
- );
- let out = content;
- for (const [original, hashed] of ordered) {
- if (original.length === 0) continue;
- if (!out.includes(original)) continue;
- out = out.split(original).join(hashed);
- }
- return out;
-}
-
function redactJsonlFile(filePath: string, ctx: RedactCtx): void {
const content = readFileSync(filePath, 'utf-8');
if (content.length === 0) return;
@@ -238,15 +109,11 @@ function redactJsonFile(filePath: string, ctx: RedactCtx): void {
const trailingNewline = content.endsWith('\n') ? '\n' : '';
writeFileSync(filePath, `${JSON.stringify(redacted, null, 2)}${trailingNewline}`);
} catch {
- // Whole-file JSON parse failure (truncated write, manual edit, etc.):
- // fall back to substring scrubs so a corrupt state file still has the
- // content-dir prefix substituted and any doc name already collected by
- // the structural walker masked. Without this, an `agent-presence.json`
- // torn mid-write would leak doc names the --redact flag promised to
- // hide.
- const contentDirReplaced = replaceContentDir(content, ctx.contentDir);
- const docNameScrubbed = substringScrubDocNames(contentDirReplaced, ctx);
- if (docNameScrubbed !== content) writeFileSync(filePath, docNameScrubbed);
+ // Whole-file JSON parse failure (truncated write, manual edit, etc.): fall
+ // back to a plain substring substitution so a corrupt state file still has
+ // the content-dir prefix masked.
+ const replaced = replaceContentDir(content, ctx.contentDir);
+ if (replaced !== content) writeFileSync(filePath, replaced);
}
}
@@ -262,14 +129,13 @@ function walkDirFiles(dir: string): string[] {
.filter((e) => e.isFile())
.map((e) => join(dir, e.name));
} catch {
- // Dir doesn't exist (nothing staged for that subdir) — nothing to redact.
+ // Dir doesn't exist (nothing staged for that subdir) — nothing to mask.
return [];
}
}
-// State files that are JSON-shaped get a full walker pass (agent-presence and
-// agent-effects may carry per-doc `doc.name` fields; runtime.json may carry
-// the contentDir). Other state files get substring-only substitution.
+// State files that are JSON-shaped get a full walker pass (runtime.json may
+// carry the contentDir). Other state files get whole-content substitution.
const STATE_JSON_FILES = new Set(['agent-presence.json', 'agent-effects.json', 'runtime.json']);
/**
@@ -283,19 +149,14 @@ export function isRotatedLogPath(filePath: string): boolean {
/**
* The user-level logs are pino JSONL that happen to carry a `.log` suffix, so
* routing them by extension alone would give them the substring-only pass and
- * silently drop the doc-name hashing the full level's `--redact` promises.
+ * silently skip the per-line credential scrub.
*/
function isLineDelimitedJson(filePath: string): boolean {
return filePath.endsWith('.jsonl') || filePath.endsWith('.log') || isRotatedLogPath(filePath);
}
-export function redactStagedBundle(opts: RedactStagedBundleOpts): RedactStagedBundleResult {
- const ctx: RedactCtx = {
- contentDir: opts.contentDir,
- docNameMap: {},
- originalToHashed: new Map(),
- docNameCollisions: {},
- };
+export function redactStagedBundle(opts: RedactStagedBundleOpts): void {
+ const ctx: RedactCtx = { contentDir: opts.contentDir };
for (const subdir of ['telemetry', 'logs', 'process']) {
for (const filePath of walkDirFiles(join(opts.stagingDir, subdir))) {
@@ -310,18 +171,13 @@ export function redactStagedBundle(opts: RedactStagedBundleOpts): RedactStagedBu
}
for (const filePath of walkDirFiles(join(opts.stagingDir, 'state'))) {
- // basename, not manual slice — node:path's basename handles both POSIX
- // and Windows separators, so a backslash-joined staging path on Windows
- // still routes agent-presence.json / runtime.json to the doc-name-
- // hashing JSON walker. Manual `lastIndexOf('/')` returns -1 on
- // backslash paths, leaving `base` as the full absolute path, which
- // misses the STATE_JSON_FILES set and silently falls through to the
- // substring-only walker.
+ // basename, not manual slice — node:path's basename handles both POSIX and
+ // Windows separators, so a backslash-joined staging path on Windows still
+ // routes runtime.json to the JSON walker. Manual `lastIndexOf('/')` returns
+ // -1 on backslash paths, leaving `base` as the full absolute path, which
+ // misses STATE_JSON_FILES and silently falls through to the plain walker.
const base = basename(filePath);
if (filePath.endsWith('.jsonl')) {
- // JSONL state artifacts (watcher-recent.jsonl) carry per-line
- // `doc.name` keys; the line-wise walker hashes them like the
- // telemetry/log JSONLs.
redactJsonlFile(filePath, ctx);
} else if (STATE_JSON_FILES.has(base)) {
redactJsonFile(filePath, ctx);
@@ -329,6 +185,4 @@ export function redactStagedBundle(opts: RedactStagedBundleOpts): RedactStagedBu
redactPlainFile(filePath, ctx);
}
}
-
- return { docNameMap: ctx.docNameMap, docNameCollisions: ctx.docNameCollisions };
}
diff --git a/packages/cli/src/diagnose/bundle.test.ts b/packages/cli/src/diagnose/bundle.test.ts
index 9b03d7d2e..b1b84972c 100644
--- a/packages/cli/src/diagnose/bundle.test.ts
+++ b/packages/cli/src/diagnose/bundle.test.ts
@@ -20,7 +20,12 @@ import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { afterEach, describe, expect, test } from 'vitest';
import { ZipFile } from 'yazl';
-import { type CollectBundleDeps, collectBundle, writeBundle } from './bundle.ts';
+import {
+ CHECKPOINT_REF_GIT_FORMAT,
+ type CollectBundleDeps,
+ collectBundle,
+ writeBundle,
+} from './bundle.ts';
// ---------------------------------------------------------------------------
// Fixture helpers
@@ -72,11 +77,11 @@ function writeAt(contentDir: string, relPath: string, body: string): void {
// ---------------------------------------------------------------------------
describe('collectBundle — smoke', () => {
- test('produces a v1 manifest on a fresh content-dir with no server', async () => {
+ test('produces a v2 manifest on a fresh content-dir with no server', async () => {
const contentDir = makeTmpDir();
const collected = await collectBundle({ contentDir, deps: makeDeterministicDeps() });
- expect(collected.manifest.schemaVersion).toBe(1);
+ expect(collected.manifest.schemaVersion).toBe(2);
expect(collected.manifest.createdAt).toBe('2026-05-28T14:22:01.000Z');
expect(collected.manifest.ok).toEqual({
version: '0.7.99',
@@ -86,7 +91,7 @@ describe('collectBundle — smoke', () => {
});
expect(collected.manifest.host).toEqual({ desktop: null });
expect(collected.manifest.serverStatus).toBe('not-running');
- expect(collected.manifest.redaction).toEqual({ applied: false, docNameMapSidecar: null });
+ expect(collected.manifest.redaction).toEqual({ applied: false });
// state/runtime.json + state/server-status.txt always staged.
const paths = collected.manifest.files.map((f) => f.path);
@@ -673,6 +678,53 @@ describe('collectBundle — summary', () => {
});
});
+// ---------------------------------------------------------------------------
+// loss-capture ring staging (full/Detailed tier)
+// ---------------------------------------------------------------------------
+
+describe('collectBundle — loss-capture ring', () => {
+ test('stages the content-loss ring under state/ with its raw doc name intact', async () => {
+ const contentDir = makeTmpDir();
+ const lossEvent = JSON.stringify({
+ ts: 1,
+ schemaVersion: 1,
+ seq: 1,
+ event: 'guard-defer',
+ docName: 'meetings/plan',
+ writerId: null,
+ site: 'site-2',
+ lostLen: 12,
+ digest: 'abc12345',
+ });
+ writeAt(contentDir, '.ok/local/loss-capture/loss-current.jsonl', `${lossEvent}\n`);
+ writeAt(contentDir, '.ok/local/loss-capture/loss-prev.jsonl', `${lossEvent}\n`);
+
+ const collected = await collectBundle({
+ contentDir,
+ redact: true,
+ deps: makeDeterministicDeps(),
+ });
+ const paths = collected.manifest.files.map((f) => f.path);
+ expect(paths).toContain('state/loss-current.jsonl');
+ expect(paths).toContain('state/loss-prev.jsonl');
+
+ // The ring's doc name ships raw — only the content-dir path is masked, and
+ // the ring carries no content-dir path.
+ const staged = readFileSync(join(collected.stagingDir, 'state', 'loss-current.jsonl'), 'utf-8');
+ expect(staged).toContain('meetings/plan');
+ collected.cleanup();
+ });
+
+ test('omits the loss ring when no producer has recorded an event', async () => {
+ const contentDir = makeTmpDir();
+ const collected = await collectBundle({ contentDir, deps: makeDeterministicDeps() });
+ const paths = collected.manifest.files.map((f) => f.path);
+ expect(paths).not.toContain('state/loss-current.jsonl');
+ expect(paths).not.toContain('state/loss-prev.jsonl');
+ collected.cleanup();
+ });
+});
+
// ---------------------------------------------------------------------------
// writeBundle
// ---------------------------------------------------------------------------
@@ -730,7 +782,7 @@ describe('writeBundle', () => {
`unzip -q ${JSON.stringify(outputPath)} manifest.json -d ${JSON.stringify(extractDir)}`,
);
const parsed = JSON.parse(readFileSync(join(extractDir, 'manifest.json'), 'utf-8'));
- expect(parsed.schemaVersion).toBe(1);
+ expect(parsed.schemaVersion).toBe(2);
expect(parsed.contentDir.pathSha256).toBe(collected.manifest.contentDir.pathSha256);
expect(parsed.files).toEqual(collected.manifest.files);
collected.cleanup();
@@ -861,3 +913,17 @@ describe('collectBundle — staging cleanup on throw', () => {
}
});
});
+
+describe('checkpoint-ref staging format (privacy enforcement)', () => {
+ test('stages only the content-free commit subject, never the body', () => {
+ // The REAL privacy enforcement for checkpoint bundle staging: the loss
+ // kinds' commit BODY carries verbatim lost-content substrings, so the
+ // for-each-ref format must expose only the content-free subject. This locks
+ // that enforcement point — the checkpoint-kind registry's bundleExposure
+ // attribute is advisory and is not consulted by the staging path.
+ expect(CHECKPOINT_REF_GIT_FORMAT).toContain('%(contents:subject)');
+ for (const bodyToken of ['%(contents:body)', '%(contents)', '%(body)', '%(trailers)']) {
+ expect(CHECKPOINT_REF_GIT_FORMAT).not.toContain(bodyToken);
+ }
+ });
+});
diff --git a/packages/cli/src/diagnose/bundle.ts b/packages/cli/src/diagnose/bundle.ts
index bac65421a..571f45a2c 100644
--- a/packages/cli/src/diagnose/bundle.ts
+++ b/packages/cli/src/diagnose/bundle.ts
@@ -41,11 +41,7 @@ import { ZipFile } from 'yazl';
import type { BundleExtraFile, BundleLogger } from '../commands/bug-report-bundle.ts';
import { redactContent } from '../commands/bug-report-redact.ts';
import { PACKAGE_VERSION } from '../constants.ts';
-import {
- isRotatedLogPath,
- type RedactStagedBundleResult,
- redactStagedBundle,
-} from './bundle-redact.ts';
+import { isRotatedLogPath, redactStagedBundle } from './bundle-redact.ts';
// ---------------------------------------------------------------------------
// Manifest schema
@@ -59,8 +55,14 @@ import {
// exception: it is exported as the value type of the `readDesktopEnv` seam so
// `collectReportBundle` callers (the desktop app) can inject host metadata.
-/** Schema version pinned at 1 for v1 bundles. */
-type BundleSchemaVersion = 1;
+/**
+ * Manifest contract version. Bumped to 2 when `redaction` dropped
+ * `docNameMapSidecar` / `docNameCollisions` alongside the doc-name
+ * anonymization they described: a consumer that reads either field off a v2
+ * manifest gets `undefined` rather than a value, so the removal has to be
+ * legible from the version rather than inferred from a missing key.
+ */
+type BundleSchemaVersion = 2;
export interface DesktopMetadata {
electronVersion: string;
@@ -90,23 +92,8 @@ interface BundleSecretScrub {
}
interface BundleRedaction {
+ /** Whether the content-dir path mask ran over the staged copies. */
applied: boolean;
- /**
- * Filename of the inverse-map sidecar written next to the zip on the user's
- * own machine — NOT included in the zip. The recipient sees only the
- * filename for reference; the actual `<hashed> → <original>` map stays
- * with the user so they can de-anonymize a bundle they sent without giving
- * the recipient the ability to reverse it.
- */
- docNameMapSidecar: string | null;
- /**
- * Hashes for which two or more distinct originals were observed during
- * redaction. Each value is the list of additional originals beyond the
- * one stored in the sidecar map. Field is absent when no collision
- * occurred; present and non-empty means the sidecar map is lossy for
- * those hashes.
- */
- docNameCollisions?: Record<string, string[]>;
/**
* Audit of the secret-pattern scrub (the `ok bug-report` scrub applied to
* the staged copies). Present only when the collector ran with
@@ -172,13 +159,11 @@ export interface CollectBundleOpts {
/** Optional path to an existing `ok diagnose process` output dir; copied to `process/` in the bundle. */
processDir?: string;
/**
- * Apply `--redact` to the staged copies: hash `doc.name` attribute values
- * with sha256(value).slice(0,8), replace the absolute content-dir
- * prefix in any string field with the literal `<CONTENT_DIR>` token, and
- * record the inverse map in `manifest.redaction.docNameMap`. The original
- * on-disk files under `<contentDir>/.ok/local/{telemetry,logs}/` are
- * untouched — the collector copies them first; the redactor only sees the
- * staged copies.
+ * Mask the absolute content-dir prefix in any staged string field with the
+ * literal `<CONTENT_DIR>` token (so a shared bundle doesn't leak the user's
+ * home-directory layout). Doc names ship raw. The original on-disk files
+ * under `<contentDir>/.ok/local/{telemetry,logs}/` are untouched — the
+ * collector copies them first; the masker only sees the staged copies.
*/
redact?: boolean;
/**
@@ -290,15 +275,6 @@ export interface CollectedBundle {
stagingDir: string;
manifest: BundleManifest;
summary: BundleSummary;
- /**
- * In-memory inverse map produced when `--redact` was applied. Held here so
- * `writeBundle` can persist it to a sidecar file next to the zip — NEVER
- * inside the zip. `null` when redaction was not applied.
- */
- redactionMapPayload: {
- docNameMap: Record<string, string>;
- docNameCollisions: Record<string, string[]>;
- } | null;
/** Removes the staging dir. Idempotent. */
cleanup: () => void;
}
@@ -324,10 +300,13 @@ export interface WriteBundleOpts {
const TELEMETRY_REL = ['.ok', 'local', 'telemetry'] as const;
const LOGS_REL = ['.ok', 'local', 'logs'] as const;
+const LOSS_CAPTURE_REL = ['.ok', 'local', 'loss-capture'] as const;
const SPANS_CURRENT = 'spans-current.jsonl';
const SPANS_PREVIOUS = 'spans-prev.jsonl';
const LOGS_CURRENT = 'server-current.jsonl';
const LOGS_PREVIOUS = 'server-prev.jsonl';
+const LOSS_CURRENT = 'loss-current.jsonl';
+const LOSS_PREVIOUS = 'loss-prev.jsonl';
function spansCurrentPath(projectDir: string): string {
return join(projectDir, ...TELEMETRY_REL, SPANS_CURRENT);
@@ -345,16 +324,31 @@ function logsPreviousPath(projectDir: string): string {
return join(projectDir, ...LOGS_REL, LOGS_PREVIOUS);
}
+// Content-loss ring — the bridge's content-free loss-class event log. Rides the
+// full/Detailed tier only. Path layout mirrors the server's loss-capture sink;
+// inlined here for the same reason as the spans/logs layout above (the on-disk
+// `.ok/local/` layout is the contract, not the writer's types).
+function lossCaptureCurrentPath(projectDir: string): string {
+ return join(projectDir, ...LOSS_CAPTURE_REL, LOSS_CURRENT);
+}
+
+function lossCapturePreviousPath(projectDir: string): string {
+ return join(projectDir, ...LOSS_CAPTURE_REL, LOSS_PREVIOUS);
+}
+
// Exposed so a cross-package parity test can assert these inlined paths stay
-// equivalent to the server's `telemetry-file-sink.ts` exports — the layout is
-// a contract, but no compiler check catches drift between
-// the two sites today (the duplication is intentional per dependency-direction
-// concerns).
+// equivalent to the server's `telemetry-file-sink.ts` / `loss-capture.ts`
+// exports — the layout is a contract, but no compiler check catches drift
+// between the two sites today (the duplication is intentional per
+// dependency-direction concerns). Every inlined path helper above belongs in
+// here: one left out is one whose rename silently stops harvesting its source.
export const _pathHelpersForTests = {
spansCurrentPath,
spansPreviousPath,
logsCurrentPath,
logsPreviousPath,
+ lossCaptureCurrentPath,
+ lossCapturePreviousPath,
};
// ---------------------------------------------------------------------------
@@ -443,14 +437,23 @@ function defaultReadShadowHead(contentDir: string): string | null {
return result.stdout ?? '';
}
+/**
+ * The git `for-each-ref` format for staging checkpoint refs: subject ONLY.
+ * Checkpoint commit BODIES carry an `ok-checkpoint-v1` JSON line with the doc
+ * name and (for the loss kinds) verbatim lost-content substrings; the subject
+ * is a content-free label. Staging the body would exfiltrate the user's
+ * document, so this format — not the checkpoint-kind registry's advisory
+ * `bundleExposure` attribute — is the actual privacy enforcement point, guarded
+ * against a body/trailers drift by a format test.
+ */
+export const CHECKPOINT_REF_GIT_FORMAT =
+ '%(refname)%09%(creatordate:iso-strict)%09%(contents:subject)';
+
function defaultReadCheckpointRefs(contentDir: string): string | null {
const shadowDir = join(contentDir, '.git', 'ok');
if (!existsSync(shadowDir)) return null;
- // `%(contents:subject)` only: checkpoint commit bodies carry an
- // `ok-checkpoint-v1` JSON line with the doc name and (for merge-loss
- // checkpoints) lost-content substrings — the subject is a content-free
- // label, so restricting the format keeps the artifact safe to stage as
- // plain text under the same redaction rules as shadow-head.txt.
+ // Subject-only (see CHECKPOINT_REF_GIT_FORMAT): keeps the staged artifact safe
+ // as plain text under the same redaction rules as shadow-head.txt.
const result = spawnSync(
'git',
[
@@ -459,7 +462,7 @@ function defaultReadCheckpointRefs(contentDir: string): string | null {
'for-each-ref',
'--sort=-creatordate',
`--count=${CHECKPOINT_REF_LIMIT}`,
- '--format=%(refname)%09%(creatordate:iso-strict)%09%(contents:subject)',
+ `--format=${CHECKPOINT_REF_GIT_FORMAT}`,
'refs/checkpoints/',
],
withHiddenWindowsConsole({ encoding: 'utf-8', timeout: 2000 }),
@@ -784,6 +787,16 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
writeFileSync(join(stagingDir, 'state', 'checkpoint-refs.txt'), checkpointRefs);
}
+ // Content-loss ring — content-free-by-schema loss-class events (which sites
+ // deferred / detected / froze / checkpointed, correlated by checkpoint sha).
+ // The "was anything silently lost, and where" triage artifact, paired with
+ // checkpoint-refs above. Present only once a producer has recorded an event.
+ stageFileIfPresent(lossCaptureCurrentPath(projectDir), join(stagingDir, 'state', LOSS_CURRENT));
+ stageFileIfPresent(
+ lossCapturePreviousPath(projectDir),
+ join(stagingDir, 'state', LOSS_PREVIOUS),
+ );
+
// last-spawn-error.log (Electron host writes this when a spawn fails).
stageFileIfPresent(
join(lockDir, 'last-spawn-error.log'),
@@ -831,13 +844,12 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
cpSync(opts.processDir, processDest, { recursive: true });
}
- // Apply redaction to the staged copies BEFORE the file inventory walk so
- // the recorded bytes/lines reflect post-redaction state. Originals on disk
- // are not touched — only the staged copies in stagingDir. The redactor
- // returns the inverse map for the manifest.
- let redactionResult: RedactStagedBundleResult | null = null;
- if (opts.redact === true) {
- redactionResult = redactStagedBundle({ stagingDir, contentDir });
+ // Mask the content-dir path in the staged copies BEFORE the file inventory
+ // walk so the recorded bytes/lines reflect post-mask state. Originals on
+ // disk are not touched — only the staged copies in stagingDir.
+ const redactApplied = opts.redact === true;
+ if (redactApplied) {
+ redactStagedBundle({ stagingDir, contentDir });
}
// Staged before the scrub so a secret pasted into the note gets caught too.
@@ -885,22 +897,13 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
}
}
- const redaction: BundleRedaction =
- redactionResult !== null
- ? Object.keys(redactionResult.docNameCollisions).length > 0
- ? {
- applied: true,
- docNameMapSidecar: null,
- docNameCollisions: redactionResult.docNameCollisions,
- }
- : { applied: true, docNameMapSidecar: null }
- : { applied: false, docNameMapSidecar: null };
+ const redaction: BundleRedaction = { applied: redactApplied };
if (secretScrub !== null) {
redaction.secretScrub = secretScrub;
}
const manifest: BundleManifest = {
- schemaVersion: 1,
+ schemaVersion: 2,
createdAt: now().toISOString(),
ok: {
version: okVersion(),
@@ -915,7 +918,7 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
// string itself is masked when redaction is on so the bundle doesn't
// leak the user's home directory layout.
pathSha256: hashContentDirPath(contentDir),
- absolutePath: redactionResult !== null ? '<CONTENT_DIR>' : contentDir,
+ absolutePath: redactApplied ? '<CONTENT_DIR>' : contentDir,
},
telemetry: {
localSink,
@@ -946,7 +949,7 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
fileCount: files.length,
docNameCount,
contentDirVisible,
- redacted: redactionResult !== null,
+ redacted: redactApplied,
};
let cleaned = false;
@@ -956,15 +959,7 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
rmSync(stagingDir, { recursive: true, force: true });
};
- const redactionMapPayload =
- redactionResult !== null
- ? {
- docNameMap: redactionResult.docNameMap,
- docNameCollisions: redactionResult.docNameCollisions,
- }
- : null;
-
- return { stagingDir, manifest, summary, redactionMapPayload, cleanup };
+ return { stagingDir, manifest, summary, cleanup };
} catch (err) {
// The cleanup handle only exists on the returned value, so a throw during
// staging is the one path where nobody else can release the tmpdir — and
@@ -989,27 +984,6 @@ export async function writeBundle(opts: WriteBundleOpts): Promise<string> {
);
}
- // When redaction was applied, restamp the staged manifest with the sidecar
- // filename so the recipient sees a pointer (not the map itself). The sidecar
- // is written next to the zip below — outside the zip, on the user's machine
- // only. This preserves the contract: "downstream consumers see only
- // hashes."
- if (collected.redactionMapPayload !== null) {
- const sidecarName = `${basename(outputPath, '.zip')}.docnames.json`;
- const stampedManifest: BundleManifest = {
- ...collected.manifest,
- redaction: {
- ...collected.manifest.redaction,
- applied: true,
- docNameMapSidecar: sidecarName,
- },
- };
- writeFileSync(
- join(collected.stagingDir, 'manifest.json'),
- `${JSON.stringify(stampedManifest, null, 2)}\n`,
- );
- }
-
const zipfile = new ZipFile();
const absStagedFiles = walkStagedFiles(collected.stagingDir);
for (const absPath of absStagedFiles) {
@@ -1018,28 +992,6 @@ export async function writeBundle(opts: WriteBundleOpts): Promise<string> {
}
zipfile.end();
- // Write the inverse-map sidecar next to the zip (NOT inside it). The user
- // keeps this locally so they can de-anonymize their own bundle if they ever
- // need to; the recipient only ever gets the zip. Mode 0o600 because the
- // sidecar contains the exact data --redact was meant to keep private —
- // default umask would leave it world-readable on shared systems.
- if (collected.redactionMapPayload !== null) {
- const sidecarName = `${basename(outputPath, '.zip')}.docnames.json`;
- const sidecarPath = join(parent, sidecarName);
- writeFileSync(
- sidecarPath,
- `${JSON.stringify(
- {
- docNameMap: collected.redactionMapPayload.docNameMap,
- docNameCollisions: collected.redactionMapPayload.docNameCollisions,
- },
- null,
- 2,
- )}\n`,
- { mode: 0o600 },
- );
- }
-
const writer = createWriteStream(outputPath);
zipfile.outputStream.pipe(writer);
await new Promise<void>((resolveWait, rejectWait) => {
diff --git a/packages/cli/src/diagnose/path-parity.test.ts b/packages/cli/src/diagnose/path-parity.test.ts
index 5bdd0e9d4..ce6d7622f 100644
--- a/packages/cli/src/diagnose/path-parity.test.ts
+++ b/packages/cli/src/diagnose/path-parity.test.ts
@@ -1,15 +1,21 @@
/**
* Cross-package path-helper equivalence guard.
*
- * `bundle.ts` inlines path constants for `<contentDir>/.ok/local/telemetry/*`
- * and `<contentDir>/.ok/local/logs/*` rather than importing them from
- * `@inkeep/open-knowledge-server` — the on-disk layout is a stable
- * contract and the CLI should not reach into server internals for runtime
- * code (see the block comment near `bundle.ts`'s path-helper region). The
- * trade-off: if a filename or subdirectory changes in `telemetry-file-sink.ts`,
- * `bundle.ts`'s inlined copies silently desync and bundles stop finding the
- * files. This test guards against that by computing both sets of paths and
- * asserting equivalence — when they drift, this test fails.
+ * `bundle.ts` inlines path constants for `<contentDir>/.ok/local/telemetry/*`,
+ * `<contentDir>/.ok/local/logs/*`, and `<contentDir>/.ok/local/loss-capture/*`
+ * rather than importing them from `@inkeep/open-knowledge-server` — the
+ * on-disk layout is a stable contract and the CLI should not reach into server
+ * internals for runtime code (see the block comment near `bundle.ts`'s
+ * path-helper region). The trade-off: if a filename or subdirectory changes on
+ * the writer side, `bundle.ts`'s inlined copies silently desync and bundles
+ * stop finding the files. This test guards against that by computing both sets
+ * of paths and asserting equivalence — when they drift, this test fails.
+ *
+ * The loss-capture layout is reached through the server module file directly
+ * because the server barrel re-exports the telemetry sink but not
+ * `loss-capture.ts`. That is a test-only reach, and a deliberate one: a guard
+ * that skipped the pair the barrel happens to omit would leave exactly the
+ * newest helpers unguarded.
*/
import {
@@ -19,34 +25,37 @@ import {
spansPreviousPath as serverSpansPreviousPath,
} from '@inkeep/open-knowledge-server';
import { describe, expect, test } from 'vitest';
+import {
+ lossCaptureCurrentPath as serverLossCaptureCurrentPath,
+ lossCapturePreviousPath as serverLossCapturePreviousPath,
+} from '../../../server/src/loss-capture.ts';
import { _pathHelpersForTests } from './bundle.ts';
-describe('CLI bundle path helpers — parity with server telemetry-file-sink', () => {
+describe('CLI bundle path helpers — parity with the server writers', () => {
const fixtures = ['/tmp/content', '/Users/dev/projects/foo', '/var/data/with spaces/dir'];
- for (const contentDir of fixtures) {
- test(`spansCurrentPath(${contentDir}) matches server`, () => {
- expect(_pathHelpersForTests.spansCurrentPath(contentDir)).toBe(
- serverSpansCurrentPath(contentDir),
- );
- });
-
- test(`spansPreviousPath(${contentDir}) matches server`, () => {
- expect(_pathHelpersForTests.spansPreviousPath(contentDir)).toBe(
- serverSpansPreviousPath(contentDir),
- );
- });
+ // Every helper the CLI inlines, paired with the server export it must match.
+ // Adding a helper to `_pathHelpersForTests` without a pair here fails the
+ // coverage test below rather than passing silently.
+ const pairs = {
+ spansCurrentPath: serverSpansCurrentPath,
+ spansPreviousPath: serverSpansPreviousPath,
+ logsCurrentPath: serverLogsCurrentPath,
+ logsPreviousPath: serverLogsPreviousPath,
+ lossCaptureCurrentPath: serverLossCaptureCurrentPath,
+ lossCapturePreviousPath: serverLossCapturePreviousPath,
+ } satisfies Record<keyof typeof _pathHelpersForTests, (contentDir: string) => string>;
- test(`logsCurrentPath(${contentDir}) matches server`, () => {
- expect(_pathHelpersForTests.logsCurrentPath(contentDir)).toBe(
- serverLogsCurrentPath(contentDir),
- );
- });
+ test('every exported CLI path helper is paired with a server export', () => {
+ expect(Object.keys(pairs).sort()).toEqual(Object.keys(_pathHelpersForTests).sort());
+ });
- test(`logsPreviousPath(${contentDir}) matches server`, () => {
- expect(_pathHelpersForTests.logsPreviousPath(contentDir)).toBe(
- serverLogsPreviousPath(contentDir),
- );
- });
+ for (const [name, serverFn] of Object.entries(pairs)) {
+ const cliFn = _pathHelpersForTests[name as keyof typeof _pathHelpersForTests];
+ for (const contentDir of fixtures) {
+ test(`${name}(${contentDir}) matches server`, () => {
+ expect(cliFn(contentDir)).toBe(serverFn(contentDir));
+ });
+ }
}
});
diff --git a/packages/cli/src/report-bundle.test.ts b/packages/cli/src/report-bundle.test.ts
index 5045b58a9..20544f71c 100644
--- a/packages/cli/src/report-bundle.test.ts
+++ b/packages/cli/src/report-bundle.test.ts
@@ -9,6 +9,7 @@ import { execSync } from 'node:child_process';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
+import { SERVER_CRASH_LOG } from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, test } from 'vitest';
import { collectReportBundle as collectReportBundleFromIndex } from './index.ts';
import { collectReportBundle } from './report-bundle.ts';
@@ -76,6 +77,60 @@ function makeFullProjectDir(slug = 'full-proj'): string {
return projectDir;
}
+/**
+ * One realistically-shaped credential per input the STANDARD tier harvests,
+ * paired with the zip entry it must not survive in. The standard tier is
+ * `collectStandardBundle`, a different assembler from the full tier's
+ * `collectBundle` — the full-tier canary does not cover any of these sinks.
+ */
+const STANDARD_PLANTS = {
+ 'logs/desktop.log': 'AKIAIOSFODNN7EXAMPLE',
+ 'local-logs/server-current.jsonl': SECRET,
+ 'lockdir/last-spawn-error.log': 'abcdefghijklmnopqrstuvwxyz0123456789',
+ 'lockdir/server.lock': 'hunter2',
+ [`lockdir/${SERVER_CRASH_LOG}`]: 'sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123',
+ 'note.txt': 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiJ9.s5x8Qk3rTvW2pLmNq7Yz',
+} as const satisfies Record<string, string>;
+
+const PLANTED_NOTE = `it died right after I pasted ${STANDARD_PLANTS['note.txt']}`;
+
+/** Every standard-tier source seeded with its planted credential. */
+function makePlantedStandardProject(): { projectDir: string; userLogsDir: string } {
+ const projectDir = makeTmpDir();
+ const userLogsDir = makeTmpDir();
+ writeAt(projectDir, '.ok/config.yml', 'name: planted-proj\n');
+ // The desktop transport's sink: renderer console output captured into
+ // `~/.ok/logs`, which the standard tier harvests wholesale.
+ writeAt(
+ userLogsDir,
+ 'desktop.log',
+ `{"level":50,"msg":"assume-role ${STANDARD_PLANTS['logs/desktop.log']} denied"}\n`,
+ );
+ // The web transport's sink: the same renderer console output, ingested
+ // through `/api/client-logs` into the project-local server log.
+ writeAt(
+ projectDir,
+ '.ok/local/logs/server-current.jsonl',
+ `{"level":50,"source":"renderer-console","msg":"push failed ${STANDARD_PLANTS['local-logs/server-current.jsonl']}"}\n`,
+ );
+ writeAt(
+ projectDir,
+ '.ok/local/last-spawn-error.log',
+ `spawn failed: Authorization: Bearer ${STANDARD_PLANTS['lockdir/last-spawn-error.log']}\n`,
+ );
+ writeAt(
+ projectDir,
+ '.ok/local/server.lock',
+ `{"pid":1234,"remote":"https://ci:${STANDARD_PLANTS['lockdir/server.lock']}@github.com/o/r.git"}\n`,
+ );
+ writeAt(
+ projectDir,
+ `.ok/local/${SERVER_CRASH_LOG}`,
+ `{"reason":"boot failed","env":"ANTHROPIC_API_KEY=${STANDARD_PLANTS[`lockdir/${SERVER_CRASH_LOG}`]}"}\n`,
+ );
+ return { projectDir, userLogsDir };
+}
+
describe('collectReportBundle — standard level', () => {
test('packages the bug-report content set with level metadata in the summary', async () => {
const projectDir = makeStandardProjectDir();
@@ -149,6 +204,55 @@ describe('collectReportBundle — standard level', () => {
expect(summary.files).toContain('extra/crash.dmp');
});
+ test('canary: no planted credential survives in any standard-tier bundle artifact', async () => {
+ const { projectDir, userLogsDir } = makePlantedStandardProject();
+ const outputPath = join(makeTmpDir(), 'report.zip');
+
+ const { zipPath, summary } = await collectReportBundle({
+ level: 'standard',
+ projectDir,
+ note: PLANTED_NOTE,
+ redact: true,
+ outputPath,
+ userLogsDir,
+ });
+
+ // Every seeded source really did reach the bundle — otherwise the sweep
+ // below would pass by collecting nothing.
+ const entries = listZipEntries(zipPath);
+ for (const entry of Object.keys(STANDARD_PLANTS)) expect(entries).toContain(entry);
+
+ // No text artifact anywhere in the assembled bundle carries any of them.
+ const textEntries = entries.filter((e) => /\.(jsonl?|txt|log|lock|md)$/.test(e));
+ for (const entry of textEntries) {
+ const content = readZipEntry(zipPath, entry);
+ for (const secret of Object.values(STANDARD_PLANTS)) {
+ expect(`${entry}: ${content}`).not.toContain(secret);
+ }
+ }
+ expect(summary.redactedLineCount).toBeGreaterThanOrEqual(Object.keys(STANDARD_PLANTS).length);
+ });
+
+ test('canary control: with the scrub off every planted credential lands verbatim', async () => {
+ const { projectDir, userLogsDir } = makePlantedStandardProject();
+ const outputPath = join(makeTmpDir(), 'report.zip');
+
+ const { zipPath } = await collectReportBundle({
+ level: 'standard',
+ projectDir,
+ note: PLANTED_NOTE,
+ redact: false,
+ outputPath,
+ userLogsDir,
+ });
+
+ // The scrub is the only thing removing them: unredacted, each planted
+ // credential is present in the entry it was planted in.
+ for (const [entry, secret] of Object.entries(STANDARD_PLANTS)) {
+ expect(readZipEntry(zipPath, entry)).toContain(secret);
+ }
+ });
+
test('produces a system-wide bundle when projectDir is omitted', async () => {
const userLogsDir = makeTmpDir();
writeAt(userLogsDir, 'cli.log', 'started\n');
@@ -194,7 +298,7 @@ describe('collectReportBundle — full level', () => {
expect(entries).not.toContain('state/server.lock');
expect(entries).not.toContain('state/agent-presence.json');
const manifest = JSON.parse(readZipEntry(zipPath, 'manifest.json'));
- expect(manifest.schemaVersion).toBe(1);
+ expect(manifest.schemaVersion).toBe(2);
expect(manifest.serverStatus).toBe('not-running');
const paths = manifest.files.map((f: { path: string }) => f.path);
expect(paths).not.toContain('state/shadow-head.txt');
@@ -257,13 +361,21 @@ describe('collectReportBundle — full level', () => {
expect(readZipEntry(zipPath, 'logs/desktop.2026-07-28.log.1')).not.toContain(SECRET);
});
- test('hashes doc names in user logs, which are pino JSONL behind a .log suffix', async () => {
+ test('scrubs credentials in user logs, which are pino JSONL behind a .log suffix', async () => {
+ // User-level logs carry a .log suffix but are line-delimited JSON, so
+ // routing them by extension alone would give them the substring-only pass
+ // and skip the per-line credential scrub. Doc names stay in cleartext by
+ // the ratified consent posture: legible names are what make a bundle
+ // diagnosable, and the summary says so before anything is written.
const projectDir = makeFullProjectDir();
const userLogsDir = makeTmpDir();
writeAt(
userLogsDir,
'desktop.2026-07-28.log',
- `${JSON.stringify({ attributes: [{ key: 'doc.name', value: { stringValue: 'secret-notes/plan' } }] })}\n`,
+ `${JSON.stringify({
+ attributes: [{ key: 'doc.name', value: { stringValue: 'secret-notes/plan' } }],
+ msg: 'token ghp_0123456789abcdefghijABCDEFGHIJ123456 leaked into a log line',
+ })}\n`,
);
const outputPath = join(makeTmpDir(), 'report.zip');
@@ -275,7 +387,10 @@ describe('collectReportBundle — full level', () => {
userLogsDir,
});
- expect(readZipEntry(zipPath, 'logs/desktop.2026-07-28.log')).not.toContain('secret-notes/plan');
+ const entry = readZipEntry(zipPath, 'logs/desktop.2026-07-28.log');
+ expect(entry).not.toContain('ghp_0123456789abcdefghijABCDEFGHIJ123456');
+ expect(entry).toContain('[REDACTED-');
+ expect(entry).toContain('secret-notes/plan');
});
test('omits telemetry entirely when the sink has never written', async () => {
@@ -295,7 +410,7 @@ describe('collectReportBundle — full level', () => {
expect(entries).toContain('manifest.json');
});
- test('scrubs seeded secrets, hashes doc names, and reports the audit', async () => {
+ test('scrubs seeded credentials while doc names ship raw, with no inverse-map sidecar', async () => {
const projectDir = makeFullProjectDir();
const outputPath = join(makeTmpDir(), 'report.zip');
@@ -307,10 +422,12 @@ describe('collectReportBundle — full level', () => {
});
const spans = readZipEntry(zipPath, 'telemetry/spans-current.jsonl');
+ // Credentials are scrubbed, unconditionally.
expect(spans).not.toContain(SECRET);
expect(spans).toContain('[REDACTED-GH-PAT]');
- expect(spans).not.toContain('secret-notes/plan');
- expect(spans).toContain('doc:');
+ // Doc names ship raw under Detailed-diagnostics consent — no hashing.
+ expect(spans).toContain('secret-notes/plan');
+ expect(spans).not.toMatch(/doc:[a-f0-9]{8}/);
const manifest = JSON.parse(readZipEntry(zipPath, 'manifest.json'));
expect(manifest.redaction.applied).toBe(true);
const scrub = manifest.redaction.secretScrub;
@@ -320,11 +437,77 @@ describe('collectReportBundle — full level', () => {
expect(summary.redactions).toEqual(scrub.redactions);
expect(summary.redactedLineCount).toBe(scrub.redactedLineCount);
expect(summary.redactedLineCount).toBeGreaterThanOrEqual(1);
- // Inverse doc-name map lands as a sidecar next to the zip, never inside.
- expect(existsSync(join(dirname(outputPath), 'report.docnames.json'))).toBe(true);
+ // No inverse-map sidecar is written next to the zip anymore.
+ expect(existsSync(join(dirname(outputPath), 'report.docnames.json'))).toBe(false);
expect(listZipEntries(zipPath)).not.toContain('report.docnames.json');
});
+ test('canary: planted credentials appear in no full-tier bundle artifact', async () => {
+ const projectDir = makeFullProjectDir();
+ // Plant the same secret across multiple sinks: the server log and a
+ // loss-ring event field, on top of the span leak makeFullProjectDir seeds.
+ writeAt(
+ projectDir,
+ '.ok/local/logs/server-current.jsonl',
+ `{"level":50,"msg":"auth failed for ${SECRET}"}\n`,
+ );
+ writeAt(
+ projectDir,
+ '.ok/local/loss-capture/loss-current.jsonl',
+ `${JSON.stringify({
+ ts: 1,
+ schemaVersion: 1,
+ seq: 1,
+ event: 'detector-trip',
+ docName: 'notes/plan',
+ writerId: `agent ${SECRET}`,
+ checkpointSha: 'deadbeef',
+ })}\n`,
+ );
+ const outputPath = join(makeTmpDir(), 'report.zip');
+ const { zipPath } = await collectReportBundle({
+ level: 'full',
+ projectDir,
+ redact: true,
+ outputPath,
+ });
+
+ // No text artifact anywhere in the assembled bundle carries the secret.
+ const textEntries = listZipEntries(zipPath).filter((e) => /\.(jsonl?|txt|log|lock)$/.test(e));
+ for (const entry of textEntries) {
+ expect(readZipEntry(zipPath, entry)).not.toContain(SECRET);
+ }
+ // The loss ring rode the full tier; its doc name shipped raw, secret gone.
+ const ring = readZipEntry(zipPath, 'state/loss-current.jsonl');
+ expect(ring).toContain('notes/plan');
+ expect(ring).not.toContain(SECRET);
+ });
+
+ test('tier gating: the loss ring rides the full tier only, never the standard tier', async () => {
+ const projectDir = makeFullProjectDir();
+ writeAt(
+ projectDir,
+ '.ok/local/loss-capture/loss-current.jsonl',
+ `${JSON.stringify({ ts: 1, schemaVersion: 1, seq: 1, event: 'checkpoint-write', docName: 'd' })}\n`,
+ );
+
+ const full = await collectReportBundle({
+ level: 'full',
+ projectDir,
+ redact: true,
+ outputPath: join(makeTmpDir(), 'full.zip'),
+ });
+ expect(listZipEntries(full.zipPath)).toContain('state/loss-current.jsonl');
+
+ const standard = await collectReportBundle({
+ level: 'standard',
+ projectDir,
+ redact: true,
+ outputPath: join(makeTmpDir(), 'standard.zip'),
+ });
+ expect(listZipEntries(standard.zipPath)).not.toContain('state/loss-current.jsonl');
+ });
+
test('redact: false leaves content unmodified with an empty audit', async () => {
const projectDir = makeFullProjectDir();
const outputPath = join(makeTmpDir(), 'report.zip');
diff --git a/packages/cli/src/report-bundle.ts b/packages/cli/src/report-bundle.ts
index 13474477e..f480595b7 100644
--- a/packages/cli/src/report-bundle.ts
+++ b/packages/cli/src/report-bundle.ts
@@ -156,7 +156,7 @@ async function collectFullBundle(
* per-project lock/spawn-error + local sink logs, sysinfo. No git/server
* dependency.
* - `full`: the `ok diagnose bundle` superset — adds telemetry spans, live
- * server state, runtime metadata, and doc-name anonymization.
+ * server state, runtime metadata, and the content-loss ring.
* Availability-gated: pieces whose source is missing (no running server,
* no shadow repo, no telemetry sink) are omitted without error, and the
* bundled manifest inventory reflects what was actually included.
@@ -164,9 +164,9 @@ async function collectFullBundle(
* Every full-only artifact is project-scoped, so without a `projectDir` both
* levels produce the same system-wide bundle.
*
- * With `redact` on, the secret-pattern scrub applies at both levels; the
- * full level additionally hashes doc names and masks the content-dir path
- * (inverse map written as a sidecar next to the zip, never inside it).
+ * With `redact` on, the secret-pattern scrub applies at both levels; the full
+ * level additionally masks the content-dir path. Doc names ship raw under the
+ * user's explicit Detailed-diagnostics consent.
*/
export async function collectReportBundle(
opts: CollectReportBundleOptions,
diff --git a/packages/core/src/bridge/index.ts b/packages/core/src/bridge/index.ts
index 32718b836..4669ca409 100644
--- a/packages/core/src/bridge/index.ts
+++ b/packages/core/src/bridge/index.ts
@@ -52,6 +52,10 @@ export {
} from './frontmatter-region.ts';
export { DUPLICATION_GATE_MIN_LINE_LENGTH, overMultipliedBodyLines } from './growth-detect.ts';
export { fnv1aDigest } from './hash-util.ts';
+export {
+ fragmentHoldsPendingContent,
+ pendingContentLines,
+} from './intraline-predicate.ts';
export {
assertContentPreservation,
BridgeMergeContentLossError,
@@ -59,6 +63,7 @@ export {
type BridgeMergeContentLossLogPayload,
type BridgeMergeContentLossSide,
type BridgeMergeContentLossWhich,
+ findDroppedContent,
mergeThreeWay,
tryLineLevelCombine,
} from './merge-three-way.ts';
diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.ts
new file mode 100644
index 000000000..c43fdd7e7
--- /dev/null
+++ b/packages/core/src/bridge/intraline-predicate.ts
@@ -0,0 +1,33 @@
+export function rawLineCounts(doc: string): Map<string, number> {
+ const counts = new Map<string, number>();
+ for (const line of doc.split('\n')) {
+ if (line.trim() === '') continue;
+ counts.set(line, (counts.get(line) ?? 0) + 1);
+ }
+ return counts;
+}
+
+export function fragmentHoldsPendingContent(md: string, ytext: string, witness: string): boolean {
+ const mdCounts = rawLineCounts(md);
+ const ytextCounts = rawLineCounts(ytext);
+ const witnessCounts = rawLineCounts(witness);
+ for (const [line, mdCount] of mdCounts) {
+ if (mdCount > (ytextCounts.get(line) ?? 0) && mdCount > (witnessCounts.get(line) ?? 0)) {
+ return true;
+ }
+ }
+ return false;
+}
+
+export function pendingContentLines(md: string, ytext: string, witness: string): string[] {
+ const mdCounts = rawLineCounts(md);
+ const ytextCounts = rawLineCounts(ytext);
+ const witnessCounts = rawLineCounts(witness);
+ const pending: string[] = [];
+ for (const [line, mdCount] of mdCounts) {
+ if (mdCount > (ytextCounts.get(line) ?? 0) && mdCount > (witnessCounts.get(line) ?? 0)) {
+ pending.push(line);
+ }
+ }
+ return pending;
+}
diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.ts
index 3d5fd0771..251560a35 100644
--- a/packages/core/src/bridge/merge-three-way.ts
+++ b/packages/core/src/bridge/merge-three-way.ts
@@ -254,6 +254,12 @@ export function assertContentPreservation(
}
}
+export function findDroppedContent(candidate: string, baseline: string, applied: string): string[] {
+ const atRisk = extractUniqueSegments(baseline, candidate);
+ if (atRisk.length === 0) return [];
+ return atRisk.filter((seg) => !applied.includes(seg));
+}
+
function mergeConflictRegion(base: string, user: string, agent: string): string {
if (user === '') return agent;
if (agent === '') return user;
diff --git a/packages/core/src/checkpoint-kind-registry.test.ts b/packages/core/src/checkpoint-kind-registry.test.ts
new file mode 100644
index 000000000..7036d4851
--- /dev/null
+++ b/packages/core/src/checkpoint-kind-registry.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest';
+import {
+ CHECKPOINT_KIND_REGISTRY,
+ CHECKPOINT_KINDS,
+ type CheckpointKind,
+ formatCheckpointBodyLine,
+ isSurfacedCheckpointKind,
+ type ParsedCheckpoint,
+ parseCheckpoint,
+} from './shadow-repo-layout.ts';
+
+// One representative checkpoint per kind. Typed `satisfies Record<CheckpointKind,
+// …>` so a kind added to ParsedCheckpoint without a sample here fails to
+// compile — the round-trip test below then proves the parser and the registry
+// agree on that new kind at runtime, not just at the type level.
+const SAMPLE_BY_KIND = {
+ 'bridge-merge-loss': {
+ kind: 'bridge-merge-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { lostSubstrings: ['dropped'] },
+ },
+ 'producer-guard-loss': {
+ kind: 'producer-guard-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { construct: 'tableCell' },
+ },
+ 'observer-a-duplication': {
+ kind: 'observer-a-duplication',
+ docName: 'notes',
+ size: 12,
+ metadata: { duplicatedLineCount: 2 },
+ },
+ 'external-change-rescue': {
+ kind: 'external-change-rescue',
+ docName: 'notes',
+ size: 12,
+ metadata: { incomingDiskSha: 'abc123' },
+ },
+ 'defer-exhaustion-loss': {
+ kind: 'defer-exhaustion-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { deferCount: 8 },
+ },
+ 'observer-a-apply-loss': {
+ kind: 'observer-a-apply-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { lostSubstrings: ['dropped'] },
+ },
+ 'bridge-derive-loss': {
+ kind: 'bridge-derive-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { lostSubstrings: ['dropped'] },
+ },
+ 'bridge-backstop-trip': {
+ kind: 'bridge-backstop-trip',
+ docName: 'notes',
+ size: 12,
+ metadata: { rounds: 8 },
+ },
+ 'persistence-reconcile-loss': {
+ kind: 'persistence-reconcile-loss',
+ docName: 'notes',
+ size: 12,
+ metadata: { atRiskLines: 1, witnessAvailable: true },
+ },
+ 'auto-consolidation': {
+ kind: 'auto-consolidation',
+ docName: null,
+ size: null,
+ metadata: { foldedRefs: 3, trigger: 'dead-chain' },
+ },
+} satisfies Record<CheckpointKind, ParsedCheckpoint>;
+
+describe('checkpoint-kind registry', () => {
+ it('registers every kind the parser can produce, and no phantom kinds', () => {
+ for (const sample of Object.values(SAMPLE_BY_KIND)) {
+ const parsed = parseCheckpoint(formatCheckpointBodyLine(sample));
+ expect(parsed?.kind).toBe(sample.kind);
+ // The kind the parser round-trips must be a registered kind.
+ expect(CHECKPOINT_KINDS).toContain(parsed?.kind);
+ }
+ // And the registry carries no kind the parser can't produce.
+ expect([...CHECKPOINT_KINDS].sort()).toEqual(Object.keys(SAMPLE_BY_KIND).sort());
+ });
+
+ it('gives every kind a complete, well-typed attribute set', () => {
+ for (const kind of CHECKPOINT_KINDS) {
+ const attrs = CHECKPOINT_KIND_REGISTRY[kind];
+ expect(['surfaced', 'hidden']).toContain(attrs.visibility);
+ expect(['metadata', 'subject-only', 'none']).toContain(attrs.bundleExposure);
+ // Every GC bucket must itself be a registered kind (a real partition key).
+ expect(CHECKPOINT_KINDS).toContain(attrs.gcBucket);
+ }
+ });
+
+ it('surfaces loss and rescue kinds and hides routine auto-consolidation', () => {
+ expect(CHECKPOINT_KIND_REGISTRY['bridge-merge-loss'].visibility).toBe('surfaced');
+ expect(CHECKPOINT_KIND_REGISTRY['producer-guard-loss'].visibility).toBe('surfaced');
+ expect(CHECKPOINT_KIND_REGISTRY['observer-a-duplication'].visibility).toBe('surfaced');
+ expect(CHECKPOINT_KIND_REGISTRY['external-change-rescue'].visibility).toBe('surfaced');
+ expect(CHECKPOINT_KIND_REGISTRY['auto-consolidation'].visibility).toBe('hidden');
+ });
+
+ it('keeps secrets out of the bundle by not exposing routine kinds', () => {
+ // Loss/rescue kinds may ride a consent-gated bundle (correlation only);
+ // routine consolidations never do.
+ expect(CHECKPOINT_KIND_REGISTRY['bridge-merge-loss'].bundleExposure).toBe('subject-only');
+ expect(CHECKPOINT_KIND_REGISTRY['auto-consolidation'].bundleExposure).toBe('none');
+ });
+
+ describe('isSurfacedCheckpointKind', () => {
+ it('treats a non-checkpoint / malformed row (null) as surfaced', () => {
+ expect(isSurfacedCheckpointKind(null)).toBe(true);
+ expect(isSurfacedCheckpointKind(undefined)).toBe(true);
+ });
+
+ it('hides only the kinds registered hidden', () => {
+ expect(isSurfacedCheckpointKind('external-change-rescue')).toBe(true);
+ expect(isSurfacedCheckpointKind('auto-consolidation')).toBe(false);
+ });
+ });
+
+ it('classifies every content-bearing kind as subject-only', () => {
+ // `lostSubstrings` is verbatim document content. A kind carrying it must
+ // never be classified as safe to stage whole into a diagnostics bundle —
+ // that is the difference between a correlation record and an exfiltration.
+ for (const [kind, sample] of Object.entries(SAMPLE_BY_KIND)) {
+ const carriesContent = 'lostSubstrings' in sample.metadata;
+ const exposure = CHECKPOINT_KIND_REGISTRY[kind as CheckpointKind].bundleExposure;
+ if (carriesContent) expect(exposure).toBe('subject-only');
+ else expect(exposure).not.toBe('subject-only');
+ }
+ });
+});
diff --git a/packages/core/src/checkpoint-kinds.ts b/packages/core/src/checkpoint-kinds.ts
new file mode 100644
index 000000000..391ec655d
--- /dev/null
+++ b/packages/core/src/checkpoint-kinds.ts
@@ -0,0 +1,492 @@
+/**
+ * Checkpoint-kind metadata + the shared kind registry.
+ *
+ * Pure data and pure functions — no `node:fs`, no git, no runtime deps — so
+ * this module is safe to import into the browser bundle. It is the single
+ * source of truth both the server (GC partition, timeline query, bundle
+ * staging) and the editor UI (which checkpoint rows surface as ordinary
+ * versions) consume. `shadow-repo-layout.ts` re-exports everything here for
+ * the Node-only subpath consumers; the browser barrel re-exports the registry
+ * helpers so the editor can drive row visibility off the same attributes.
+ */
+
+/** Prefix for the versioned checkpoint-metadata body line. */
+const OK_CHECKPOINT_PREFIX = 'ok-checkpoint-v1: ';
+
+/**
+ * Kind-discriminated checkpoint metadata parsed from the `ok-checkpoint-v1:`
+ * body line. The body line coexists with `ok-contributors:` lines —
+ * `parseContributors` skips unknown prefixes, so the two channels do not
+ * interfere.
+ *
+ * `docName` and `size` are carried inline so the `/api/rescue` read path can
+ * enumerate checkpoints via a single batched `git log` without a per-ref
+ * `git ls-tree` fan-out. They are
+ * optional in the parsed shape for backward-compatible reads: pre-enrichment
+ * commits returned `null` for both and the rescue list fell back to
+ * `ls-tree`. New writes (`saveInMemoryCheckpoint`) always populate them.
+ */
+/**
+ * Why a service-authored consolidation fired. Bounded set so telemetry/diagnose
+ * can read it back as a low-cardinality enum. Parsed back as a bare `string` for
+ * forward-compatibility (a future trigger an old reader doesn't know about still
+ * parses), so writers construct with this type but readers must not assume it.
+ */
+export type AutoConsolidationTrigger = 'dead-chain' | 'session-close' | 'boot' | 'ttl';
+
+export type ParsedCheckpoint =
+ | {
+ // `which` distinguishes the post-condition verdict class ('substring' /
+ // 'order' losses vs 'growth' gains) within the one merge checkpoint
+ // kind. Optional: checkpoints written before the field existed parse
+ // without it.
+ kind: 'bridge-merge-loss';
+ docName: string | null;
+ size: number | null;
+ metadata: { lostSubstrings: string[]; which?: string };
+ }
+ | {
+ // Observer A's producer guard detected serialize output that fails
+ // structural legality (a fresh parse loses authored content) at the
+ // serialize boundary — distinct from `bridge-merge-loss` (a Path B merge
+ // drop) so the two detection sites keep separate retention budgets and
+ // TimelinePanel can tell serializer-corruption from merge-drop. `construct`
+ // is a bounded, content-free locator of the danger-space node types
+ // present (e.g. `jsxComponent,tableCell`), never raw content.
+ kind: 'producer-guard-loss';
+ docName: string | null;
+ size: number | null;
+ metadata: { construct: string };
+ }
+ | {
+ // Observer A's duplication gate detected a CRDT double-materialization of
+ // a bridge-derived span (a substantive body line present in the fragment
+ // more times than Y.Text justified, provenance-confirmed as a
+ // server-vs-client race) and re-derived the fragment from Y.Text before
+ // it could persist. `contents` is the pre-recovery doubled fragment
+ // serialization — the anchor if the re-derive was wrong.
+ // `duplicatedLineCount` is a content-free count, never raw content.
+ kind: 'observer-a-duplication';
+ docName: string | null;
+ size: number | null;
+ metadata: { duplicatedLineCount: number };
+ }
+ | {
+ kind: 'external-change-rescue';
+ docName: string | null;
+ size: number | null;
+ metadata: { incomingDiskSha: string };
+ }
+ | {
+ // The derive-timing defer guard reached its drain-count bound and
+ // force-resolved. The re-derive then proceeds, dropping the un-propagated
+ // WYSIWYG content from the live fragment; this checkpoint holds the
+ // pre-resolve fragment serialization so that content stays restorable
+ // through the timeline floor — the loud alternative to a silent clamp.
+ // `deferCount` is a content-free count of the deferrals that preceded the
+ // force-resolve.
+ kind: 'defer-exhaustion-loss';
+ docName: string | null;
+ size: number | null;
+ metadata: { deferCount: number };
+ }
+ | {
+ // The Observer-A APPLY post-condition (XmlFragment→Y.Text direction)
+ // detected that the byte-preserving apply arms (map-driven splice /
+ // incremental diff) dropped content the fragment's intended markdown held.
+ // Distinct from `bridge-merge-loss` (a Path-B MERGE drop) so the two
+ // detection sites keep separate counters and retention budgets, and an
+ // operator can tell an apply drop from a merge drop by kind alone.
+ // `contents` is the pre-loss fragment serialization (the restore anchor);
+ // `lostSubstrings` names the dropped content for diagnosis.
+ kind: 'observer-a-apply-loss';
+ docName: string | null;
+ size: number | null;
+ metadata: { lostSubstrings: string[] };
+ }
+ | {
+ // The Y.Text→XmlFragment derive post-condition (Observer B direction)
+ // detected that the pre-derive fragment held authored content the
+ // authoritative Y.Text lacked — a paired agent-undo derive was about to
+ // rebuild the fragment from Y.Text and discard it. Distinct from the
+ // Observer-A merge/producer/duplication kinds so the derive direction
+ // keeps its own retention budget and surfaces separately. `contents` is
+ // the pre-derive fragment serialization (the restore anchor);
+ // `lostSubstrings` names the dropped content for diagnosis.
+ kind: 'bridge-derive-loss';
+ docName: string | null;
+ size: number | null;
+ metadata: { lostSubstrings: string[] };
+ }
+ | {
+ // The Y.Text→XmlFragment re-derive loop hit its drain-count backstop: a
+ // run of re-derive drains never reached a raw-byte fixed point (the two
+ // representations kept diverging). The B-direction re-derive is frozen to
+ // stop the runaway loop; this checkpoint holds the Y.Text at freeze time
+ // so that authoritative state stays restorable — the loud alternative to
+ // silent truncate-and-continue. `rounds` is a content-free count of the
+ // non-converging drains that preceded the trip.
+ kind: 'bridge-backstop-trip';
+ docName: string | null;
+ size: number | null;
+ metadata: { rounds: number };
+ }
+ | {
+ // The persistence pre-write sanity check found a fragment/Y.Text
+ // divergence it could NOT attribute to the derive-timing guard's
+ // protected pending set, and is about to rebuild the fragment from
+ // Y.Text. This checkpoint holds the pre-rebuild fragment serialization so
+ // that view stays restorable — checkpoint-before-repair, the posture
+ // `reports/tolerated-divergence-hygiene-layers/REPORT.md` draws from
+ // e2fsck. Both metadata fields are content-free: `atRiskLines` counts the
+ // fragment lines Y.Text lacked, `witnessAvailable` records whether the
+ // tolerance could be evaluated at all (a detached observer publishes no
+ // witness, which is itself a distinguishable trip class).
+ kind: 'persistence-reconcile-loss';
+ docName: string | null;
+ size: number | null;
+ metadata: { atRiskLines: number; witnessAvailable: boolean };
+ }
+ | {
+ // Service-authored consolidation of dead/stale WIP chains.
+ // GET /api/history excludes this kind by default so daily
+ // auto-consolidations never pollute timelines; old readers that predate
+ // this kind get `null` from parseCheckpoint (the unknown-kind fallback)
+ // and render it as a plain Save Version — data-safe, cosmetic only.
+ kind: 'auto-consolidation';
+ docName: string | null;
+ size: number | null;
+ metadata: { foldedRefs: number; trigger: string };
+ };
+
+/**
+ * Parse the `ok-checkpoint-v1:` metadata line from a commit message body.
+ * Returns `null` when the line is absent, malformed JSON, has an unknown
+ * `kind`, or has a metadata shape that doesn't match the expected kind.
+ *
+ * Parallel to `parseContributors` in spirit — silent fallback, no throws —
+ * so TimelinePanel rendering can gracefully degrade to 'Save Version'
+ * rendering for checkpoints without this body line.
+ */
+export function parseCheckpoint(body: string): ParsedCheckpoint | null {
+ if (!body) return null;
+ for (const line of body.split('\n')) {
+ const trimmed = line.trim();
+ if (!trimmed.startsWith(OK_CHECKPOINT_PREFIX)) continue;
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed.slice(OK_CHECKPOINT_PREFIX.length));
+ } catch {
+ return null;
+ }
+ if (parsed === null || typeof parsed !== 'object') return null;
+ const obj = parsed as {
+ kind?: unknown;
+ metadata?: unknown;
+ docName?: unknown;
+ size?: unknown;
+ };
+ const kind = obj.kind;
+ const metadata = obj.metadata;
+ if (metadata === null || typeof metadata !== 'object') return null;
+ const docName = typeof obj.docName === 'string' ? obj.docName : null;
+ const size = typeof obj.size === 'number' && Number.isFinite(obj.size) ? obj.size : null;
+ if (kind === 'bridge-merge-loss') {
+ const m = metadata as { lostSubstrings?: unknown };
+ if (Array.isArray(m.lostSubstrings) && m.lostSubstrings.every((s) => typeof s === 'string')) {
+ return {
+ kind: 'bridge-merge-loss',
+ docName,
+ size,
+ metadata: { lostSubstrings: m.lostSubstrings as string[] },
+ };
+ }
+ return null;
+ }
+ if (kind === 'producer-guard-loss') {
+ const m = metadata as { construct?: unknown };
+ if (typeof m.construct === 'string') {
+ return {
+ kind: 'producer-guard-loss',
+ docName,
+ size,
+ metadata: { construct: m.construct },
+ };
+ }
+ return null;
+ }
+ if (kind === 'observer-a-duplication') {
+ const m = metadata as { duplicatedLineCount?: unknown };
+ if (typeof m.duplicatedLineCount === 'number' && Number.isFinite(m.duplicatedLineCount)) {
+ return {
+ kind: 'observer-a-duplication',
+ docName,
+ size,
+ metadata: { duplicatedLineCount: m.duplicatedLineCount },
+ };
+ }
+ return null;
+ }
+ if (kind === 'external-change-rescue') {
+ const m = metadata as { incomingDiskSha?: unknown };
+ if (typeof m.incomingDiskSha === 'string') {
+ return {
+ kind: 'external-change-rescue',
+ docName,
+ size,
+ metadata: { incomingDiskSha: m.incomingDiskSha },
+ };
+ }
+ return null;
+ }
+ if (kind === 'defer-exhaustion-loss') {
+ const m = metadata as { deferCount?: unknown };
+ if (typeof m.deferCount === 'number' && Number.isFinite(m.deferCount)) {
+ return {
+ kind: 'defer-exhaustion-loss',
+ docName,
+ size,
+ metadata: { deferCount: m.deferCount },
+ };
+ }
+ return null;
+ }
+ if (kind === 'observer-a-apply-loss') {
+ const m = metadata as { lostSubstrings?: unknown };
+ if (Array.isArray(m.lostSubstrings) && m.lostSubstrings.every((s) => typeof s === 'string')) {
+ return {
+ kind: 'observer-a-apply-loss',
+ docName,
+ size,
+ metadata: { lostSubstrings: m.lostSubstrings as string[] },
+ };
+ }
+ return null;
+ }
+ if (kind === 'bridge-derive-loss') {
+ const m = metadata as { lostSubstrings?: unknown };
+ if (Array.isArray(m.lostSubstrings) && m.lostSubstrings.every((s) => typeof s === 'string')) {
+ return {
+ kind: 'bridge-derive-loss',
+ docName,
+ size,
+ metadata: { lostSubstrings: m.lostSubstrings as string[] },
+ };
+ }
+ return null;
+ }
+ if (kind === 'bridge-backstop-trip') {
+ const m = metadata as { rounds?: unknown };
+ if (typeof m.rounds === 'number' && Number.isFinite(m.rounds)) {
+ return {
+ kind: 'bridge-backstop-trip',
+ docName,
+ size,
+ metadata: { rounds: m.rounds },
+ };
+ }
+ return null;
+ }
+ if (kind === 'persistence-reconcile-loss') {
+ const m = metadata as { atRiskLines?: unknown; witnessAvailable?: unknown };
+ if (
+ typeof m.atRiskLines === 'number' &&
+ Number.isFinite(m.atRiskLines) &&
+ typeof m.witnessAvailable === 'boolean'
+ ) {
+ return {
+ kind: 'persistence-reconcile-loss',
+ docName,
+ size,
+ metadata: { atRiskLines: m.atRiskLines, witnessAvailable: m.witnessAvailable },
+ };
+ }
+ return null;
+ }
+ if (kind === 'auto-consolidation') {
+ const m = metadata as { foldedRefs?: unknown; trigger?: unknown };
+ if (
+ typeof m.foldedRefs === 'number' &&
+ Number.isFinite(m.foldedRefs) &&
+ typeof m.trigger === 'string'
+ ) {
+ return {
+ kind: 'auto-consolidation',
+ docName,
+ size,
+ metadata: { foldedRefs: m.foldedRefs, trigger: m.trigger },
+ };
+ }
+ return null;
+ }
+ return null;
+ }
+ return null;
+}
+
+/**
+ * Format the `ok-checkpoint-v1:` body line for a given kind+metadata. Produces
+ * exactly one line (no trailing newline). Consumers embed it inside a full
+ * commit message body as a sibling to `ok-contributors:` lines.
+ *
+ * Exported so `saveInMemoryCheckpoint` in the server package can share this
+ * serialization rule with the parser — see precedent #4 (shared computation).
+ */
+export function formatCheckpointBodyLine(parsed: ParsedCheckpoint): string {
+ const payload: {
+ kind: ParsedCheckpoint['kind'];
+ docName?: string;
+ size?: number;
+ metadata: ParsedCheckpoint['metadata'];
+ } = {
+ kind: parsed.kind,
+ metadata: parsed.metadata,
+ };
+ if (parsed.docName !== null) payload.docName = parsed.docName;
+ if (parsed.size !== null) payload.size = parsed.size;
+ return `${OK_CHECKPOINT_PREFIX}${JSON.stringify(payload)}`;
+}
+
+// ─── Checkpoint-kind registry ────────────────────────────────────────────────
+
+/**
+ * The typed checkpoint kinds. Derived from the parser union so every kind-keyed
+ * partition (GC buckets, timeline visibility, bundle staging) stays tied to
+ * what `parseCheckpoint` can actually return — a kind the parser produces but a
+ * consumer forgot to handle becomes a compile error, not a silent gap.
+ */
+export type CheckpointKind = ParsedCheckpoint['kind'];
+
+/**
+ * Whether a checkpoint kind surfaces as an ordinary version-history row.
+ * `hidden` kinds are still walked for ancestry but never shown — routine
+ * service consolidations stay out of the timeline.
+ */
+export type CheckpointVisibility = 'surfaced' | 'hidden';
+
+/**
+ * How much of a checkpoint row may ride a consent-gated Detailed-diagnostics
+ * bundle. This is a PRIVACY classification, and the distinction is real:
+ *
+ * - `metadata` — the kind's `ok-checkpoint-v1:` metadata is content-free
+ * correlation data (counts, shas, bounded construct locators), so the whole
+ * body line may travel.
+ * - `subject-only` — the kind's metadata embeds RAW DOCUMENT CONTENT (the
+ * `lostSubstrings` kinds carry verbatim dropped lines), so only the
+ * content-free commit subject may travel. A bundle that staged the body for
+ * these kinds would exfiltrate the user's document.
+ * - `none` — the kind never appears in a bundle at all.
+ *
+ * The loss ring is content-free by schema regardless of this attribute; this
+ * classifies the CHECKPOINT COMMIT, which is not.
+ *
+ * ADVISORY, not enforcement: the bundle staging path stages the content-free
+ * commit subject UNIFORMLY for every kind (the `CHECKPOINT_REF_GIT_FORMAT`
+ * for-each-ref format in the CLI bundle assembler) and never reads this
+ * attribute — privacy holds by that uniform construction, guarded by a format
+ * test. This documents each kind's content tier so a future staging change that
+ * wants to expand a kind's body registers which kinds it must never expand; it
+ * does not gate today's staging.
+ */
+export type CheckpointBundleExposure = 'metadata' | 'subject-only' | 'none';
+
+/**
+ * Per-kind attributes that drive surfacing, GC, restore, and bundle behavior
+ * from one place, so those four consumers can't drift from each other. Both
+ * this program's loss/rescue kinds and the conflict spec's future consumer
+ * kinds register here.
+ */
+export interface CheckpointKindAttributes {
+ /** Surfaced as an ordinary timeline row, or hidden from it. */
+ visibility: CheckpointVisibility;
+ /**
+ * Retention partition this kind is GC'd under — the `gcCheckpointRefs`
+ * byKind key. 1:1 with the kind today; the indirection lets a future kind
+ * draw from an existing budget instead of minting its own.
+ */
+ gcBucket: CheckpointKind;
+ /** How rows of this kind may appear in a consent-gated diagnostic bundle. */
+ bundleExposure: CheckpointBundleExposure;
+}
+
+/**
+ * Single source of truth for checkpoint-kind behavior. Visibility follows the
+ * timeline-floor reshape: loss and rescue kinds surface as ordinary "recovered
+ * content" rows; routine `auto-consolidation` stays hidden.
+ *
+ * The `satisfies Record<CheckpointKind, …>` makes this the enforced extension
+ * point: a kind added to `ParsedCheckpoint` that is not registered here (or an
+ * entry registered here with no matching parser kind) fails to compile. When
+ * the conflict spec adds `auto-merge-rescue` it must register it here too, as
+ * `visibility: 'surfaced'` — the "Before merge" row whose restore is a plain
+ * restore-to-that-row.
+ */
+export const CHECKPOINT_KIND_REGISTRY = {
+ // `lostSubstrings` is verbatim document content — subject-only.
+ 'bridge-merge-loss': {
+ visibility: 'surfaced',
+ gcBucket: 'bridge-merge-loss',
+ bundleExposure: 'subject-only',
+ },
+ 'producer-guard-loss': {
+ visibility: 'surfaced',
+ gcBucket: 'producer-guard-loss',
+ bundleExposure: 'metadata',
+ },
+ 'observer-a-duplication': {
+ visibility: 'surfaced',
+ gcBucket: 'observer-a-duplication',
+ bundleExposure: 'metadata',
+ },
+ 'external-change-rescue': {
+ visibility: 'surfaced',
+ gcBucket: 'external-change-rescue',
+ bundleExposure: 'metadata',
+ },
+ 'defer-exhaustion-loss': {
+ visibility: 'surfaced',
+ gcBucket: 'defer-exhaustion-loss',
+ bundleExposure: 'metadata',
+ },
+ // `lostSubstrings` is verbatim document content — subject-only.
+ 'observer-a-apply-loss': {
+ visibility: 'surfaced',
+ gcBucket: 'observer-a-apply-loss',
+ bundleExposure: 'subject-only',
+ },
+ // `lostSubstrings` is verbatim document content — subject-only.
+ 'bridge-derive-loss': {
+ visibility: 'surfaced',
+ gcBucket: 'bridge-derive-loss',
+ bundleExposure: 'subject-only',
+ },
+ 'bridge-backstop-trip': {
+ visibility: 'surfaced',
+ gcBucket: 'bridge-backstop-trip',
+ bundleExposure: 'metadata',
+ },
+ 'persistence-reconcile-loss': {
+ visibility: 'surfaced',
+ gcBucket: 'persistence-reconcile-loss',
+ bundleExposure: 'metadata',
+ },
+ 'auto-consolidation': {
+ visibility: 'hidden',
+ gcBucket: 'auto-consolidation',
+ bundleExposure: 'none',
+ },
+} as const satisfies Record<CheckpointKind, CheckpointKindAttributes>;
+
+/** Every registered checkpoint kind, for exhaustive iteration. */
+export const CHECKPOINT_KINDS = Object.keys(CHECKPOINT_KIND_REGISTRY) as CheckpointKind[];
+
+/**
+ * Whether a checkpoint kind surfaces as an ordinary timeline row. `null` /
+ * `undefined` (a non-checkpoint row, or a checkpoint whose body line was
+ * missing or malformed) counts as surfaced — those are ordinary Save-Version /
+ * WIP rows, not hidden kinds.
+ */
+export function isSurfacedCheckpointKind(kind: CheckpointKind | null | undefined): boolean {
+ if (kind == null) return true;
+ return CHECKPOINT_KIND_REGISTRY[kind].visibility === 'surfaced';
+}
diff --git a/packages/core/src/config/field-registry.test.ts b/packages/core/src/config/field-registry.test.ts
index 5e0e7718e..9e66027d5 100644
--- a/packages/core/src/config/field-registry.test.ts
+++ b/packages/core/src/config/field-registry.test.ts
@@ -166,7 +166,7 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
]);
});
- test('project-strict fields cover autoSync.default + content.* + contentRules.* + telemetry.localSink.*', () => {
+ test('project-strict fields cover autoSync.default + content.* + contentRules.* + lossCapture.* + telemetry.localSink.*', () => {
// `autoSync.default` is the committed seed for a machine's sync mode on
// first open ('off'/'pull'/'full', or the legacy boolean, or null). Project
// scope is the whole point — it travels with the repo so a maintainer
@@ -188,6 +188,11 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
// disabling the sink is also a project-level decision (sensitive
// workspaces opt out across the whole team).
//
+ // `lossCapture.*` controls the dedicated bridge loss-class ring harvested
+ // by the same bundle. Project scope for the same reason as the telemetry
+ // sink: rotation cap shared via the committed `config.yml`, and disabling
+ // the ring is a whole-team decision for a sensitive workspace.
+ //
// `contentRules.*` is the project's markdown authoring standard — which
// lint plugins run. Shared via the committed `config.yml` (the OK analog of
// a checked-in `.markdownlint.json`). Each plugin's slice registers its own
@@ -200,11 +205,19 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
.sort();
expect(projectStrict).toEqual([
'autoSync.default',
+ 'bridge.backgroundThrottle.enabled',
+ 'bridge.deferGuard.enabled',
+ 'bridge.fixedPoint.enabled',
+ 'bridge.flushOnHide.enabled',
+ 'bridge.lossDetector.enabled',
+ 'bridge.preDrain.enabled',
'content.attachmentFolderPath',
'content.dir',
'contentRules.frontmatter.enabled',
'contentRules.frontmatter.schemas',
'contentRules.markdownlint.enabled',
+ 'lossCapture.enabled',
+ 'lossCapture.maxBytes',
'telemetry.localSink.attributeDenylist',
'telemetry.localSink.enabled',
'telemetry.localSink.logs.maxBytes',
diff --git a/packages/core/src/config/schema-jsonschema.test.ts b/packages/core/src/config/schema-jsonschema.test.ts
index 308f56729..382eeab42 100644
--- a/packages/core/src/config/schema-jsonschema.test.ts
+++ b/packages/core/src/config/schema-jsonschema.test.ts
@@ -236,4 +236,83 @@ describe('loose-mode forgiveness', () => {
});
expect(config.telemetry.localSink.attributeDenylist).toEqual(['x-internal-token']);
});
+
+ test('lossCapture defaults to enabled with a rotation cap', () => {
+ const config = ConfigSchema.parse({});
+ expect(config.lossCapture.enabled).toBe(true);
+ expect(config.lossCapture.maxBytes).toBe(12_582_912);
+ });
+
+ test('lossCapture.enabled=false preserved through parse', () => {
+ const config = ConfigSchema.parse({ lossCapture: { enabled: false } });
+ expect(config.lossCapture.enabled).toBe(false);
+ // The sibling cap still resolves to its default even when enabled is overridden.
+ expect(config.lossCapture.maxBytes).toBe(12_582_912);
+ });
+
+ test('lossCapture custom maxBytes preserved', () => {
+ const config = ConfigSchema.parse({ lossCapture: { maxBytes: 4096 } });
+ expect(config.lossCapture.maxBytes).toBe(4096);
+ expect(config.lossCapture.enabled).toBe(true);
+ });
+
+ test('bridge.backgroundThrottle defaults to enabled', () => {
+ const config = ConfigSchema.parse({});
+ expect(config.bridge.backgroundThrottle.enabled).toBe(true);
+ });
+
+ test('bridge.backgroundThrottle.enabled=false preserved through parse', () => {
+ const config = ConfigSchema.parse({ bridge: { backgroundThrottle: { enabled: false } } });
+ expect(config.bridge.backgroundThrottle.enabled).toBe(false);
+ });
+
+ test('bridge.deferGuard defaults to enabled', () => {
+ const config = ConfigSchema.parse({});
+ expect(config.bridge.deferGuard.enabled).toBe(true);
+ });
+
+ test('bridge.deferGuard.enabled=false preserved through parse', () => {
+ const config = ConfigSchema.parse({ bridge: { deferGuard: { enabled: false } } });
+ expect(config.bridge.deferGuard.enabled).toBe(false);
+ });
+
+ test('bridge.lossDetector defaults to enabled', () => {
+ const config = ConfigSchema.parse({});
+ expect(config.bridge.lossDetector.enabled).toBe(true);
+ });
+
+ test('bridge.lossDetector.enabled=false preserved through parse', () => {
+ const config = ConfigSchema.parse({ bridge: { lossDetector: { enabled: false } } });
+ expect(config.bridge.lossDetector.enabled).toBe(false);
+ });
+
+ test('bridge.fixedPoint defaults to enabled', () => {
+ const config = ConfigSchema.parse({});
+ expect(config.bridge.fixedPoint.enabled).toBe(true);
+ });
+
+ test('bridge.fixedPoint.enabled=false preserved through parse', () => {
+ const config = ConfigSchema.parse({ bridge: { fixedPoint: { enabled: false } } });
+ expect(config.bridge.fixedPoint.enabled).toBe(false);
+ });
+
+ test('bridge.preDrain defaults to enabled', () => {
+ const config = ConfigSchema.parse({});
+ expect(config.bridge.preDrain.enabled).toBe(true);
+ });
+
+ test('bridge.preDrain.enabled=false preserved through parse', () => {
+ const config = ConfigSchema.parse({ bridge: { preDrain: { enabled: false } } });
+ expect(config.bridge.preDrain.enabled).toBe(false);
+ });
+
+ test('bridge.flushOnHide defaults to enabled', () => {
+ const config = ConfigSchema.parse({});
+ expect(config.bridge.flushOnHide.enabled).toBe(true);
+ });
+
+ test('bridge.flushOnHide.enabled=false preserved through parse', () => {
+ const config = ConfigSchema.parse({ bridge: { flushOnHide: { enabled: false } } });
+ expect(config.bridge.flushOnHide.enabled).toBe(false);
+ });
});
diff --git a/packages/core/src/config/schema.ts b/packages/core/src/config/schema.ts
index 1215ab391..d07ddc120 100644
--- a/packages/core/src/config/schema.ts
+++ b/packages/core/src/config/schema.ts
@@ -25,6 +25,11 @@ export const DEFAULT_TELEMETRY_ATTRIBUTE_DENYLIST: readonly string[] = Object.fr
export const DEFAULT_SPANS_MAX_BYTES = 52_428_800;
export const DEFAULT_LOGS_MAX_BYTES = 26_214_400;
+// The loss-capture ring is a small, dedicated diagnostic sink (bridge
+// loss-class events, content-free); ~12 MB/generation keeps its two-generation
+// footprint bounded well under the span/log rings it must never compete with.
+const DEFAULT_LOSS_CAPTURE_MAX_BYTES = 12_582_912;
+
// Non-secret embeddings-provider defaults. Shared with the server so the live
// layered config read and the schema `.default()` below cannot drift. The API
// key is NEVER a config value — it lives only in `~/.ok/secrets.yml` (0600).
@@ -604,6 +609,146 @@ export const ConfigSchema = z.looseObject({
attributeDenylist: [...DEFAULT_TELEMETRY_ATTRIBUTE_DENYLIST],
},
}),
+ // PROJECT-scope: the loss-capture ring records bridge loss-class events
+ // (deferred re-derives, tripped detectors/backstops, written recovery
+ // checkpoints) content-free under `<contentDir>/.ok/local/loss-capture/` for
+ // `ok diagnose bundle` to harvest. Same posture as the telemetry sink:
+ // local-only until the user runs bundle, default-on following the universal
+ // production-tooling pattern, and a project-shared decision (a sensitive
+ // workspace opts the whole team out). It is a distinct ring from the OTel
+ // span/log sink above — its own file, its own smaller cap — so a burst of
+ // loss events never rotates diagnostic logs out from under the user.
+ lossCapture: z
+ .looseObject({
+ enabled: z
+ .boolean()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ defaultScope: 'project',
+ description:
+ 'Record bridge loss-class events (content-free) under .ok/local/loss-capture/ for `ok diagnose bundle`. Local-only — never leaves the machine until you run bundle. Set false for sensitive workspaces. Shared across collaborators.',
+ })
+ .default(true),
+ maxBytes: z
+ .number()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ defaultScope: 'project',
+ description:
+ 'Maximum size, in bytes, of the local loss-capture file before it rotates (default ~12 MB).',
+ })
+ .default(DEFAULT_LOSS_CAPTURE_MAX_BYTES),
+ })
+ .default({
+ enabled: true,
+ maxBytes: DEFAULT_LOSS_CAPTURE_MAX_BYTES,
+ }),
+ // PROJECT-scope: kill-switches for the bridge loss-hardening mechanisms.
+ // Mostly server-side, but not exclusively — `backgroundThrottle` gates the
+ // desktop main process and `flushOnHide` the renderer, so the sub-tree is
+ // "the bridge loss-hardening family", not "the server". Each defaults ON (the
+ // mechanisms are the loss-prevention guarantee) and exists as a
+ // support-visible field escape — a sensitive or regression-hit workspace can
+ // disable one without a code change. Project scope because the bridge is
+ // server-authoritative: the whole project shares one server, so a per-machine
+ // toggle would not be honored.
+ bridge: z
+ .looseObject({
+ backgroundThrottle: z
+ .looseObject({
+ enabled: z
+ .boolean()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ defaultScope: 'project',
+ description:
+ "Keep the desktop window's timers running at full rate while it holds unsynced work, so backgrounding the app never starves sync or recovery; when the window is idle the OS-default background throttling is restored (battery). Honored by the desktop app. Default ON — disable only to isolate a suspected regression.",
+ })
+ .default(true),
+ })
+ .default({ enabled: true }),
+ deferGuard: z
+ .looseObject({
+ enabled: z
+ .boolean()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ defaultScope: 'project',
+ description:
+ 'Defer a drain-shaped Observer B re-derive when the WYSIWYG fragment holds an un-propagated keystroke Y.Text lacks, so the keystroke survives instead of being stomped. Default ON — disable only to isolate a suspected regression.',
+ })
+ .default(true),
+ })
+ .default({ enabled: true }),
+ lossDetector: z
+ .looseObject({
+ enabled: z
+ .boolean()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ defaultScope: 'project',
+ description:
+ 'Detect content the bridge silently dropped at its reconciliation boundary (an Observer-A apply arm or a paired agent-undo derive) and write a recovery checkpoint plus a content-free loss event. Detection only — never blocks a write. Default ON — disable only to isolate a suspected regression.',
+ })
+ .default(true),
+ })
+ .default({ enabled: true }),
+ fixedPoint: z
+ .looseObject({
+ enabled: z
+ .boolean()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ defaultScope: 'project',
+ description:
+ 'Bound the Y.Text→WYSIWYG re-derive loop with a drain-count backstop: a run of re-derive drains that never reaches a raw-byte fixed point freezes the re-derive loop and writes a recovery checkpoint plus a content-free loss event, instead of churning unbounded. Default ON — disable only to isolate a suspected regression.',
+ })
+ .default(true),
+ })
+ .default({ enabled: true }),
+ preDrain: z
+ .looseObject({
+ enabled: z
+ .boolean()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ defaultScope: 'project',
+ description:
+ 'Before an agent write or undo rebuilds the WYSIWYG fragment, flush an un-propagated keystroke that provably does not overlap the operation into Y.Text so the keystroke survives instead of needing recovery; overlapping or unmodellable cases fall back to the checkpoint floor. Scope: appending writes and single-frame undos — a write that replaces the whole body (replace / edit) overwrites the keystroke either way, so those always take the checkpoint floor. Default ON — disable only to isolate a suspected regression.',
+ })
+ .default(true),
+ })
+ .default({ enabled: true }),
+ flushOnHide: z
+ .looseObject({
+ enabled: z
+ .boolean()
+ .register(fieldRegistry, {
+ scope: 'project',
+ agentSettable: false,
+ defaultScope: 'project',
+ description:
+ "On tab hide/unload, force-send each doc's unsynced work to the server and commit its local cache, and re-sync on return to foreground, so a backgrounded tab never strands edits that IndexedDB alone would lose on recycle. Honored client-side. Default ON — disable only to isolate a suspected regression.",
+ })
+ .default(true),
+ })
+ .default({ enabled: true }),
+ })
+ .default({
+ backgroundThrottle: { enabled: true },
+ deferGuard: { enabled: true },
+ lossDetector: { enabled: true },
+ fixedPoint: { enabled: true },
+ preDrain: { enabled: true },
+ flushOnHide: { enabled: true },
+ }),
// PROJECT-LOCAL scope: semantic search is an additive embeddings signal fused
// into the MCP `search` tool's lexical ranking. It is per-machine, not
// project-shared, because enabling it sends content to a third-party
diff --git a/packages/core/src/desktop-bridge.ts b/packages/core/src/desktop-bridge.ts
index cf93c0bd0..561415d8c 100644
--- a/packages/core/src/desktop-bridge.ts
+++ b/packages/core/src/desktop-bridge.ts
@@ -1693,6 +1693,12 @@ export interface OkDesktopBridge {
* JSDoc in `packages/desktop/src/shared/bridge-contract.ts`.
*/
notifyViewMenuStateChanged(state: Partial<OkEditorViewMenuStateSnapshot>): void;
+ /**
+ * Fire-and-forget push keying the window's Chromium background-throttling
+ * to its unsynced work. See canonical JSDoc in
+ * `packages/desktop/src/shared/bridge-contract.ts`.
+ */
+ notifyBackgroundThrottle(signal: { hasPendingWork: boolean; enabled: boolean }): void;
};
/**
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 089b62d46..0aa2f4d6f 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -61,18 +61,27 @@ export {
BUG_REPORT_SCREENSHOT_ZIP_NAME,
LOG_LEVELS,
} from './logger-types.ts';
-// Renderer/browser console-capture helpers (level mapping, structured-message
-// unwrap, batch bounds) shared by the desktop main listener, the server
-// `/api/client-logs` ingest, and the web renderer forwarder.
+// Renderer/browser console-capture helpers (capture-time scrub, level mapping,
+// structured-message unwrap, batch bounds) shared by the desktop main listener
+// and the web renderer forwarder, plus the server `/api/client-logs` ingest
+// that receives what the forwarder captured.
export {
mapConsoleLevel,
parseStructuredConsoleMessage,
+ prepareCapturedConsoleMessage,
RENDERER_LOG_MAX_BATCH_BYTES,
RENDERER_LOG_MAX_ENTRIES,
RENDERER_LOG_MAX_MESSAGE_BYTES,
type RendererLogLevel,
truncateLogMessage,
} from './logging/renderer-log.ts';
+// Canonical secret/credential scrub shared by the diagnostic-bundle assembly
+// and the renderer console-capture forwarder (one pattern list, no drift).
+export {
+ redactSecrets,
+ SECRET_PATTERN_NAMES,
+ scrubSecrets,
+} from './logging/secret-scrub.ts';
// Cross-process contract version (pure integer; browser-safe).
export { PROTOCOL_VERSION } from './protocol-version.ts';
@@ -1281,8 +1290,10 @@ export {
type FrontmatterBindingUnsubscribe,
type FrontmatterDocProvider,
type FrontmatterSnapshot,
+ findDroppedContent,
findFirstDivergenceIndex,
fnv1aDigest,
+ fragmentHoldsPendingContent,
type InvariantViolation,
isParseEquivalentBridge,
MAX_FM_REGION_BYTES,
@@ -1294,6 +1305,7 @@ export {
type PmStructuralNode,
parseFencedFmRegion,
parseFmRegion,
+ pendingContentLines,
projectMergeBoundarySpace,
readFmKeys,
readFmMap,
@@ -1314,6 +1326,25 @@ export {
toBridgeInvariantLog,
tryLineLevelCombine,
} from './bridge/index.ts';
+export type {
+ AutoConsolidationTrigger,
+ CheckpointBundleExposure,
+ CheckpointKind,
+ CheckpointKindAttributes,
+ CheckpointVisibility,
+ ParsedCheckpoint,
+} from './checkpoint-kinds.ts';
+// Checkpoint-kind metadata + the shared kind registry ARE browser-safe (pure
+// data, no `node:fs`) and live in `./checkpoint-kinds.ts`, so the editor UI can
+// drive timeline-row visibility off the same registry the server GC/timeline/
+// bundle paths use. `shadow-repo-layout` re-exports these for Node-only callers.
+export {
+ CHECKPOINT_KIND_REGISTRY,
+ CHECKPOINT_KINDS,
+ formatCheckpointBodyLine,
+ isSurfacedCheckpointKind,
+ parseCheckpoint,
+} from './checkpoint-kinds.ts';
// Two-phase shutdown timing constants — shared by the CLI's idle-shutdown
// UI-sibling termination and the desktop's `stopAllOwnedServers` auto-
// update teardown. Calibrated against Hocuspocus's destroyTimeoutMs.
diff --git a/packages/core/src/logging/qa-secret-pattern-canary.test.ts b/packages/core/src/logging/qa-secret-pattern-canary.test.ts
new file mode 100644
index 000000000..2011bcacc
--- /dev/null
+++ b/packages/core/src/logging/qa-secret-pattern-canary.test.ts
@@ -0,0 +1,132 @@
+/**
+ * Exhaustive canary for every entry in `SECRET_PATTERNS`.
+ *
+ * Each pattern is live in the redactor and relied on by the diagnostic bundle,
+ * so a regex that stopped matching (an anchor change, a character-class
+ * narrowing, a dropped entry) would ship a live credential silently unless
+ * something plants a matching token.
+ *
+ * `PLANTED` is keyed by pattern name and cross-checked against
+ * `SECRET_PATTERN_NAMES`, so adding a pattern without a canary fails here
+ * rather than quietly widening the untested set.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { redactSecrets, SECRET_PATTERN_NAMES, scrubSecrets } from './secret-scrub.ts';
+
+/** One planted, secret-shaped token per named pattern, with the token that must vanish. */
+const PLANTED: Record<string, { input: string; secret: string; marker: string }> = {
+ 'macos-home-path': {
+ input: 'opened /Users/alice/notes/plan.md',
+ secret: '/Users/alice/',
+ marker: '~/',
+ },
+ 'linux-home-path': {
+ input: 'opened /home/alice/notes/plan.md',
+ secret: '/home/alice/',
+ marker: '~/',
+ },
+ 'github-pat': {
+ input: 'token was ghp_0123456789abcdefghijklmnopqrstuvwxyz sent',
+ secret: 'ghp_0123456789abcdefghijklmnopqrstuvwxyz',
+ marker: '[REDACTED-GH-PAT]',
+ },
+ 'aws-access-key': {
+ input: 'creds AKIAIOSFODNN7EXAMPLE here',
+ secret: 'AKIAIOSFODNN7EXAMPLE',
+ marker: '[REDACTED-AWS-KEY]',
+ },
+ 'anthropic-key': {
+ input: 'key=sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123',
+ secret: 'sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123',
+ marker: '[REDACTED-ANTHROPIC]',
+ },
+ 'openai-key': {
+ input: 'key=sk-abcdefghijklmnopqrstuvwxyz012345',
+ secret: 'sk-abcdefghijklmnopqrstuvwxyz012345',
+ marker: '[REDACTED-OPENAI]',
+ },
+ 'bearer-token': {
+ input: 'Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123456789',
+ secret: 'abcdefghijklmnopqrstuvwxyz0123456789',
+ marker: '[REDACTED',
+ },
+ jwt: {
+ input:
+ 'jwt eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4ifQ.dBjftJeZ4CVPmB92K27uhbUJU1p1r_wW1gFWFOEjXk',
+ secret: 'eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4ifQ',
+ marker: '[REDACTED',
+ },
+ 'url-credentials': {
+ input: 'url=https://user:hunter2@host/db',
+ secret: 'hunter2',
+ marker: '://[REDACTED]@',
+ },
+ 'github-pat-fine-grained': {
+ input: 'token github_pat_11ABCDEFG0aBcDeFgHiJ012345_kLmNoPqRsTuVwXyZ sent',
+ secret: 'github_pat_11ABCDEFG0aBcDeFgHiJ012345_kLmNoPqRsTuVwXyZ',
+ marker: '[REDACTED-GH-PAT]',
+ },
+ 'openai-key-modern': {
+ input: 'key=sk-proj-abcdefghijklmnopqrstuvwxyz0123456789ABCD',
+ secret: 'sk-proj-abcdefghijklmnopqrstuvwxyz0123456789ABCD',
+ marker: '[REDACTED-OPENAI]',
+ },
+ 'slack-token': {
+ input: 'slack xoxb-24209812345-67890abcdefXYZ token',
+ secret: 'xoxb-24209812345-67890abcdefXYZ',
+ marker: '[REDACTED-SLACK]',
+ },
+ 'google-api-key': {
+ input: 'gkey AIzaSyA1B2C3D4E5F6G7H8I9J0KLMNOPQRSTUVW here',
+ secret: 'AIzaSyA1B2C3D4E5F6G7H8I9J0KLMNOPQRSTUVW',
+ marker: '[REDACTED-GOOGLE]',
+ },
+ 'stripe-secret-key': {
+ input: 'stripe sk_live_abcdefghij0123456789 here',
+ secret: 'sk_live_abcdefghij0123456789',
+ marker: '[REDACTED-STRIPE]',
+ },
+ 'gitlab-pat': {
+ input: 'gitlab glpat-abcdefghij0123456789XYZ done',
+ secret: 'glpat-abcdefghij0123456789XYZ',
+ marker: '[REDACTED-GITLAB]',
+ },
+ 'bearer-token-json': {
+ input: '{"authorization":"Bearer opaqueBearerToken1234567890abcXYZ","k":1}',
+ secret: 'opaqueBearerToken1234567890abcXYZ',
+ marker: '[REDACTED',
+ },
+};
+
+describe('secret-pattern canary', () => {
+ it('plants a canary for every named pattern (adding a pattern without one fails here)', () => {
+ expect([...SECRET_PATTERN_NAMES].sort()).toEqual(Object.keys(PLANTED).sort());
+ });
+
+ for (const [name, { input, secret, marker }] of Object.entries(PLANTED)) {
+ it(`scrubs a planted ${name}`, () => {
+ // Planted-positive control: the raw token really is present pre-scrub, so
+ // a canary that silently stopped containing its own secret can't pass.
+ expect(input).toContain(secret);
+
+ const scrubbed = scrubSecrets(input);
+ expect(scrubbed).not.toContain(secret);
+ expect(scrubbed).toContain(marker);
+
+ // The line-wise redactor must attribute the hit to this pattern by name.
+ expect(redactSecrets(input).patterns).toContain(name);
+ });
+ }
+
+ it('scrubs every planted secret when they arrive together in one blob', () => {
+ const blob = Object.values(PLANTED)
+ .map((p) => p.input)
+ .join('\n');
+ const scrubbed = scrubSecrets(blob);
+ for (const { secret } of Object.values(PLANTED)) {
+ expect(scrubbed).not.toContain(secret);
+ }
+ expect(redactSecrets(blob).patterns.sort()).toEqual([...SECRET_PATTERN_NAMES].sort());
+ });
+});
diff --git a/packages/core/src/logging/renderer-capture-scrub-coverage.test.ts b/packages/core/src/logging/renderer-capture-scrub-coverage.test.ts
new file mode 100644
index 000000000..115a32aee
--- /dev/null
+++ b/packages/core/src/logging/renderer-capture-scrub-coverage.test.ts
@@ -0,0 +1,107 @@
+/**
+ * Structural guard — every renderer-console capture site scrubs credentials.
+ *
+ * A capture site is any module that turns raw browser `console` text into a log
+ * record. Every one of them necessarily calls the capture primitives this
+ * directory exports (`mapConsoleLevel` / `parseStructuredConsoleMessage`), so
+ * the sweep discovers sites by that call rather than from a hand-maintained
+ * list: a capture site added anywhere under `packages/<pkg>/src` is picked up by
+ * the commit that adds it, and fails here if it does not scrub.
+ *
+ * Raw console strings bypass pino's path-keyed `redact` entirely — a site that
+ * skips the scrub writes live credentials into a local log file that the
+ * bug-report bundle then reads, so the scrub has to happen at capture time.
+ *
+ * Why a source sweep rather than a runtime test: the sites live in
+ * `packages/desktop` and `packages/app`, neither of which `core` may import
+ * (the dependency edge points the other way), so no single test process can
+ * reach them all to drive a planted secret through. Each site carries its own
+ * planted-credential behavioral test; this sweep is what makes the coverage
+ * structural instead of per-site.
+ *
+ * `POST /api/client-logs` is deliberately not a capture site: it ingests
+ * already-captured, schema-validated entries from the web forwarder (which
+ * scrubs at capture) and calls none of these primitives.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+
+/** `…/packages/core/src/logging/` → `…/packages/`. */
+const PACKAGES_DIR = fileURLToPath(new URL('../../../', import.meta.url));
+
+/**
+ * A CALL of a capture primitive, not a mention: `renderer-log.ts` declares
+ * them and `schemas/api/client-logs.ts` names them in prose, and neither is a
+ * capture site.
+ */
+const CAPTURE_PRIMITIVE_CALL = /\b(?:mapConsoleLevel|parseStructuredConsoleMessage)\s*\(/;
+
+/** The canonical scrub, whether taken via the combined helper or directly. */
+const SCRUB_CALL = /\b(?:prepareCapturedConsoleMessage|scrubSecrets)\s*\(/;
+
+/** Where the primitives are declared — excluded so the module isn't its own site. */
+const DEFINITION_DIR = join('core', 'src', 'logging');
+
+const SKIP_DIR_NAMES = new Set(['node_modules', 'dist', 'out', 'build', '.turbo']);
+
+/**
+ * Sites known to exist today. Asserted as a lower bound so a walk that silently
+ * stops finding files (a renamed directory, a tightened skip list) fails here
+ * instead of passing with an empty sweep.
+ */
+const KNOWN_CAPTURE_SITES = [
+ 'app/src/lib/install-client-log-forwarder.ts',
+ 'desktop/src/main/renderer-console-capture.ts',
+];
+
+function listSourceFiles(dir: string, out: string[] = []): string[] {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ if (entry.name.startsWith('.') || SKIP_DIR_NAMES.has(entry.name)) continue;
+ const full = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ listSourceFiles(full, out);
+ continue;
+ }
+ if (!/\.tsx?$/.test(entry.name)) continue;
+ if (/\.(?:test|test-helper|e2e|private\.test)\.tsx?$/.test(entry.name)) continue;
+ out.push(full);
+ }
+ return out;
+}
+
+function findCaptureSites(): string[] {
+ const sites: string[] = [];
+ for (const pkg of readdirSync(PACKAGES_DIR, { withFileTypes: true })) {
+ if (!pkg.isDirectory() || SKIP_DIR_NAMES.has(pkg.name)) continue;
+ const srcDir = join(PACKAGES_DIR, pkg.name, 'src');
+ try {
+ if (!statSync(srcDir).isDirectory()) continue;
+ } catch {
+ continue; // package without a `src/` (fixtures, generated output)
+ }
+ for (const file of listSourceFiles(srcDir)) {
+ const rel = relative(PACKAGES_DIR, file);
+ if (rel.startsWith(DEFINITION_DIR) || rel.includes(join('/', DEFINITION_DIR))) continue;
+ if (CAPTURE_PRIMITIVE_CALL.test(readFileSync(file, 'utf8'))) {
+ sites.push(rel.split(/[\\/]/).join('/'));
+ }
+ }
+ }
+ return sites.sort();
+}
+
+describe('renderer-console capture sites', () => {
+ test('the sweep finds the capture sites that exist today', () => {
+ expect(findCaptureSites()).toEqual(expect.arrayContaining(KNOWN_CAPTURE_SITES));
+ });
+
+ test('every capture site scrubs the console text before it reaches a sink', () => {
+ const unscrubbed = findCaptureSites().filter(
+ (rel) => !SCRUB_CALL.test(readFileSync(join(PACKAGES_DIR, rel), 'utf8')),
+ );
+ expect(unscrubbed).toEqual([]);
+ });
+});
diff --git a/packages/core/src/logging/renderer-log.ts b/packages/core/src/logging/renderer-log.ts
index dc9ff7971..b345dd186 100644
--- a/packages/core/src/logging/renderer-log.ts
+++ b/packages/core/src/logging/renderer-log.ts
@@ -1,14 +1,23 @@
/**
* Shared, dependency-free helpers for capturing renderer/browser `console`
- * output into the on-disk pino logs. Consumed by all three capture sites so
- * they agree on level mapping, structured-message unwrapping, and batch bounds:
+ * output into the on-disk pino logs. Consumed by both capture sites — the
+ * modules that turn raw console text into a log record — so they agree on
+ * credential scrubbing, level mapping, structured-message unwrapping, and
+ * batch bounds:
* - Electron main `console-message` listener (`packages/desktop/src/main/renderer-console-capture.ts`)
- * - server `/api/client-logs` ingest handler (`packages/server/src/api-extension.ts`)
* - web renderer forwarder (`packages/app/src/lib/install-client-log-forwarder.ts`)
*
+ * The server's `/api/client-logs` ingest handler
+ * (`packages/server/src/api-extension.ts`) is downstream of the web forwarder,
+ * not a capture site: it receives entries the forwarder already scrubbed and
+ * schema-validated. `renderer-capture-scrub-coverage.test.ts` sweeps every
+ * caller of these primitives and fails on one that skips the scrub.
+ *
* Browser+Node safe (no deps) — lives in core alongside `schemas/api/*`.
*/
+import { scrubSecrets } from './secret-scrub.ts';
+
export type RendererLogLevel = 'info' | 'warn' | 'error';
/** Max console entries accepted per ingest batch (server Zod cap + client ring). */
@@ -62,13 +71,11 @@ export function mapConsoleLevel(level: string): RendererLogLevel | null {
* events as `console.warn(JSON.stringify({ event, ...fields }))` (e.g.
* provider-pool's `ok-provider-*` events). Lifting those into pino object
* fields makes them greppable and lets pino's path-based `redact` mask the
- * denylisted keys it covers (top-level + one level of nesting). NOTE: this is
- * NOT a full secret scrub — a raw (non-JSON) `console.*` string is logged
- * verbatim and never redacted, and lifted fields are only masked for the fixed
- * denylist at depth <= 1. Capturing all console output is a deliberate
- * local-diagnostics tradeoff; the ship-path backstop is `bug-report`'s
- * `redactContent` pass over every bundled file. Returns `null` when the message
- * is not a JSON object.
+ * denylisted keys it covers (top-level + one level of nesting). Call this on a
+ * message already run through {@link prepareCapturedConsoleMessage}: pino's
+ * keyed `redact` only masks the fixed denylist at depth <= 1, so a credential
+ * in any other field (or in a plain non-JSON string) is only removed by the
+ * capture-time scrub. Returns `null` when the message is not a JSON object.
*/
export function parseStructuredConsoleMessage(
message: string,
@@ -95,3 +102,17 @@ export function truncateLogMessage(message: string): string {
if (message.length <= RENDERER_LOG_MAX_MESSAGE_BYTES) return message;
return `${message.slice(0, RENDERER_LOG_MAX_MESSAGE_BYTES - TRUNCATION_SUFFIX.length)}${TRUNCATION_SUFFIX}`;
}
+
+/**
+ * Turn a raw console message into the text a capture site may hand to a sink:
+ * scrub credentials, then bound the length. Every capture site goes through
+ * this (or `scrubSecrets` directly) — a verbatim console string reaches the log
+ * file with no keyed-field redaction in front of it, so the scrub cannot be
+ * left to a downstream layer.
+ *
+ * Scrub BEFORE truncating: a secret straddling the cap would otherwise be cut
+ * mid-token, stop matching its pattern, and ship its surviving prefix.
+ */
+export function prepareCapturedConsoleMessage(message: string): string {
+ return truncateLogMessage(scrubSecrets(message));
+}
diff --git a/packages/core/src/logging/secret-scrub.test.ts b/packages/core/src/logging/secret-scrub.test.ts
new file mode 100644
index 000000000..80d631cae
--- /dev/null
+++ b/packages/core/src/logging/secret-scrub.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { redactSecrets, SECRET_PATTERN_NAMES, scrubSecrets } from './secret-scrub.ts';
+
+describe('scrubSecrets', () => {
+ it('leaves credential-free text unchanged', () => {
+ const clean = 'bridge drain settled: 3 docs converged';
+ expect(scrubSecrets(clean)).toBe(clean);
+ });
+
+ it('removes a GitHub personal access token', () => {
+ const secret = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';
+ const scrubbed = scrubSecrets(`token was ${secret} sent`);
+ expect(scrubbed).not.toContain(secret);
+ expect(scrubbed).toContain('[REDACTED-GH-PAT]');
+ });
+
+ it('removes an Anthropic API key and URL-embedded credentials', () => {
+ const key = 'sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123';
+ const scrubbed = scrubSecrets(`key=${key} url=https://user:hunter2@host/db`);
+ expect(scrubbed).not.toContain(key);
+ expect(scrubbed).not.toContain('hunter2');
+ expect(scrubbed).toContain('[REDACTED-ANTHROPIC]');
+ expect(scrubbed).toContain('://[REDACTED]@');
+ });
+
+ it('is idempotent: re-scrubbing already-scrubbed text is a no-op', () => {
+ const once = scrubSecrets('leaked ghp_0123456789abcdefghijklmnopqrstuvwxyz here');
+ expect(scrubSecrets(once)).toBe(once);
+ });
+
+ it('returns the redacted text of the shared line-wise redactor', () => {
+ const input = 'a\nghp_0123456789abcdefghijklmnopqrstuvwxyz\nb';
+ expect(scrubSecrets(input)).toBe(redactSecrets(input).redacted);
+ });
+});
+
+describe('redactSecrets', () => {
+ it('reports which named patterns matched with a per-line count', () => {
+ const result = redactSecrets(
+ 'line one clean\nghp_0123456789abcdefghijklmnopqrstuvwxyz\n/Users/alice/notes',
+ );
+ expect(result.patterns).toContain('github-pat');
+ expect(result.patterns).toContain('macos-home-path');
+ expect(result.lineCount).toBe(2);
+ expect(SECRET_PATTERN_NAMES).toContain('github-pat');
+ });
+
+ it('counts a line carrying two secrets once, not once per matching pattern', () => {
+ // `lineCount` is a distinct-modified-line count surfaced to users as
+ // "N line(s) scrubbed" — a single line with a token and a home path is one
+ // scrubbed line, not two.
+ const result = redactSecrets('ghp_0123456789abcdefghijklmnopqrstuvwxyz in /Users/alice/notes');
+ expect(result.patterns).toContain('github-pat');
+ expect(result.patterns).toContain('macos-home-path');
+ expect(result.lineCount).toBe(1);
+ });
+});
diff --git a/packages/core/src/logging/secret-scrub.ts b/packages/core/src/logging/secret-scrub.ts
new file mode 100644
index 000000000..16b9210d1
--- /dev/null
+++ b/packages/core/src/logging/secret-scrub.ts
@@ -0,0 +1,143 @@
+/**
+ * Canonical secret / credential scrub. One pattern list shared by every surface
+ * that captures text or ships it off the machine, so they can never drift:
+ *
+ * - the diagnostic-bundle assembly (`redactSecrets` over each staged file),
+ * - the web renderer console-capture forwarder, and
+ * - the Electron main `console-message` capture, whose sink is the local
+ * `~/.ok/logs/desktop.<date>.log`.
+ *
+ * Both capture sites take the scrub through `prepareCapturedConsoleMessage`
+ * (`renderer-log.ts`) or call `scrubSecrets` directly; the local log file has
+ * no keyed-field redaction in front of it, so capture time is the only place
+ * the scrub can happen.
+ *
+ * Best-effort pattern matching, not a guarantee — see the JWT / URL-credential
+ * note below. Credentials are scrubbed unconditionally; document titles and
+ * content are governed separately (never by this module).
+ *
+ * Browser-safe: pure string operations, no Node dependencies.
+ */
+
+interface SecretPattern {
+ name: string;
+ regex: RegExp;
+ replacement: string;
+}
+
+const SECRET_PATTERNS: readonly SecretPattern[] = [
+ { name: 'macos-home-path', regex: /\/Users\/[^/]+\//g, replacement: '~/' },
+ { name: 'linux-home-path', regex: /\/home\/[^/]+\//g, replacement: '~/' },
+ {
+ name: 'github-pat',
+ regex: /\b(ghp_|gho_|ghu_|ghs_|ghr_)[A-Za-z0-9]{36,}\b/g,
+ replacement: '[REDACTED-GH-PAT]',
+ },
+ {
+ name: 'aws-access-key',
+ regex: /\b(AKIA|ASIA|ABIA)[A-Z2-7]{16}\b/g,
+ replacement: '[REDACTED-AWS-KEY]',
+ },
+ {
+ name: 'anthropic-key',
+ regex: /\bsk-ant-api03-[A-Za-z0-9_-]{20,}\b/g,
+ replacement: '[REDACTED-ANTHROPIC]',
+ },
+ { name: 'openai-key', regex: /\bsk-[A-Za-z0-9]{20,}\b/g, replacement: '[REDACTED-OPENAI]' },
+ {
+ name: 'bearer-token',
+ regex: /([Aa]uthorization:\s*[Bb]earer\s+)\S+/g,
+ replacement: '$1[REDACTED]',
+ },
+ // JWTs (header.payload.signature; header + payload are base64url of `{`) and
+ // credentials embedded in URLs (`scheme://user:pass@host`, e.g. token push
+ // URLs / DB connection strings). No trailing `\b` on the JWT — base64url's
+ // `-`/`_` aren't word chars, so a signature ending in one wouldn't have a
+ // word boundary after it; the greedy class consumes the whole signature.
+ {
+ name: 'jwt',
+ regex: /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
+ replacement: '[REDACTED-JWT]',
+ },
+ {
+ name: 'url-credentials',
+ regex: /:\/\/[^/\s:@]+:[^/\s:@]+@/g,
+ replacement: '://[REDACTED]@',
+ },
+ // Current-default provider formats the classic prefixes above miss: GitHub
+ // fine-grained PATs (`github_pat_`, not `ghp_`), the OpenAI project/service
+ // keys issued since 2024 (`sk-proj-`/`sk-svcacct-`, whose `-` breaks the
+ // legacy `sk-[A-Za-z0-9]+`), plus Slack, Google, Stripe, and GitLab. Each is
+ // single-quantifier (no ReDoS); over-redaction is the safe direction.
+ {
+ name: 'github-pat-fine-grained',
+ regex: /\bgithub_pat_[0-9A-Za-z_]{20,}/g,
+ replacement: '[REDACTED-GH-PAT]',
+ },
+ {
+ name: 'openai-key-modern',
+ // No trailing \b: the body may end in `-`/`_` (same rationale as the jwt pattern).
+ regex: /\bsk-(?:proj|svcacct|admin|None)-[A-Za-z0-9_-]{20,}/g,
+ replacement: '[REDACTED-OPENAI]',
+ },
+ { name: 'slack-token', regex: /\bxox[a-z]-[A-Za-z0-9-]{10,}/g, replacement: '[REDACTED-SLACK]' },
+ { name: 'google-api-key', regex: /\bAIza[0-9A-Za-z_-]{35}/g, replacement: '[REDACTED-GOOGLE]' },
+ {
+ name: 'stripe-secret-key',
+ regex: /\b(?:sk|rk)_live_[0-9A-Za-z]{16,}\b/g,
+ replacement: '[REDACTED-STRIPE]',
+ },
+ { name: 'gitlab-pat', regex: /\bglpat-[0-9A-Za-z_-]{20,}/g, replacement: '[REDACTED-GITLAB]' },
+ {
+ name: 'bearer-token-json',
+ // JSON-serialized wire form: `"authorization":"Bearer <opaque>"`, which the
+ // colon-anchored `bearer-token` pattern above cannot see.
+ regex: /("[Aa]uthorization"\s*:\s*"[Bb]earer\s+)[^"]+/g,
+ replacement: '$1[REDACTED]',
+ },
+];
+
+/** Names of the redaction patterns, for a bundle's privacy summary. */
+export const SECRET_PATTERN_NAMES: readonly string[] = SECRET_PATTERNS.map((p) => p.name);
+
+/** Apply {@link SECRET_PATTERNS} line by line; report which patterns matched. */
+export function redactSecrets(content: string): {
+ redacted: string;
+ patterns: string[];
+ lineCount: number;
+} {
+ const matchedPatterns = new Set<string>();
+ let linesChanged = 0;
+ const lines = content.split('\n');
+
+ const redactedLines = lines.map((line) => {
+ let modified = line;
+ let changed = false;
+ for (const { name, regex, replacement } of SECRET_PATTERNS) {
+ regex.lastIndex = 0;
+ if (regex.test(modified)) {
+ matchedPatterns.add(name);
+ changed = true;
+ regex.lastIndex = 0;
+ modified = modified.replace(regex, replacement);
+ }
+ }
+ if (changed) linesChanged++;
+ return modified;
+ });
+
+ return {
+ redacted: redactedLines.join('\n'),
+ patterns: [...matchedPatterns],
+ lineCount: linesChanged,
+ };
+}
+
+/**
+ * Scrub credentials from a free-text string, returning only the cleaned text.
+ * The capture-time form for renderer console output, where the per-file audit
+ * that {@link redactSecrets} produces isn't needed.
+ */
+export function scrubSecrets(text: string): string {
+ return redactSecrets(text).redacted;
+}
diff --git a/packages/core/src/shadow-repo-layout.ts b/packages/core/src/shadow-repo-layout.ts
index 2095e4b51..d78abf77a 100644
--- a/packages/core/src/shadow-repo-layout.ts
+++ b/packages/core/src/shadow-repo-layout.ts
@@ -460,210 +460,29 @@ export function parseContributors(body: string): ShadowContributor[] {
return contributors;
}
-// ─── In-memory checkpoint body metadata ────────
-
-/** Prefix for the versioned checkpoint-metadata body line. */
-const OK_CHECKPOINT_PREFIX = 'ok-checkpoint-v1: ';
-
-/**
- * Kind-discriminated checkpoint metadata parsed from the `ok-checkpoint-v1:`
- * body line. The body line coexists with `ok-contributors:` lines —
- * `parseContributors` skips unknown prefixes, so the two channels do not
- * interfere.
- *
- * `docName` and `size` are carried inline so the `/api/rescue` read path can
- * enumerate checkpoints via a single batched `git log` without a per-ref
- * `git ls-tree` fan-out. They are
- * optional in the parsed shape for backward-compatible reads: pre-enrichment
- * commits returned `null` for both and the rescue list fell back to
- * `ls-tree`. New writes (`saveInMemoryCheckpoint`) always populate them.
- */
-/**
- * Why a service-authored consolidation fired. Bounded set so telemetry/diagnose
- * can read it back as a low-cardinality enum. Parsed back as a bare `string` for
- * forward-compatibility (a future trigger an old reader doesn't know about still
- * parses), so writers construct with this type but readers must not assume it.
- */
-export type AutoConsolidationTrigger = 'dead-chain' | 'session-close' | 'boot' | 'ttl';
-
-export type ParsedCheckpoint =
- | {
- // `which` distinguishes the post-condition verdict class ('substring' /
- // 'order' losses vs 'growth' gains) within the one merge checkpoint
- // kind. Optional: checkpoints written before the field existed parse
- // without it.
- kind: 'bridge-merge-loss';
- docName: string | null;
- size: number | null;
- metadata: { lostSubstrings: string[]; which?: string };
- }
- | {
- // Observer A's producer guard detected serialize output that fails
- // structural legality (a fresh parse loses authored content) at the
- // serialize boundary — distinct from `bridge-merge-loss` (a Path B merge
- // drop) so the two detection sites keep separate retention budgets and
- // TimelinePanel can tell serializer-corruption from merge-drop. `construct`
- // is a bounded, content-free locator of the danger-space node types
- // present (e.g. `jsxComponent,tableCell`), never raw content.
- kind: 'producer-guard-loss';
- docName: string | null;
- size: number | null;
- metadata: { construct: string };
- }
- | {
- // Observer A's duplication gate detected a CRDT double-materialization of
- // a bridge-derived span (a substantive body line present in the fragment
- // more times than Y.Text justified, provenance-confirmed as a
- // server-vs-client race) and re-derived the fragment from Y.Text before
- // it could persist. `contents` is the pre-recovery doubled fragment
- // serialization — the anchor if the re-derive was wrong.
- // `duplicatedLineCount` is a content-free count, never raw content.
- kind: 'observer-a-duplication';
- docName: string | null;
- size: number | null;
- metadata: { duplicatedLineCount: number };
- }
- | {
- kind: 'external-change-rescue';
- docName: string | null;
- size: number | null;
- metadata: { incomingDiskSha: string };
- }
- | {
- // Service-authored consolidation of dead/stale WIP chains.
- // GET /api/history excludes this kind by default so daily
- // auto-consolidations never pollute timelines; old readers that predate
- // this kind get `null` from parseCheckpoint (the unknown-kind fallback)
- // and render it as a plain Save Version — data-safe, cosmetic only.
- kind: 'auto-consolidation';
- docName: string | null;
- size: number | null;
- metadata: { foldedRefs: number; trigger: string };
- };
-
-/**
- * Parse the `ok-checkpoint-v1:` metadata line from a commit message body.
- * Returns `null` when the line is absent, malformed JSON, has an unknown
- * `kind`, or has a metadata shape that doesn't match the expected kind.
- *
- * Parallel to `parseContributors` in spirit — silent fallback, no throws —
- * so TimelinePanel rendering can gracefully degrade to 'Save Version'
- * rendering for checkpoints without this body line.
- */
-export function parseCheckpoint(body: string): ParsedCheckpoint | null {
- if (!body) return null;
- for (const line of body.split('\n')) {
- const trimmed = line.trim();
- if (!trimmed.startsWith(OK_CHECKPOINT_PREFIX)) continue;
- let parsed: unknown;
- try {
- parsed = JSON.parse(trimmed.slice(OK_CHECKPOINT_PREFIX.length));
- } catch {
- return null;
- }
- if (parsed === null || typeof parsed !== 'object') return null;
- const obj = parsed as {
- kind?: unknown;
- metadata?: unknown;
- docName?: unknown;
- size?: unknown;
- };
- const kind = obj.kind;
- const metadata = obj.metadata;
- if (metadata === null || typeof metadata !== 'object') return null;
- const docName = typeof obj.docName === 'string' ? obj.docName : null;
- const size = typeof obj.size === 'number' && Number.isFinite(obj.size) ? obj.size : null;
- if (kind === 'bridge-merge-loss') {
- const m = metadata as { lostSubstrings?: unknown };
- if (Array.isArray(m.lostSubstrings) && m.lostSubstrings.every((s) => typeof s === 'string')) {
- return {
- kind: 'bridge-merge-loss',
- docName,
- size,
- metadata: { lostSubstrings: m.lostSubstrings as string[] },
- };
- }
- return null;
- }
- if (kind === 'producer-guard-loss') {
- const m = metadata as { construct?: unknown };
- if (typeof m.construct === 'string') {
- return {
- kind: 'producer-guard-loss',
- docName,
- size,
- metadata: { construct: m.construct },
- };
- }
- return null;
- }
- if (kind === 'observer-a-duplication') {
- const m = metadata as { duplicatedLineCount?: unknown };
- if (typeof m.duplicatedLineCount === 'number' && Number.isFinite(m.duplicatedLineCount)) {
- return {
- kind: 'observer-a-duplication',
- docName,
- size,
- metadata: { duplicatedLineCount: m.duplicatedLineCount },
- };
- }
- return null;
- }
- if (kind === 'external-change-rescue') {
- const m = metadata as { incomingDiskSha?: unknown };
- if (typeof m.incomingDiskSha === 'string') {
- return {
- kind: 'external-change-rescue',
- docName,
- size,
- metadata: { incomingDiskSha: m.incomingDiskSha },
- };
- }
- return null;
- }
- if (kind === 'auto-consolidation') {
- const m = metadata as { foldedRefs?: unknown; trigger?: unknown };
- if (
- typeof m.foldedRefs === 'number' &&
- Number.isFinite(m.foldedRefs) &&
- typeof m.trigger === 'string'
- ) {
- return {
- kind: 'auto-consolidation',
- docName,
- size,
- metadata: { foldedRefs: m.foldedRefs, trigger: m.trigger },
- };
- }
- return null;
- }
- return null;
- }
- return null;
-}
-
-/**
- * Format the `ok-checkpoint-v1:` body line for a given kind+metadata. Produces
- * exactly one line (no trailing newline). Consumers embed it inside a full
- * commit message body as a sibling to `ok-contributors:` lines.
- *
- * Exported so `saveInMemoryCheckpoint` in the server package can share this
- * serialization rule with the parser — see precedent #4 (shared computation).
- */
-export function formatCheckpointBodyLine(parsed: ParsedCheckpoint): string {
- const payload: {
- kind: ParsedCheckpoint['kind'];
- docName?: string;
- size?: number;
- metadata: ParsedCheckpoint['metadata'];
- } = {
- kind: parsed.kind,
- metadata: parsed.metadata,
- };
- if (parsed.docName !== null) payload.docName = parsed.docName;
- if (parsed.size !== null) payload.size = parsed.size;
- return `${OK_CHECKPOINT_PREFIX}${JSON.stringify(payload)}`;
-}
+export type {
+ AutoConsolidationTrigger,
+ CheckpointBundleExposure,
+ CheckpointKind,
+ CheckpointKindAttributes,
+ CheckpointVisibility,
+ ParsedCheckpoint,
+} from './checkpoint-kinds.ts';
+// ─── Checkpoint metadata + kind registry (re-exported) ───────────────────────
+//
+// The checkpoint-body metadata types/parsers and the shared kind registry moved
+// to `./checkpoint-kinds.ts` — pure data with no `node:fs`, so the browser
+// barrel can re-export the registry and the editor UI can drive row visibility
+// off the same attributes the server GC/timeline/bundle paths use. Re-exported
+// here unchanged so every Node-only `@inkeep/open-knowledge-core/shadow-repo-layout`
+// consumer keeps its existing import site.
+export {
+ CHECKPOINT_KIND_REGISTRY,
+ CHECKPOINT_KINDS,
+ formatCheckpointBodyLine,
+ isSurfacedCheckpointKind,
+ parseCheckpoint,
+} from './checkpoint-kinds.ts';
// ─── ok-actor: body line ─────────────────────────────────────────────────────
diff --git a/packages/desktop/src/main/background-throttle.test.ts b/packages/desktop/src/main/background-throttle.test.ts
new file mode 100644
index 000000000..67991564c
--- /dev/null
+++ b/packages/desktop/src/main/background-throttle.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+ applyBackgroundThrottle,
+ type BackgroundThrottleSignal,
+ computeBackgroundThrottlingAllowed,
+ type ThrottleableWebContents,
+} from './background-throttle.ts';
+
+/**
+ * Coverage for the desktop background-throttling toggle. The observable under
+ * test is BEHAVIOR — the `setBackgroundThrottling(allowed)` call on the (fake)
+ * webContents and the boolean the predicate resolves — never the value of a
+ * config string or the presence of source text. A toggle that reads the flag
+ * but no longer applies it would pass a flag-text assertion and fail here.
+ *
+ * Residual (carried, not claimed): whether a backgrounded window actually
+ * keeps its timers alive is an OS/Chromium behavior only observable in a
+ * packaged desktop build. That rides the advisory desktop-smoke tier; these
+ * hermetic tests cover the predicate and the toggle application, not the
+ * real throttling effect.
+ */
+
+/** Hand-rolled webContents fake capturing the toggle's only two touches. */
+function makeFakeWebContents(opts: { destroyed?: boolean } = {}) {
+ const setBackgroundThrottling = vi.fn<(allowed: boolean) => void>();
+ const wc: ThrottleableWebContents = {
+ isDestroyed: () => opts.destroyed ?? false,
+ setBackgroundThrottling,
+ };
+ return { wc, setBackgroundThrottling };
+}
+
+describe('computeBackgroundThrottlingAllowed', () => {
+ it('suppresses throttling only when enabled AND there is pending work', () => {
+ expect(computeBackgroundThrottlingAllowed({ enabled: true, hasPendingWork: true })).toBe(false);
+ });
+
+ it('allows throttling (OS default) when enabled but no pending work', () => {
+ expect(computeBackgroundThrottlingAllowed({ enabled: true, hasPendingWork: false })).toBe(true);
+ });
+
+ it('allows throttling (inert) when the kill-switch is OFF, even with pending work', () => {
+ expect(computeBackgroundThrottlingAllowed({ enabled: false, hasPendingWork: true })).toBe(true);
+ });
+
+ it('allows throttling when the kill-switch is OFF and no pending work', () => {
+ expect(computeBackgroundThrottlingAllowed({ enabled: false, hasPendingWork: false })).toBe(
+ true,
+ );
+ });
+
+ it('never leaves a window permanently unthrottled: no-pending-work always allows throttling', () => {
+ for (const enabled of [true, false]) {
+ const signal: BackgroundThrottleSignal = { enabled, hasPendingWork: false };
+ expect(computeBackgroundThrottlingAllowed(signal)).toBe(true);
+ }
+ });
+});
+
+describe('applyBackgroundThrottle', () => {
+ it('keeps timers alive (setBackgroundThrottling false) when work is pending and enabled', () => {
+ const { wc, setBackgroundThrottling } = makeFakeWebContents();
+ applyBackgroundThrottle(wc, { enabled: true, hasPendingWork: true });
+ expect(setBackgroundThrottling).toHaveBeenCalledTimes(1);
+ expect(setBackgroundThrottling).toHaveBeenCalledWith(false);
+ });
+
+ it('restores the OS default (setBackgroundThrottling true) when the window goes clean', () => {
+ const { wc, setBackgroundThrottling } = makeFakeWebContents();
+ applyBackgroundThrottle(wc, { enabled: true, hasPendingWork: true });
+ applyBackgroundThrottle(wc, { enabled: true, hasPendingWork: false });
+ expect(setBackgroundThrottling).toHaveBeenLastCalledWith(true);
+ });
+
+ it('is inert when the kill-switch is OFF: applies the OS default despite pending work', () => {
+ const { wc, setBackgroundThrottling } = makeFakeWebContents();
+ applyBackgroundThrottle(wc, { enabled: false, hasPendingWork: true });
+ expect(setBackgroundThrottling).toHaveBeenCalledWith(true);
+ });
+
+ it('does not touch a destroyed webContents (shutdown race guard)', () => {
+ const { wc, setBackgroundThrottling } = makeFakeWebContents({ destroyed: true });
+ applyBackgroundThrottle(wc, { enabled: true, hasPendingWork: true });
+ expect(setBackgroundThrottling).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/desktop/src/main/background-throttle.ts b/packages/desktop/src/main/background-throttle.ts
new file mode 100644
index 000000000..423c4809d
--- /dev/null
+++ b/packages/desktop/src/main/background-throttle.ts
@@ -0,0 +1,65 @@
+/**
+ * Runtime toggle for a desktop window's Chromium background-throttling, keyed
+ * to whether the window holds unsynced work.
+ *
+ * Chromium throttles animations and timers in a backgrounded window by default
+ * (Electron `backgroundThrottling: true`). That default starves the CRDT sync
+ * and recovery loop exactly when a backgrounded window still has edits to
+ * flush. The renderer reports its unsynced state; main keeps timers alive
+ * (`setBackgroundThrottling(false)`) only while work is pending, and restores
+ * the OS-default throttling the moment the window is clean.
+ *
+ * The default is never disabled statically: `setBackgroundThrottling(false)`
+ * also disables the Page Visibility API (visibilitychange / presence), so a
+ * permanently-unthrottled window would break the flush-on-hide and presence
+ * paths that depend on those events. The toggle returns to the OS default
+ * whenever `hasPendingWork` is false — see `computeBackgroundThrottlingAllowed`.
+ *
+ * Ownership: the desktop app is the Chromium embedder, so the policy (the
+ * predicate) lives here in main, keyed off a signal only the renderer can
+ * observe (per-doc unsynced state). The kill-switch travels in the signal so a
+ * disabled config resolves to the OS default uniformly through the same
+ * predicate.
+ */
+
+export interface BackgroundThrottleSignal {
+ /** True while any open doc in the window has work the server has not yet acked. */
+ hasPendingWork: boolean;
+ /** The `bridge.backgroundThrottle.enabled` kill-switch, resolved renderer-side. */
+ enabled: boolean;
+}
+
+/**
+ * The value to pass to `webContents.setBackgroundThrottling(allowed)`:
+ * `true` = throttling allowed (the OS default), `false` = keep timers alive.
+ *
+ * Throttling is suppressed only when the mechanism is enabled AND the window
+ * has pending work; every other case restores the OS default. In particular
+ * `hasPendingWork === false` always yields `true`, so the toggle can never
+ * leave a window permanently unthrottled — that would break the Page
+ * Visibility API the flush-on-hide and presence paths depend on.
+ */
+export function computeBackgroundThrottlingAllowed(signal: BackgroundThrottleSignal): boolean {
+ return !(signal.enabled && signal.hasPendingWork);
+}
+
+/** Structural subset of Electron's `WebContents` this toggle touches. */
+export interface ThrottleableWebContents {
+ isDestroyed(): boolean;
+ setBackgroundThrottling(allowed: boolean): void;
+}
+
+/**
+ * Apply the throttling policy to one window's webContents.
+ *
+ * The `isDestroyed()` guard handles the shutdown race: the signal crosses the
+ * renderer→main IPC seam and can arrive between a window's `closed` event and
+ * the next GC pass, and calling into a destroyed webContents throws.
+ */
+export function applyBackgroundThrottle(
+ webContents: ThrottleableWebContents,
+ signal: BackgroundThrottleSignal,
+): void {
+ if (webContents.isDestroyed()) return;
+ webContents.setBackgroundThrottling(computeBackgroundThrottlingAllowed(signal));
+}
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 03c0bdf12..55472d8b1 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -156,6 +156,7 @@ import {
channelFromVersion,
type StartAutoUpdaterHandle,
} from './auto-updater.ts';
+import { applyBackgroundThrottle } from './background-throttle.ts';
import { resolveBootRestoreDecision, resolveRestoreActions } from './boot-restore-decision.ts';
import { readBootSessionUuid } from './boot-session.ts';
import { runBootstrap } from './bootstrap.ts';
@@ -4605,6 +4606,15 @@ function registerIpcHandlers() {
return undefined;
});
+ handle('ok:editor:background-throttle', async (event, signal) => {
+ // Keep the sender window's Chromium timers alive while it holds unsynced
+ // work, so backgrounding never starves sync/recovery; restore the OS
+ // default when it goes clean. Policy lives here in main (the embedder);
+ // the renderer only reports the signal.
+ applyBackgroundThrottle(event.sender, signal);
+ return undefined;
+ });
+
handle('ok:clipboard:write-text', async (_event, text) => {
clipboard.writeText(text);
return undefined;
diff --git a/packages/desktop/src/main/renderer-console-capture.test.ts b/packages/desktop/src/main/renderer-console-capture.test.ts
index 13d7e87b9..2780cdb6c 100644
--- a/packages/desktop/src/main/renderer-console-capture.test.ts
+++ b/packages/desktop/src/main/renderer-console-capture.test.ts
@@ -1,3 +1,4 @@
+import { RENDERER_LOG_MAX_MESSAGE_BYTES } from '@inkeep/open-knowledge-core';
import { describe, expect, test } from 'vitest';
import {
attachRendererConsoleCapture,
@@ -126,6 +127,67 @@ describe('attachRendererConsoleCapture', () => {
expect(spy.calls[0]?.msg).toBe('just a string');
});
+ test('scrubs credentials out of a plain-string message before it reaches the log', () => {
+ const wc = makeFakeWebContents();
+ const spy = makeSpyLogger();
+ attachRendererConsoleCapture(wc, { getLogger: spy.getLogger });
+
+ const secret = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';
+ const raw = `push from /Users/alice/notes failed: ${secret}`;
+ // Planted-positive control: the token really is in the emitted console text.
+ expect(raw).toContain(secret);
+ wc.emit({ level: 'error', message: raw });
+
+ const call = spy.calls[0];
+ if (!call) throw new Error('expected exactly one log call');
+ expect(call.msg).not.toContain(secret);
+ expect(call.msg).toContain('[REDACTED-GH-PAT]');
+ expect(call.msg).not.toContain('/Users/alice/');
+ expect(call.msg).toContain('~/notes');
+ });
+
+ test('scrubs credentials out of lifted structured fields, which pino redact never sees', () => {
+ const wc = makeFakeWebContents();
+ const spy = makeSpyLogger();
+ attachRendererConsoleCapture(wc, { getLogger: spy.getLogger });
+
+ const secret = 'AKIAIOSFODNN7EXAMPLE';
+ wc.emit({
+ level: 'warning',
+ message: JSON.stringify({
+ event: 'ok-provider-auth-failed',
+ // Not a key on the desktop logger's `redact` denylist — a keyed-field
+ // redaction pass cannot reach it, so only a capture-time scrub can.
+ reason: `rejected creds ${secret}`,
+ docPath: '/Users/alice/notes/plan.md',
+ }),
+ });
+
+ const call = spy.calls[0];
+ if (!call) throw new Error('expected exactly one log call');
+ expect(call.data.reason).toBe('rejected creds [REDACTED-AWS-KEY]');
+ expect(call.data.docPath).toBe('~/notes/plan.md');
+ expect(JSON.stringify(call.data)).not.toContain(secret);
+ });
+
+ test('scrubs before truncating so a secret straddling the cap cannot survive', () => {
+ const wc = makeFakeWebContents();
+ const spy = makeSpyLogger();
+ attachRendererConsoleCapture(wc, { getLogger: spy.getLogger });
+
+ const secret = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';
+ // Straddle the message cap: truncating first cuts the token in half, the
+ // pattern stops matching, and the surviving prefix ships verbatim.
+ const filler = 'x'.repeat(RENDERER_LOG_MAX_MESSAGE_BYTES - 33);
+ wc.emit({ level: 'info', message: `${filler} ${secret} trailing` });
+
+ const call = spy.calls[0];
+ if (!call) throw new Error('expected exactly one log call');
+ expect(call.msg).not.toContain('ghp_');
+ expect(call.msg).toContain('[REDACTED-GH-PAT]');
+ expect(call.msg.length).toBeLessThanOrEqual(RENDERER_LOG_MAX_MESSAGE_BYTES);
+ });
+
test('a throwing logger never propagates out of the listener', () => {
const wc = makeFakeWebContents();
attachRendererConsoleCapture(wc, {
diff --git a/packages/desktop/src/main/renderer-console-capture.ts b/packages/desktop/src/main/renderer-console-capture.ts
index 2fd6239e5..5bb10417f 100644
--- a/packages/desktop/src/main/renderer-console-capture.ts
+++ b/packages/desktop/src/main/renderer-console-capture.ts
@@ -15,7 +15,7 @@
import {
mapConsoleLevel,
parseStructuredConsoleMessage,
- truncateLogMessage,
+ prepareCapturedConsoleMessage,
} from '@inkeep/open-knowledge-core';
import { getLogger } from './desktop-logger.ts';
@@ -71,7 +71,11 @@ export function attachRendererConsoleCapture(
try {
const level = mapConsoleLevel(event.level);
if (!level) return;
- const message = truncateLogMessage(event.message ?? '');
+ // Scrub credentials at capture time: this message becomes pino's `msg`
+ // (and, when structured, its lifted fields), and the desktop logger's
+ // `redact` is path-keyed — it never inspects either. Scrubbing here also
+ // masks `/Users/<name>/` to `~/` in the local log.
+ const message = prepareCapturedConsoleMessage(event.message ?? '');
const structured = parseStructuredConsoleMessage(message);
// Spread the renderer-supplied fields FIRST so our provenance markers
// below always win — a renderer JSON payload must not be able to clobber
diff --git a/packages/desktop/src/preload/index.ts b/packages/desktop/src/preload/index.ts
index 13ee39756..8095a3495 100644
--- a/packages/desktop/src/preload/index.ts
+++ b/packages/desktop/src/preload/index.ts
@@ -732,6 +732,11 @@ const bridge: OkDesktopBridge = {
// state. Same swallow-rejection contract as the active-target push.
invoke('ok:editor:view-menu-state-changed', state).catch(() => {});
},
+ notifyBackgroundThrottle: (signal: { hasPendingWork: boolean; enabled: boolean }) => {
+ // Sibling fire-and-forget push keying the window's background-throttling
+ // to unsynced work. Same swallow-rejection contract as the pushes above.
+ invoke('ok:editor:background-throttle', signal).catch(() => {});
+ },
},
menu: {
diff --git a/packages/desktop/src/shared/bridge-contract.ts b/packages/desktop/src/shared/bridge-contract.ts
index 05af5e46c..2132d13f4 100644
--- a/packages/desktop/src/shared/bridge-contract.ts
+++ b/packages/desktop/src/shared/bridge-contract.ts
@@ -1990,6 +1990,15 @@ export interface OkDesktopBridge {
* windows — matches the active-target singleton model.
*/
notifyViewMenuStateChanged(state: Partial<OkEditorViewMenuStateSnapshot>): void;
+ /**
+ * Fire-and-forget push keying the window's Chromium background-throttling
+ * to its unsynced work. `hasPendingWork` is the renderer's aggregate
+ * unsynced-work flag; `enabled` is the resolved
+ * `bridge.backgroundThrottle.enabled` kill-switch. Main runs the toggle
+ * predicate on the sender window's webContents. Reported on each
+ * transition of either input.
+ */
+ notifyBackgroundThrottle(signal: { hasPendingWork: boolean; enabled: boolean }): void;
};
/**
diff --git a/packages/desktop/src/shared/ipc-channels.ts b/packages/desktop/src/shared/ipc-channels.ts
index 79f969e7e..d7c1d9028 100644
--- a/packages/desktop/src/shared/ipc-channels.ts
+++ b/packages/desktop/src/shared/ipc-channels.ts
@@ -60,11 +60,16 @@
* (`ok:terminal:set-dock-state`). The 87→88 bump reconciled the Windows/Linux
* desktop port: the win/linux renderer menubar (`ok:menu:dispatch`, a
* discriminated fold per the sharing-dispatch precedent — the custom-drawn menu
- * bar's whole surface in one slot). The 88→89 bump added the React self-uninstall
- * window (`ok:uninstall:dispatch`), the last renderer→main surface that still
- * rode a private URL scheme through `will-navigate`; folding all four screens
- * plus the screen pull into one slot keeps the whole migration at one channel.
- * Full rationale in the ratchet test header.
+ * bar's whole surface in one slot). The 88→90 bumps landed as two independent
+ * additions. One is the React self-uninstall window (`ok:uninstall:dispatch`),
+ * the last renderer→main surface that still rode a private URL scheme through
+ * `will-navigate`; folding all four screens plus the screen pull into one slot
+ * keeps the whole migration at one channel. The other is the desktop
+ * background-throttling toggle (`ok:editor:background-throttle`), keying a
+ * window's Chromium timers to its unsynced work — it could not fold onto the
+ * sibling `ok:editor:*` snapshots (different cadence, and a fold would rebuild
+ * the app menu on every keystroke-to-sync edge). Full rationale in the ratchet
+ * test header.
*/
import type {
@@ -1555,6 +1560,24 @@ export interface RequestChannels {
args: [state: Partial<EditorViewMenuStateSnapshot>];
result: undefined;
};
+ /**
+ * Renderer → main fire-and-forget push keying the sender window's Chromium
+ * background-throttling to its unsynced work. `hasPendingWork` is the
+ * renderer's aggregate unsynced-work flag; `enabled` is the resolved
+ * `bridge.backgroundThrottle.enabled` kill-switch. Main runs the toggle
+ * predicate and calls `setBackgroundThrottling` on `event.sender`.
+ *
+ * Could not fold onto the sibling `ok:editor:*` snapshots: those fire on
+ * active-target / view-menu changes and drive `refreshApplicationMenu`, a
+ * different cadence and side effect than an unsynced-work transition — a
+ * fold would spuriously rebuild the menu on every keystroke-to-sync edge.
+ * Modeled as a request channel so the preload `invoke().catch(()=>{})`
+ * pattern composes through the typed `createInvoker` wrapper.
+ */
+ 'ok:editor:background-throttle': {
+ args: [signal: { hasPendingWork: boolean; enabled: boolean }];
+ result: undefined;
+ };
/**
* Renderer-menubar dispatch (the windows-linux-port renderer-menubar decision). One
* discriminated channel (the `ok:sharing:dispatch` precedent) for the
diff --git a/packages/desktop/tests/integration/ipc-channel-count-ratchet.test.ts b/packages/desktop/tests/integration/ipc-channel-count-ratchet.test.ts
index 881c698af..fc758afd5 100644
--- a/packages/desktop/tests/integration/ipc-channel-count-ratchet.test.ts
+++ b/packages/desktop/tests/integration/ipc-channel-count-ratchet.test.ts
@@ -363,20 +363,32 @@ const CHANNELS_SRC = readFileSync(SRC_PATH, 'utf-8');
* migration remains the committed end state, with the `ipc-channels.ts` header
* updated in lock-step.
*
- * Bumped from 88 to 89 for the React self-uninstall window
- * (`ok:uninstall:dispatch`). The uninstall screens were the last renderer→main
- * surface still riding a private `ok-desktop-uninstall://` URL scheme
- * intercepted by `will-navigate`; moving them onto real IPC retires that
- * channel. Follows the `ok:sharing:dispatch` discriminated-union precedent —
- * the screen pull plus every intent from all four screens (picker, survey,
- * progress, notices) share ONE slot, so porting the remaining screens costs no
- * further channels. Could not fold into an existing channel: no renderer→main
- * uninstall surface existed, and the sender-validation rule (only a live
- * uninstall window is answered) is specific to this surface. The typed-ipc
- * migration remains the committed end state, with the `ipc-channels.ts` header
- * updated in lock-step.
+ * Bumped from 88 to 90 by two independent additions that landed together.
+ *
+ * 89 is the React self-uninstall window (`ok:uninstall:dispatch`). The
+ * uninstall screens were the last renderer→main surface still riding a private
+ * `ok-desktop-uninstall://` URL scheme intercepted by `will-navigate`; moving
+ * them onto real IPC retires that scheme. Follows the `ok:sharing:dispatch`
+ * discriminated-union precedent — the screen pull plus every intent from all
+ * four screens (picker, survey, progress, notices) share ONE slot, so porting
+ * the remaining screens costs no further channels. Could not fold into an
+ * existing channel: no renderer→main uninstall surface existed, and the
+ * sender-validation rule (only a live uninstall window is answered) is specific
+ * to this surface.
+ *
+ * 90 is the desktop background-throttling toggle
+ * (`ok:editor:background-throttle`): the renderer reports its aggregate
+ * unsynced-work state so main keeps the window's Chromium timers alive while
+ * work is pending. Could not fold onto the sibling `ok:editor:*` snapshots:
+ * those fire on active-target / view-menu changes and drive
+ * `refreshApplicationMenu`, a different cadence and side effect than an
+ * unsynced-work transition — a fold would rebuild the menu on every
+ * keystroke-to-sync edge.
+ *
+ * The typed-ipc migration remains the committed end state, with the
+ * `ipc-channels.ts` header updated in lock-step.
*/
-const REQUEST_CHANNEL_CAP = 89;
+const REQUEST_CHANNEL_CAP = 90;
/**
* Extract the body of an interface block by name. Returns the substring
diff --git a/packages/desktop/tests/smoke/background-throttle.e2e.ts b/packages/desktop/tests/smoke/background-throttle.e2e.ts
new file mode 100644
index 000000000..14663d467
--- /dev/null
+++ b/packages/desktop/tests/smoke/background-throttle.e2e.ts
@@ -0,0 +1,243 @@
+/**
+ * Runtime verification that Electron actually applies the background-throttling
+ * policy main computes from the renderer's unsynced-work signal. The Vitest
+ * unit test in `src/main/background-throttle.test.ts` pins the predicate and
+ * the toggle call against a `vi.fn()` webContents; this smoke test proves the
+ * real chain honors it end to end — renderer `window.okDesktop.editor
+ * .notifyBackgroundThrottle` -> preload `invoke` -> the
+ * `ok:editor:background-throttle` main handler -> a live Chromium
+ * `webContents` — by reading `webContents.backgroundThrottling` back from
+ * main-process context.
+ *
+ * The observable is the Chromium-side property, not a spy: a window holding
+ * unsynced work opts OUT of background throttling (`false`), and a clean
+ * window (or one whose kill-switch is off) sits at the OS default (`true`).
+ *
+ * Pattern mirrors `window-min-size.e2e.ts`:
+ * - Seed a tmp HOME with `lastOpenedProject` so the Editor window opens
+ * first (Navigator stays closed).
+ * - Launch with `--user-data-dir=<tmpHome>/electron-userdata`.
+ * - Find the Editor window, drive the real preload API from its renderer,
+ * read main-process state through `app.browserWindow(page)`.
+ *
+ * Each transition re-pushes its signal on every poll iteration. The renderer's
+ * own `BackgroundThrottleReporter` seeds main once on install and then pushes
+ * on true<->false unsynced-work edges, so a real edge during window warm-up
+ * could otherwise land between this test's push and its read; re-pushing makes
+ * the test's signal the last writer on each attempt rather than depending on
+ * the window being quiescent.
+ *
+ * Skip gates (same as the rest of the smoke suite):
+ * - `OK_DESKTOP_E2E_SMOKE !== '1'` — opt-in.
+ * - `process.platform !== 'darwin'` — darwin-only.
+ * - `out/main/index.js` missing — `pnpm run build:desktop` must have run.
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ElectronApplication, JSHandle, Page } from '@playwright/test';
+import { _electron as electron } from '@playwright/test';
+import { expect, test } from './_helpers/smoke-test';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+
+const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
+const DARWIN = process.platform === 'darwin';
+const BUILD_EXISTS = existsSync(MAIN_ENTRY);
+
+interface SeededHome {
+ tmpHome: string;
+ projectDir: string;
+}
+
+function userDataDirFor(tmpHome: string): string {
+ return join(tmpHome, 'electron-userdata');
+}
+
+function seedHomeWithLastOpenedProject(prefix: string): SeededHome {
+ const tmpHome = mkdtempSync(join(tmpdir(), `ok-bg-throttle-${prefix}-`));
+ const projectDir = mkdtempSync(join(tmpdir(), `ok-bg-throttle-${prefix}-project-`));
+ mkdirSync(join(projectDir, '.ok'), { recursive: true });
+ writeFileSync(
+ join(projectDir, '.ok', 'config.yml'),
+ "content:\n dir: '.'\n include: ['**/*.md']\n exclude: []\n",
+ );
+ const userDataDir = userDataDirFor(tmpHome);
+ mkdirSync(userDataDir, { recursive: true });
+ writeFileSync(
+ join(userDataDir, 'state.json'),
+ JSON.stringify({
+ recentProjects: [
+ {
+ path: projectDir,
+ name: 'Background Throttle Smoke',
+ lastOpenedAt: new Date().toISOString(),
+ },
+ ],
+ lastOpenedProject: projectDir,
+ versionPendingInstall: null,
+ lastSeenVersion: null,
+ lastSuccessfulCheckAt: null,
+ stuckHintShown: false,
+ }),
+ );
+ return { tmpHome, projectDir };
+}
+
+async function launchApp(tmpHome: string): Promise<ElectronApplication> {
+ return electron.launch({
+ args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ },
+ });
+}
+
+async function findWindow(
+ app: ElectronApplication,
+ mode: 'editor' | 'navigator',
+ timeoutMs = 20_000,
+): Promise<Page> {
+ await expect
+ .poll(
+ async () => {
+ for (const page of app.windows()) {
+ const m = await page
+ .evaluate(() => window.okDesktop?.config?.mode)
+ .catch(() => undefined);
+ if (m === mode) return true;
+ }
+ return false;
+ },
+ {
+ timeout: timeoutMs,
+ message: `${mode} window did not appear within timeout`,
+ },
+ )
+ .toBe(true);
+ for (const page of app.windows()) {
+ const m = await page.evaluate(() => window.okDesktop?.config?.mode).catch(() => undefined);
+ if (m === mode) return page;
+ }
+ throw new Error(`${mode} window vanished between poll resolution and read`);
+}
+
+/** Read the live Chromium property from main-process context. */
+async function readBackgroundThrottling(app: ElectronApplication, page: Page): Promise<boolean> {
+ const winHandle: JSHandle = await app.browserWindow(page);
+ return winHandle.evaluate((win: unknown) => {
+ // BrowserWindow types are not in scope inside evaluate's V8 context;
+ // `webContents.backgroundThrottling` is a runtime property on the
+ // BrowserWindow wrapper Playwright hands back. The cast is local here.
+ const w = win as { webContents: { backgroundThrottling: boolean } };
+ return w.webContents.backgroundThrottling;
+ });
+}
+
+interface ThrottleSignal {
+ hasPendingWork: boolean;
+ enabled: boolean;
+}
+
+/** Push the signal through the real preload bridge from the renderer. */
+async function pushSignal(page: Page, signal: ThrottleSignal): Promise<void> {
+ await page.evaluate((s) => {
+ window.okDesktop?.editor.notifyBackgroundThrottle(s);
+ }, signal);
+}
+
+/**
+ * Push `signal` and wait for Chromium's `backgroundThrottling` to settle on
+ * `expected`. The push repeats per poll iteration (see the file docblock).
+ */
+async function pushAndExpectThrottling(
+ app: ElectronApplication,
+ page: Page,
+ signal: ThrottleSignal,
+ expected: boolean,
+ label: string,
+): Promise<void> {
+ await expect
+ .poll(
+ async () => {
+ await pushSignal(page, signal);
+ return readBackgroundThrottling(app, page);
+ },
+ {
+ timeout: 10_000,
+ message: `${label}: expected webContents.backgroundThrottling === ${expected} after pushing ${JSON.stringify(signal)}`,
+ },
+ )
+ .toBe(expected);
+}
+
+test.describe('background-throttle smoke', () => {
+ test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
+ test.skip(!DARWIN, 'Smoke harness is darwin-only in v0.');
+ test.skip(
+ !BUILD_EXISTS,
+ `Main build missing at ${MAIN_ENTRY} — run "pnpm run build:desktop" first.`,
+ );
+
+ test('a window holding unsynced work opts out of Chromium background throttling until it is clean', async ({
+ captureStderrFor,
+ }) => {
+ const { tmpHome, projectDir } = seedHomeWithLastOpenedProject('happy');
+ const app = await launchApp(tmpHome);
+ captureStderrFor(app, { cleanupDirs: [tmpHome, projectDir] });
+
+ const editor = await findWindow(app, 'editor');
+
+ // Baseline: a window with no pending work sits at the OS default. The
+ // renderer's reporter seeds `hasPendingWork: false` on install, and the
+ // BrowserWindow is constructed with Electron's default throttling.
+ await expect
+ .poll(() => readBackgroundThrottling(app, editor), {
+ timeout: 10_000,
+ message: 'baseline: expected the OS default (backgroundThrottling === true)',
+ })
+ .toBe(true);
+
+ // Unsynced work: main must keep the window's timers alive.
+ await pushAndExpectThrottling(
+ app,
+ editor,
+ { hasPendingWork: true, enabled: true },
+ false,
+ 'pending work',
+ );
+
+ // Clean again: the OS default comes back, so the Page Visibility API the
+ // flush-on-hide and presence paths depend on keeps working.
+ await pushAndExpectThrottling(
+ app,
+ editor,
+ { hasPendingWork: false, enabled: true },
+ true,
+ 'work drained',
+ );
+
+ // Re-arm, then prove the kill-switch is honored at the real boundary:
+ // pending work with `enabled: false` returns to the OS default.
+ await pushAndExpectThrottling(
+ app,
+ editor,
+ { hasPendingWork: true, enabled: true },
+ false,
+ 're-armed pending work',
+ );
+ await pushAndExpectThrottling(
+ app,
+ editor,
+ { hasPendingWork: true, enabled: false },
+ true,
+ 'kill-switch off',
+ );
+ });
+});
diff --git a/packages/server/src/acp/thread-manager.ts b/packages/server/src/acp/thread-manager.ts
index 14a8edb71..89caf26bd 100644
--- a/packages/server/src/acp/thread-manager.ts
+++ b/packages/server/src/acp/thread-manager.ts
@@ -61,6 +61,7 @@ import { toBroadcasterKey } from '../agent-id.ts';
import type { AgentPresenceBroadcaster } from '../agent-presence.ts';
import {
type AgentSessionManager,
+ agentWriteLossDetect,
applyAgentMarkdownWrite,
snapshotBlocks,
} from '../agent-sessions.ts';
@@ -1919,7 +1920,14 @@ export class AcpThreadManager {
: undefined;
session.dc.document.transact(() => {
const beforeBlocks = snapshotBlocks(session.dc.document);
- applyAgentMarkdownWrite(session.dc.document, content, 'replace', embedResolver);
+ applyAgentMarkdownWrite(
+ session.dc.document,
+ content,
+ 'replace',
+ embedResolver,
+ undefined,
+ agentWriteLossDetect(session),
+ );
// Same-transaction flash entry, mirroring the HTTP agent-write
// handlers — drives the editor's write-flash + follow-the-write
// animation for thread writes too (and rides the per-session
diff --git a/packages/server/src/activity-log.test.ts b/packages/server/src/activity-log.test.ts
index fb77345fa..5f74f1b04 100644
--- a/packages/server/src/activity-log.test.ts
+++ b/packages/server/src/activity-log.test.ts
@@ -6,6 +6,12 @@ import * as Y from 'yjs';
import { captureEffect, type EffectValue } from './activity-log.ts';
import { getMetrics, resetMetrics } from './metrics.ts';
+/**
+ * The frozen per-session write origin these tests stand in for. `captureEffect`
+ * matches it by object identity, so every stimulus below transacts under it.
+ */
+const WRITE_ORIGIN = Object.freeze({ source: 'local', context: { origin: 'test-write' } });
+
function makeDoc() {
const doc = new Y.Doc();
const ytext = doc.getText('source');
@@ -19,10 +25,10 @@ beforeEach(() => {
describe('captureEffect — happy path', () => {
test('registers an effect entry in Y.Map("agent-effects") after a Y.Text change', () => {
const { doc, ytext } = makeDoc();
- captureEffect(ytext, 'agent-test', 'claude-code');
+ captureEffect(ytext, 'agent-test', WRITE_ORIGIN, 'claude-code');
doc.transact(() => {
ytext.insert(0, 'Hello world');
- });
+ }, WRITE_ORIGIN);
const effectsMap = doc.getMap<EffectValue>('agent-effects');
expect(effectsMap.size).toBe(1);
@@ -37,10 +43,10 @@ describe('captureEffect — happy path', () => {
test('stores agent_type from parameter', () => {
const { doc, ytext } = makeDoc();
- captureEffect(ytext, 'agent-abc', undefined, 'cursor');
+ captureEffect(ytext, 'agent-abc', WRITE_ORIGIN, undefined, 'cursor');
doc.transact(() => {
ytext.insert(0, 'data');
- });
+ }, WRITE_ORIGIN);
const effectsMap = doc.getMap<EffectValue>('agent-effects');
const value = [...effectsMap.values()][0] as EffectValue;
@@ -49,10 +55,10 @@ describe('captureEffect — happy path', () => {
test('defaults agent_type to "agent" when not provided', () => {
const { doc, ytext } = makeDoc();
- captureEffect(ytext, 'agent-xyz');
+ captureEffect(ytext, 'agent-xyz', WRITE_ORIGIN);
doc.transact(() => {
ytext.insert(0, 'test');
- });
+ }, WRITE_ORIGIN);
const effectsMap = doc.getMap<EffectValue>('agent-effects');
const value = [...effectsMap.values()][0] as EffectValue;
@@ -61,10 +67,10 @@ describe('captureEffect — happy path', () => {
test('delta captures Quill Delta ops (YTextEvent.delta)', () => {
const { doc, ytext } = makeDoc();
- captureEffect(ytext, 'agent-delta-test', 'blue');
+ captureEffect(ytext, 'agent-delta-test', WRITE_ORIGIN, 'blue');
doc.transact(() => {
ytext.insert(0, 'abc');
- });
+ }, WRITE_ORIGIN);
const effectsMap = doc.getMap<EffectValue>('agent-effects');
const value = [...effectsMap.values()][0] as EffectValue;
@@ -74,13 +80,13 @@ describe('captureEffect — happy path', () => {
test('is a one-shot observer — second write does not create new entry', () => {
const { doc, ytext } = makeDoc();
- captureEffect(ytext, 'agent-oneshot', 'seed');
+ captureEffect(ytext, 'agent-oneshot', WRITE_ORIGIN, 'seed');
doc.transact(() => {
ytext.insert(0, 'first');
- });
+ }, WRITE_ORIGIN);
doc.transact(() => {
ytext.insert(0, 'second');
- });
+ }, WRITE_ORIGIN);
const effectsMap = doc.getMap<EffectValue>('agent-effects');
expect(effectsMap.size).toBe(1);
@@ -89,7 +95,7 @@ describe('captureEffect — happy path', () => {
test('does nothing when ytext has no doc (early return)', () => {
// Creating a Y.Text without a Y.Doc — accessing .doc returns null
const orphanText = new Y.Text();
- expect(() => captureEffect(orphanText, 'agent-orphan')).not.toThrow();
+ expect(() => captureEffect(orphanText, 'agent-orphan', WRITE_ORIGIN)).not.toThrow();
});
});
@@ -98,10 +104,10 @@ describe('captureEffect — ring-buffer eviction', () => {
const { doc, ytext } = makeDoc();
for (let i = 0; i < 60; i++) {
- captureEffect(ytext, `agent-${i}`, 'seed');
+ captureEffect(ytext, `agent-${i}`, WRITE_ORIGIN, 'seed');
doc.transact(() => {
ytext.insert(0, `write-${i}`);
- });
+ }, WRITE_ORIGIN);
}
const effectsMap = doc.getMap<EffectValue>('agent-effects');
@@ -113,10 +119,10 @@ describe('captureEffect — ring-buffer eviction', () => {
// Artificially set timestamps to be distinguishable
for (let i = 0; i < 60; i++) {
- captureEffect(ytext, `agent-${i}`, 'seed');
+ captureEffect(ytext, `agent-${i}`, WRITE_ORIGIN, 'seed');
doc.transact(() => {
ytext.insert(0, `write-${i}`);
- });
+ }, WRITE_ORIGIN);
}
const effectsMap = doc.getMap<EffectValue>('agent-effects');
@@ -132,15 +138,15 @@ describe('captureEffect — ring-buffer eviction', () => {
test('two sessions produce distinct entries keyed by session ID', () => {
const { doc, ytext } = makeDoc();
- captureEffect(ytext, 'session-A', 'blue');
+ captureEffect(ytext, 'session-A', WRITE_ORIGIN, 'blue');
doc.transact(() => {
ytext.insert(0, 'from-A');
- });
+ }, WRITE_ORIGIN);
- captureEffect(ytext, 'session-B', 'red');
+ captureEffect(ytext, 'session-B', WRITE_ORIGIN, 'red');
doc.transact(() => {
ytext.insert(0, 'from-B');
- });
+ }, WRITE_ORIGIN);
const effectsMap = doc.getMap<EffectValue>('agent-effects');
expect(effectsMap.size).toBe(2);
@@ -165,7 +171,7 @@ describe('captureEffect — error handling (D37)', () => {
// captureEffect wires the observer but before the user's transact fires.
// This is the most reliable reproducer: observer runs, inner transact throws,
// catch block records the failure + increments the metric.
- captureEffect(ytext, 'agent-fail', 'seed');
+ captureEffect(ytext, 'agent-fail', WRITE_ORIGIN, 'seed');
const originalSet = effectsMap.set.bind(effectsMap);
(effectsMap as unknown as { set: typeof originalSet }).set = () => {
@@ -177,7 +183,7 @@ describe('captureEffect — error handling (D37)', () => {
try {
doc.transact(() => {
ytext.insert(0, 'trigger');
- });
+ }, WRITE_ORIGIN);
} finally {
process.env.NODE_ENV = prevEnv;
(effectsMap as unknown as { set: typeof originalSet }).set = originalSet;
@@ -189,7 +195,7 @@ describe('captureEffect — error handling (D37)', () => {
test('unobserves on doc destroy to prevent observer leak', () => {
const { doc, ytext } = makeDoc();
- captureEffect(ytext, 'agent-leak', 'seed');
+ captureEffect(ytext, 'agent-leak', WRITE_ORIGIN, 'seed');
// Destroying the doc before any write must detach the observer so a later
// (post-destroy) write on a reused ytext reference cannot fire the capture
diff --git a/packages/server/src/activity-log.ts b/packages/server/src/activity-log.ts
index 51bd32864..0349d4221 100644
--- a/packages/server/src/activity-log.ts
+++ b/packages/server/src/activity-log.ts
@@ -40,27 +40,47 @@ export interface EffectValue {
}
/**
- * Register a one-shot ytext observer that captures the next YTextEvent.delta
- * into Y.Map('agent-effects'). Must be called BEFORE the agent write transact.
+ * Register a one-shot ytext observer that captures the delta of the agent's own
+ * write transact into Y.Map('agent-effects'). Must be called BEFORE that
+ * transact.
*
- * @param ytext The Y.Text('source') instance to observe.
- * @param sessionId The agent's writer ID (e.g. 'agent-<connectionId>').
- * @param colorSeed Color seed for UI rendering (defaults to sessionId).
- * @param agentType Agent type string for UI aggregation (e.g. 'claude', 'cursor').
+ * The observer is ORIGIN-KEYED, not merely one-shot: it consumes only an event
+ * whose `transaction.origin` is `writeOrigin` by identity (the same frozen
+ * per-session object `Y.UndoManager` matches on, precedent #24). Origin-blind
+ * arming is unsound because non-agent Y.Text writes legitimately land between
+ * arming and the agent's transact — the pre-drain flush (`agentWritePreDrain`,
+ * under `OBSERVER_SYNC_ORIGIN`) is exactly that, and consuming it would file the
+ * USER's un-propagated keystroke as an agent effect while the agent's own write
+ * produced no row at all.
+ *
+ * Returns a disposer the caller runs when the operation ends (a `finally` beside
+ * the write). Arming is therefore scoped to the operation: a write that produces
+ * no Y.Text delta at all (an empty append `composeAgentWrite` declines) leaves no
+ * armed observer behind to consume a LATER same-session write's delta under this
+ * call's stale key. Idempotent — the observer disarms itself on capture.
+ *
+ * @param ytext The Y.Text('source') instance to observe.
+ * @param sessionId The agent's writer ID (e.g. 'agent-<connectionId>').
+ * @param writeOrigin The transaction origin the agent's write will run under
+ * (`session.origin`); matched by object identity.
+ * @param colorSeed Color seed for UI rendering (defaults to sessionId).
+ * @param agentType Agent type string for UI aggregation (e.g. 'claude', 'cursor').
*/
export function captureEffect(
ytext: Y.Text,
sessionId: string,
+ writeOrigin: unknown,
colorSeed?: string,
agentType?: string,
-): void {
+): () => void {
const doc = ytext.doc;
- if (!doc) return;
+ if (!doc) return () => {};
const transactIdx = ++_effectCounter;
const effectsMap = doc.getMap<EffectValue>('agent-effects');
const observer = (event: Y.YTextEvent) => {
+ if (event.transaction.origin !== writeOrigin) return;
ytext.unobserve(observer);
doc.off('destroy', onDocDestroy);
const key = `${sessionId}:${transactIdx}`;
@@ -97,4 +117,9 @@ export function captureEffect(
ytext.observe(observer);
doc.once('destroy', onDocDestroy);
+
+ return () => {
+ ytext.unobserve(observer);
+ doc.off('destroy', onDocDestroy);
+ };
}
diff --git a/packages/server/src/agent-activity.ts b/packages/server/src/agent-activity.ts
index 8d336915d..17830b060 100644
--- a/packages/server/src/agent-activity.ts
+++ b/packages/server/src/agent-activity.ts
@@ -48,7 +48,7 @@ import type { AgentSessionManager } from './agent-sessions.ts';
interface YjsDeleteSetShape {
clients: Map<number, Array<{ clock: number; len: number }>>;
}
-interface YjsStackItemShape {
+export interface YjsStackItemShape {
insertions: YjsDeleteSetShape;
deletions: YjsDeleteSetShape;
meta: Map<unknown, unknown>;
@@ -81,7 +81,7 @@ function collectItemsInDeleteSet(
// sibling pointers. `AbstractType._start` is declared in
// `node_modules/yjs/dist/src/types/AbstractType.d.ts` — documented public
// surface despite the underscore prefix (convention-only; TypeScript-visible).
-function* walkYTextItems(ytext: Y.Text): IterableIterator<Item> {
+export function* walkYTextItems(ytext: Y.Text): IterableIterator<Item> {
let cursor = (ytext as unknown as { _start: Item | null })._start;
while (cursor !== null) {
yield cursor;
diff --git a/packages/server/src/agent-effect-capture.test.ts b/packages/server/src/agent-effect-capture.test.ts
new file mode 100644
index 000000000..b38d9e718
--- /dev/null
+++ b/packages/server/src/agent-effect-capture.test.ts
@@ -0,0 +1,151 @@
+/**
+ * Effect-capture attribution: the agent-effects row an agent write produces must
+ * carry THAT WRITE's delta, under THAT agent's identity.
+ *
+ * `captureEffect` is armed before the write transact, and the write spine
+ * legitimately makes a foreign-origin Y.Text write in between: the pre-drain
+ * flush (`agentWritePreDrain`) lands the user's un-propagated keystroke under
+ * `OBSERVER_SYNC_ORIGIN` so the compose rides it into the body. An origin-blind
+ * one-shot consumes that flush instead — filing the USER's bytes as an agent
+ * effect and leaving the agent's real write with no row at all. The observer is
+ * therefore keyed on the write's own origin (object identity), and the arming is
+ * disposed with the operation so a delta-free write cannot capture a later one.
+ */
+
+import { describe, expect, test, vi } from 'vitest';
+import * as Y from 'yjs';
+import { captureEffect, type EffectValue } from './activity-log.ts';
+import { applyAgentMarkdownWrite } from './agent-sessions.ts';
+import {
+ createWiredPreDrainRig,
+ WIRED_PENDING_LINE,
+ WIRED_STALE_LINE,
+} from './pre-drain-wired.test-helper.ts';
+
+const AGENT_ORIGIN = Object.freeze({ source: 'local', context: { origin: 'agent-write' } });
+const FOREIGN_ORIGIN = Object.freeze({ source: 'local', context: { origin: 'observer-sync' } });
+
+function effectRows(doc: Y.Doc): EffectValue[] {
+ return [...doc.getMap<EffectValue>('agent-effects').values()];
+}
+
+describe('captureEffect origin keying', () => {
+ test('a foreign-origin write landing between arming and the agent transact is not captured', () => {
+ const doc = new Y.Doc();
+ const ytext = doc.getText('source');
+ doc.transact(() => ytext.insert(0, 'seed body\n'), 'setup');
+
+ captureEffect(ytext, 'agent-1', AGENT_ORIGIN, 'seed', 'claude');
+
+ // The pre-drain flush shape: a real Y.Text delete+insert of the USER's
+ // un-propagated bytes, under the observer self-origin.
+ doc.transact(() => ytext.insert(ytext.length, 'user keystroke\n'), FOREIGN_ORIGIN);
+ // The agent's own write.
+ doc.transact(() => ytext.insert(ytext.length, 'agent bytes\n'), AGENT_ORIGIN);
+
+ const rows = effectRows(doc);
+ expect(rows.length).toBe(1);
+ const delta = JSON.stringify(rows[0]?.delta);
+ expect(delta).toContain('agent bytes');
+ expect(delta).not.toContain('user keystroke');
+ });
+
+ test('the disposer disarms a write that produced no delta, so it cannot capture a later one', () => {
+ const doc = new Y.Doc();
+ const ytext = doc.getText('source');
+
+ // Operation 1: armed, but `composeAgentWrite` declined — no Y.Text delta.
+ const dispose = captureEffect(ytext, 'agent-1', AGENT_ORIGIN, 'seed', 'claude');
+ dispose();
+
+ // Operation 2 must produce exactly one row, keyed to its OWN arming.
+ const dispose2 = captureEffect(ytext, 'agent-1', AGENT_ORIGIN, 'seed', 'claude');
+ doc.transact(() => ytext.insert(0, 'second write\n'), AGENT_ORIGIN);
+ dispose2();
+
+ const rows = effectRows(doc);
+ expect(rows.length).toBe(1);
+ expect(JSON.stringify(rows[0]?.delta)).toContain('second write');
+ });
+});
+
+describe('effect capture across a real pre-drain flush', () => {
+ test('the agent-effects row carries the AGENT delta, not the pre-drained user keystroke', async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ const rig = await createWiredPreDrainRig({ docName: 'effect-attribution.md' });
+ try {
+ // A pending WYSIWYG keystroke sitting only in the fragment, cross-block
+ // from the append seam — the case the pre-drain exists to flush.
+ rig.stageUnpropagatedKeystroke();
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(rig.ytextString()).toContain(WIRED_STALE_LINE);
+ expect(rig.ytextString()).not.toContain(WIRED_PENDING_LINE);
+
+ // The handler ordering: arm, pre-drain, write, dispose.
+ const document = rig.session.dc.document;
+ const dispose = captureEffect(
+ document.getText('source'),
+ rig.session.agentId,
+ rig.session.origin,
+ 'seed',
+ 'claude',
+ );
+ try {
+ rig.agentWriteWithPreDrain('A fresh agent paragraph.', 'append');
+ } finally {
+ dispose();
+ }
+
+ // The flush happened (the keystroke reached Y.Text) — so the one-shot had a
+ // foreign-origin event available to consume.
+ expect(rig.ytextString()).toContain(WIRED_PENDING_LINE);
+
+ const rows = effectRows(rig.doc);
+ expect(rows.length).toBe(1);
+ const row = rows[0];
+ expect(row?.sessionId).toBe(rig.session.agentId);
+ const delta = JSON.stringify(row?.delta);
+ // The agent's own bytes are the effect; the user's flushed keystroke is not.
+ expect(delta).toContain('A fresh agent paragraph.');
+ expect(delta).not.toContain(WIRED_PENDING_LINE);
+ } finally {
+ await rig.cleanup();
+ vi.useRealTimers();
+ }
+ });
+
+ test('a declined write leaves no armed observer for the next write on the same session', async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ const rig = await createWiredPreDrainRig({ docName: 'effect-noop.md' });
+ try {
+ const document = rig.session.dc.document;
+ // An empty append: `composeAgentWrite` declines, so no Y.Text delta lands.
+ const disposeNoop = captureEffect(
+ document.getText('source'),
+ rig.session.agentId,
+ rig.session.origin,
+ );
+ document.transact(() => {
+ applyAgentMarkdownWrite(document, '', 'append');
+ }, rig.session.origin);
+ disposeNoop();
+ expect(effectRows(rig.doc).length).toBe(0);
+
+ const dispose = captureEffect(
+ document.getText('source'),
+ rig.session.agentId,
+ rig.session.origin,
+ );
+ rig.agentWrite('Real content.', 'append');
+ dispose();
+
+ // Exactly one row — the stale arming did not double-file the real write.
+ expect(effectRows(rig.doc).length).toBe(1);
+ } finally {
+ await rig.cleanup();
+ vi.useRealTimers();
+ }
+ });
+});
diff --git a/packages/server/src/agent-presence.test.ts b/packages/server/src/agent-presence.test.ts
index 66e2724c3..47db948e0 100644
--- a/packages/server/src/agent-presence.test.ts
+++ b/packages/server/src/agent-presence.test.ts
@@ -458,11 +458,17 @@ describe('AgentPresenceBroadcaster', () => {
const tryMatches = src.match(tryShapePattern) ?? [];
expect(tryMatches.length).toBe(expectedCount);
- // Every handler's finally block must call touchMode('idle'). Drop
- // this pairing and the entry stays in 'writing' until the next
- // successful write or WS close.
+ // Every handler's finally block must CLOSE with touchMode('idle'). Drop
+ // this pairing and the entry stays in 'writing' until the next successful
+ // write or WS close.
+ //
+ // Other cleanup may precede it in the same finally (the effect-capture
+ // disposer does), but the `\}` anchor keeps touchMode the LAST statement:
+ // anything after it could throw and skip the idle flip, which is the
+ // stuck-writing race this guards. `[^{}]*` also refuses a nested block, so a
+ // touchMode buried inside a conditional still fails.
const finallyPattern =
- /finally\s*\{\s*agentPresenceBroadcaster\?\.touchMode\(agentId,\s*'idle'\);\s*\}/g;
+ /finally\s*\{[^{}]*agentPresenceBroadcaster\?\.touchMode\(agentId,\s*'idle'\);\s*\}/g;
const finallyMatches = src.match(finallyPattern) ?? [];
expect(finallyMatches.length).toBe(expectedCount);
});
diff --git a/packages/server/src/agent-sessions.ts b/packages/server/src/agent-sessions.ts
index 3cbbbd021..54c45b5c1 100644
--- a/packages/server/src/agent-sessions.ts
+++ b/packages/server/src/agent-sessions.ts
@@ -30,12 +30,19 @@ import {
export { colorFromSeed } from '@inkeep/open-knowledge-core';
import * as Y from 'yjs';
+import type { YjsStackItemShape } from './agent-activity.ts';
import {
composeAndWriteRawBody,
deriveFragmentFromYtext,
type PrecomputedParse,
replaceRawBody,
} from './bridge-intake.ts';
+import {
+ type BridgeDeriveLossReporter,
+ DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE,
+ type DeriveLossDetectOptions,
+} from './bridge-loss-detector.ts';
+import { shouldRunPairedIntakeDetection } from './bridge-loss-suppression.ts';
import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';
import { DocInConflictError, isDocInConflict } from './conflict-errors.ts';
import {
@@ -48,7 +55,7 @@ import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
import { getLogger } from './logger.ts';
import { incrementAgentSessionEvictions } from './metrics.ts';
import { precomputeParse } from './parse-pool.ts';
-import type { PairedWriteOrigin } from './server-observers.ts';
+import { getPreDrainController, type PairedWriteOrigin } from './server-observers.ts';
import { getMeter, setActiveSpanAttributes, withSpanSync } from './telemetry.ts';
/**
@@ -200,6 +207,59 @@ export async function prepareFrontmatterPatchParse(
return precomputeParse(result.nextFenced + (needsFenceSeparator ? '\n' : '') + body);
}
+/**
+ * Wires the paired-intake derive-loss detector for an agent write. When present
+ * (and the `agent-write` origin is classified `detect`), an agent write that
+ * rebuilds the fragment over un-propagated WYSIWYG content checkpoints +
+ * observes it. The reporter comes from the session; `writerId` is the agent id
+ * for the ring event's correlation slot.
+ */
+export interface AgentWriteLossDetect {
+ reporter: BridgeDeriveLossReporter;
+ writerId: string | null;
+}
+
+/**
+ * Build the paired-intake loss-detect for an agent write from its session.
+ * Returns undefined when loss detection is disabled (no reporter attached), so
+ * the write stays serialize-free. Accepts a structural subset of the session so
+ * callers pass the session record directly.
+ */
+export function agentWriteLossDetect(session: {
+ bridgeLossReporter?: BridgeDeriveLossReporter;
+ agentId: string;
+}): AgentWriteLossDetect | undefined {
+ return session.bridgeLossReporter
+ ? { reporter: session.bridgeLossReporter, writerId: session.agentId }
+ : undefined;
+}
+
+/**
+ * Pre-drain in front of an agent write. Called by a write handler BEFORE
+ * its `doc.transact(..., session.origin)` block — the flush must land in its own
+ * observer-origin transact (not captured into the agent's undo frame), and the
+ * compose inside the transact then reads the flushed Y.Text so the keystroke
+ * rides into the composed body. Recomposes the write's projected body (the same
+ * `composeAgentWrite` the apply path runs) so the discriminator can locate the
+ * op's target; a no-op compose (empty append/prepend) skips. Inert when no
+ * controller is registered (system/config doc, observers not attached) — the
+ * write's checkpoint floor then captures any un-propagated content instead.
+ */
+export function agentWritePreDrain(
+ document: Document,
+ markdown: string,
+ position: 'append' | 'prepend' | 'replace' | 'patch',
+): void {
+ const controller = getPreDrainController(document as unknown as Y.Doc);
+ if (!controller) return;
+ // A no-op compose (empty append/prepend) writes nothing, so there is nothing
+ // to pre-drain in front of.
+ if (composeAgentWrite(document.getText('source').toString(), markdown, position) === undefined) {
+ return;
+ }
+ controller.preDrain({ kind: 'agent-write', writeKind: position });
+}
+
export function applyAgentMarkdownWrite(
document: Document,
markdown: string,
@@ -221,6 +281,7 @@ export function applyAgentMarkdownWrite(
* doc that moved during the caller's await falls back to inline parse.
*/
precomputed?: PrecomputedParse,
+ lossDetect?: AgentWriteLossDetect,
): AgentWriteContentDivergence | undefined {
// Conflict-aware write gate (precedent #38 + this batch's structural
// refusal contract). Lives OUTSIDE the transact — the check is static on
@@ -248,6 +309,7 @@ export function applyAgentMarkdownWrite(
position,
embedResolver,
precomputed,
+ lossDetect,
);
if (divergence !== undefined) {
setActiveSpanAttributes({
@@ -378,6 +440,7 @@ function applyAgentMarkdownWriteInner(
sourcePath: string;
},
precomputed?: PrecomputedParse,
+ lossDetect?: AgentWriteLossDetect,
): AgentWriteContentDivergence | undefined {
try {
const ytext = document.getText('source');
@@ -388,6 +451,26 @@ function applyAgentMarkdownWriteInner(
}
const { existingFm, finalFm, newContent } = composed;
+ // A `replace`/`patch` that rebuilds the fragment over un-propagated WYSIWYG
+ // content silently discards it — wire the paired-intake derive-loss detector
+ // when a reporter is present and the `agent-write` origin is classified
+ // `detect`. The pre-write Y.Text is the baseline so the agent's own write is
+ // excluded; only never-propagated fragment content trips. Off leaves the
+ // write serialize-free.
+ const detect: DeriveLossDetectOptions | undefined =
+ lossDetect && shouldRunPairedIntakeDetection(AGENT_WRITE_ORIGIN.context.origin)
+ ? {
+ report: (obs) =>
+ lossDetect.reporter(
+ document.name,
+ obs,
+ lossDetect.writerId,
+ DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE,
+ ),
+ baselineFullMd: currentYText,
+ }
+ : undefined;
+
if (finalFm !== existingFm) {
// Refuse the write when the agent's payload introduces unparseable
// YAML into the FM region. Y.Text-is-truth means the bytes
@@ -448,9 +531,9 @@ function applyAgentMarkdownWriteInner(
// incremental primitive. Two primitives, two intents — see
// `bridge-intake.ts` file header for the full contrast.
if (position === 'replace') {
- replaceRawBody(document, newContent, embedResolver, precomputed);
+ replaceRawBody(document, newContent, embedResolver, precomputed, detect);
} else {
- composeAndWriteRawBody(document, newContent, 'agent', embedResolver, precomputed);
+ composeAndWriteRawBody(document, newContent, 'agent', embedResolver, precomputed, detect);
}
// Site A content-divergence gate (shared predicate). Read Y.Text
@@ -612,7 +695,42 @@ function applyAgentUndoInner(
? Math.min(Math.max(0, count ?? 0), um.undoStack.length)
: um.undoStack.length;
+ // Pre-drain: before the derive rebuilds the fragment, flush an
+ // un-propagated keystroke that provably does not overlap the frame being
+ // undone into Y.Text, so the keystroke survives the undo instead of needing
+ // the checkpoint floor below. Only for a single-frame undo — the discriminator
+ // models the top StackItem's target, so a multi-frame drain (which reverts
+ // frames the discriminator did not inspect) fails closed to the floor. Runs
+ // before the baseline capture so a successful flush makes the derive's own
+ // loss verdict see the now-in-Y.Text keystroke and never checkpoints it.
+ if (framesToPop === 1 && um.undoStack.length > 0) {
+ getPreDrainController(document as unknown as Y.Doc)?.preDrain({
+ kind: 'agent-undo',
+ stackItem: um.undoStack[um.undoStack.length - 1] as unknown as YjsStackItemShape,
+ });
+ }
+
let undone = false;
+ // The Observer-B derive post-condition: when a reporter is wired, the derive
+ // observes whether the pre-derive fragment held content that was NEVER in
+ // Y.Text (an un-propagated WYSIWYG keystroke the rebuild is about to discard)
+ // and checkpoints + emits it. The pre-undo Y.Text is the baseline so the
+ // undo's own (intended) content removal is excluded from the verdict — only a
+ // never-propagated keystroke can trip. Bound to this session's doc/writer
+ // here so the primitive stays identity-free.
+ //
+ // Gated on the per-origin registry, like the agent-write and file-watcher
+ // intakes: `PAIRED_INTAKE_DETECTION` is the load-bearing classification, so
+ // reclassifying `agent-undo` must actually change what runs here rather than
+ // leaving a site that detects on reporter presence alone.
+ const reporter = session.bridgeLossReporter;
+ const detect: DeriveLossDetectOptions | undefined =
+ reporter && shouldRunPairedIntakeDetection(undoOrigin.context.origin)
+ ? {
+ report: (obs) => reporter(session.docName, obs, session.agentId),
+ baselineFullMd: document.getText('source').toString(),
+ }
+ : undefined;
// Wrap undo + composition in one outer transact under undoOrigin.
// Y.js merges um.undo()'s nested transact into this outer → fires under undoOrigin.
// isPairedWriteOrigin(undoOrigin) === true → Observer A/B short-circuit on settle.
@@ -621,7 +739,7 @@ function applyAgentUndoInner(
um.undo();
undone = true;
}
- if (undone) deriveFragmentFromYtext(document, embedResolver);
+ if (undone) deriveFragmentFromYtext(document, embedResolver, detect);
}, undoOrigin);
log.debug(
@@ -658,6 +776,12 @@ interface SessionRecord {
um: Y.UndoManager;
agentId: string;
docName: string;
+ /**
+ * Observer-B derive-loss observer, copied from the manager at session
+ * birth. Undefined when loss detection is disabled — then the undo derive
+ * pays no serialize cost.
+ */
+ bridgeLossReporter?: BridgeDeriveLossReporter;
/**
* Recency stamp (epoch ms), maintained exclusively by AgentSessionManager:
* refreshed on every `getSession` / `getLiveSession` hit. The manager's
@@ -815,15 +939,37 @@ export class AgentSessionManager {
private readonly maxSessions: number;
/** Idle floor for eviction eligibility. Override is for tests only. */
private readonly minEvictableIdleMs: number;
+ /**
+ * Observer-B derive-loss observer, wired at boot when loss detection is
+ * enabled. Copied into every session created by this manager. Undefined =
+ * detection off, and the undo derive stays serialize-free. Settable via the
+ * constructor (tests) or {@link attachBridgeLossReporter} at boot (the server
+ * builds the reporter after the loss ring, later in init than the manager).
+ */
+ private bridgeLossReporter?: BridgeDeriveLossReporter;
private evictions = 0;
constructor(
hocuspocus: Hocuspocus,
- options: { maxSessions?: number; minEvictableIdleMs?: number } = {},
+ options: {
+ maxSessions?: number;
+ minEvictableIdleMs?: number;
+ bridgeLossReporter?: BridgeDeriveLossReporter;
+ } = {},
) {
this.hocuspocus = hocuspocus;
this.maxSessions = options.maxSessions ?? MAX_AGENT_SESSIONS;
this.minEvictableIdleMs = options.minEvictableIdleMs ?? MIN_EVICTABLE_IDLE_MS;
+ this.bridgeLossReporter = options.bridgeLossReporter;
+ }
+
+ /**
+ * Attach the derive-loss observer after construction. Called once at boot,
+ * before any session exists (sessions are created only at request time), so
+ * every real session picks it up at creation.
+ */
+ public attachBridgeLossReporter(reporter: BridgeDeriveLossReporter): void {
+ this.bridgeLossReporter = reporter;
}
/** Number of live sessions currently retained. Read-only occupancy probe. */
@@ -1056,7 +1202,16 @@ export class AgentSessionManager {
`[agent-session] Created session for: ${docName} / ${agentId}`,
);
- return { dc, origin, undoOrigin, um, agentId, docName, lastUsedAt: Date.now() };
+ return {
+ dc,
+ origin,
+ undoOrigin,
+ um,
+ agentId,
+ docName,
+ lastUsedAt: Date.now(),
+ bridgeLossReporter: this.bridgeLossReporter,
+ };
}
/**
diff --git a/packages/server/src/agent-write-loss-detect-coverage.test.ts b/packages/server/src/agent-write-loss-detect-coverage.test.ts
new file mode 100644
index 000000000..b391685f0
--- /dev/null
+++ b/packages/server/src/agent-write-loss-detect-coverage.test.ts
@@ -0,0 +1,108 @@
+/**
+ * Fail-closed coverage: every agent-write spine handler threads the paired-intake
+ * loss detector.
+ *
+ * `applyAgentMarkdownWrite` is the shared spine for the agent content-write HTTP
+ * handlers (write / write-md / write-batch / patch / lint-fix). Each call must
+ * pass `agentWriteLossDetect(session)` so a `replace`/`patch` that rebuilds the
+ * fragment over un-propagated WYSIWYG content is checkpointed + observed rather
+ * than silently discarded. A new spine handler that forgets the detector is a
+ * silent loss surface — this gate fails the build so it can't ship.
+ */
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Node, Project, SyntaxKind } from 'ts-morph';
+import { describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// Every source file that hosts an `applyAgentMarkdownWrite` spine call: the HTTP
+// handlers live in `api-extension.ts`, the ACP fs-write handler in
+// `acp/thread-manager.ts`. Both must be scanned — a spine site in an unscanned
+// file is a silent loss surface the gate can't see.
+const SPINE_FILES = [join(here, 'api-extension.ts'), join(here, 'acp', 'thread-manager.ts')];
+
+function newProject(): Project {
+ return new Project({
+ skipFileDependencyResolution: true,
+ skipLoadingLibFiles: true,
+ skipAddingFilesFromTsConfig: true,
+ compilerOptions: { noLib: true, allowJs: false },
+ });
+}
+
+/** Callee's trailing name: `x.foo` → `foo`, `foo` → `foo`, else null. */
+function calleeName(call: Node): string | null {
+ if (!Node.isCallExpression(call)) return null;
+ const expr = call.getExpression();
+ if (Node.isIdentifier(expr)) return expr.getText();
+ if (Node.isPropertyAccessExpression(expr)) return expr.getName();
+ return null;
+}
+
+/** Whether any positional argument of the call is `agentWriteLossDetect(...)`. */
+function threadsLossDetect(call: Node): boolean {
+ if (!Node.isCallExpression(call)) return false;
+ return call
+ .getArguments()
+ .some((arg) => Node.isCallExpression(arg) && calleeName(arg) === 'agentWriteLossDetect');
+}
+
+describe('agent-write loss-detect coverage', () => {
+ it('every applyAgentMarkdownWrite spine call threads agentWriteLossDetect', () => {
+ const project = newProject();
+ const spineCalls = SPINE_FILES.flatMap((path) =>
+ project
+ .addSourceFileAtPath(path)
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .filter((c) => calleeName(c) === 'applyAgentMarkdownWrite'),
+ );
+ // Guard-the-guard: five HTTP spine sites (write / write-md / write-batch /
+ // patch / lint-fix) plus the ACP fs-write site. A refactor that drops below
+ // this is suspect.
+ expect(spineCalls.length).toBeGreaterThanOrEqual(6);
+ const missing = spineCalls
+ .filter((c) => !threadsLossDetect(c))
+ .map((c) => `${basename(c.getSourceFile().getFilePath())}:${c.getStartLineNumber()}`);
+ expect(missing).toEqual([]);
+ });
+
+ it('flags a spine call that omits the loss detector (planted positive)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-missing-loss-detect.ts',
+ `declare function applyAgentMarkdownWrite(...a: unknown[]): void;
+ function h(session: { dc: { document: unknown } }) {
+ applyAgentMarkdownWrite(session.dc.document, 'x', 'append');
+ }`,
+ );
+ const call = sf
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .find((c) => calleeName(c) === 'applyAgentMarkdownWrite');
+ expect(call).toBeDefined();
+ expect(call && threadsLossDetect(call)).toBe(false);
+ });
+
+ it('recognizes a spine call that threads the loss detector (positive control)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-with-loss-detect.ts',
+ `declare function applyAgentMarkdownWrite(...a: unknown[]): void;
+ declare function agentWriteLossDetect(s: unknown): unknown;
+ function h(session: { dc: { document: unknown } }) {
+ applyAgentMarkdownWrite(
+ session.dc.document,
+ 'x',
+ 'append',
+ undefined,
+ undefined,
+ agentWriteLossDetect(session),
+ );
+ }`,
+ );
+ const call = sf
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .find((c) => calleeName(c) === 'applyAgentMarkdownWrite');
+ expect(call).toBeDefined();
+ expect(call && threadsLossDetect(call)).toBe(true);
+ });
+});
diff --git a/packages/server/src/agent-write-pre-drain-coverage.test.ts b/packages/server/src/agent-write-pre-drain-coverage.test.ts
new file mode 100644
index 000000000..e1cad3a7c
--- /dev/null
+++ b/packages/server/src/agent-write-pre-drain-coverage.test.ts
@@ -0,0 +1,190 @@
+/**
+ * Fail-closed coverage: every agent-write spine handler whose position can be
+ * pre-drained actually calls the pre-drain.
+ *
+ * `applyAgentMarkdownWrite` is the shared spine for the agent content-write HTTP
+ * handlers (write / write-md / write-batch / patch / lint-fix). A pending WYSIWYG
+ * keystroke in front of one of those writes either gets flushed to safety by
+ * `agentWritePreDrain` or has to be rescued from the checkpoint floor after the
+ * fact — so a handler that forgets the pre-drain is a silent downgrade, not a
+ * visible failure. The sibling `agent-write-loss-detect-coverage` gate enforces
+ * the detector at exactly these sites; this one enforces the flush.
+ *
+ * The exemption is STRUCTURAL, not discretionary. `composeAgentWrite` sets
+ * `newBody = payloadBody` for both `replace` and `patch`, so those writes
+ * overwrite the whole body and a flushed keystroke cannot survive them —
+ * `planPreDrain` declines them outright (`checkpoint-full-overwrite`). A site
+ * that only ever writes at those positions therefore has nothing to call. This
+ * gate pins that reasoning: it exempts a call site ONLY when every position it
+ * passes is a full-body overwrite, so re-pointing such a handler at `append`
+ * without wiring the pre-drain fails the build.
+ */
+
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Node, Project, SyntaxKind } from 'ts-morph';
+import { describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// Every source file that hosts an `applyAgentMarkdownWrite` spine call: the HTTP
+// handlers in `api-extension.ts`, the ACP fs-write handler in
+// `acp/thread-manager.ts`. Both must be scanned — a pre-drainable spine site in
+// an unscanned file is a silent downgrade the gate can't see. The ACP site only
+// ever writes `replace` (a full-body overwrite), so it is exempt today; scanning
+// it makes a future re-point at `append` without a pre-drain fail the build.
+const SPINE_FILES = [join(here, 'api-extension.ts'), join(here, 'acp', 'thread-manager.ts')];
+
+/** Positions whose compose is a full-body overwrite (pre-drain is inert). */
+const FULL_BODY_OVERWRITE = new Set(['replace', 'patch']);
+
+function newProject(): Project {
+ return new Project({
+ skipFileDependencyResolution: true,
+ skipLoadingLibFiles: true,
+ skipAddingFilesFromTsConfig: true,
+ compilerOptions: { noLib: true, allowJs: false },
+ });
+}
+
+/** Callee's trailing name: `x.foo` → `foo`, `foo` → `foo`, else null. */
+function calleeName(call: Node): string | null {
+ if (!Node.isCallExpression(call)) return null;
+ const expr = call.getExpression();
+ if (Node.isIdentifier(expr)) return expr.getText();
+ if (Node.isPropertyAccessExpression(expr)) return expr.getName();
+ return null;
+}
+
+/**
+ * Every string literal the call's `position` argument (3rd positional) can
+ * evaluate to. Handles the literal (`'append'`) and the defaulted-expression
+ * (`entry.position ?? 'append'`) forms; anything else yields an empty set, which
+ * is NOT exempt — an unanalysable position must not buy an exemption.
+ */
+function positionLiterals(call: Node): Set<string> {
+ const out = new Set<string>();
+ if (!Node.isCallExpression(call)) return out;
+ const arg = call.getArguments()[2];
+ if (!arg) return out;
+ for (const lit of [
+ ...(Node.isStringLiteral(arg) ? [arg] : []),
+ ...arg.getDescendantsOfKind(SyntaxKind.StringLiteral),
+ ]) {
+ out.add(lit.getLiteralText());
+ }
+ return out;
+}
+
+function isFunctionLike(n: Node): boolean {
+ return (
+ Node.isFunctionDeclaration(n) ||
+ Node.isFunctionExpression(n) ||
+ Node.isArrowFunction(n) ||
+ Node.isMethodDeclaration(n)
+ );
+}
+
+/**
+ * The HANDLER scope for a spine call: the nearest enclosing function that is not
+ * itself a `transact(...)` callback. Climbing past transact callbacks is the
+ * point — the pre-drain must run in the handler, in its OWN observer-origin
+ * transact, never nested inside the agent's (which would capture the flush into
+ * the undo frame).
+ */
+function handlerScope(call: Node): Node | undefined {
+ for (const anc of call.getAncestors()) {
+ if (!isFunctionLike(anc)) continue;
+ const parent = anc.getParent();
+ if (parent && Node.isCallExpression(parent) && calleeName(parent) === 'transact') continue;
+ return anc;
+ }
+ return undefined;
+}
+
+describe('agent-write pre-drain coverage', () => {
+ it('every pre-drainable applyAgentMarkdownWrite spine call is preceded by agentWritePreDrain', () => {
+ const project = newProject();
+ const spineCalls = SPINE_FILES.flatMap((path) =>
+ project
+ .addSourceFileAtPath(path)
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .filter((c) => calleeName(c) === 'applyAgentMarkdownWrite'),
+ );
+ // Guard-the-guard: five HTTP spine sites (write / write-md / write-batch /
+ // patch / lint-fix) plus the ACP fs-write site. A refactor that drops below
+ // this is suspect.
+ expect(spineCalls.length).toBeGreaterThanOrEqual(6);
+
+ // A site is exempt only when every position it can pass is a full-body
+ // overwrite, and it passes at least one analysable position.
+ const preDrainable = spineCalls.filter((call) => {
+ const positions = positionLiterals(call);
+ return positions.size === 0 || [...positions].some((p) => !FULL_BODY_OVERWRITE.has(p));
+ });
+ // At least the three localized-write handlers must be in scope.
+ expect(preDrainable.length).toBeGreaterThanOrEqual(3);
+
+ const missing = preDrainable
+ .filter((call) => {
+ const scope = handlerScope(call);
+ if (!scope) return true;
+ return !scope
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .some((c) => calleeName(c) === 'agentWritePreDrain' && c.getStart() < call.getStart());
+ })
+ .map((c) => `${basename(c.getSourceFile().getFilePath())}:${c.getStartLineNumber()}`);
+ expect(missing).toEqual([]);
+ });
+
+ it('does not exempt a site that writes at a pre-drainable position (planted positive)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-append-without-pre-drain.ts',
+ `declare function applyAgentMarkdownWrite(...a: unknown[]): void;
+ function h(doc: unknown) {
+ applyAgentMarkdownWrite(doc, 'x', 'append');
+ }`,
+ );
+ const call = sf
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .find((c) => calleeName(c) === 'applyAgentMarkdownWrite');
+ expect(call).toBeDefined();
+ const positions = call ? positionLiterals(call) : new Set<string>();
+ expect([...positions]).toEqual(['append']);
+ expect([...positions].some((p) => !FULL_BODY_OVERWRITE.has(p))).toBe(true);
+ });
+
+ it('exempts a site that only ever writes a full-body overwrite (negative control)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-patch-only.ts',
+ `declare function applyAgentMarkdownWrite(...a: unknown[]): void;
+ function h(doc: unknown) {
+ applyAgentMarkdownWrite(doc, 'x', 'patch');
+ }`,
+ );
+ const call = sf
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .find((c) => calleeName(c) === 'applyAgentMarkdownWrite');
+ expect(call).toBeDefined();
+ const positions = call ? positionLiterals(call) : new Set<string>();
+ expect([...positions].some((p) => !FULL_BODY_OVERWRITE.has(p))).toBe(false);
+ });
+
+ it('refuses to exempt an unanalysable position (fail-closed)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-dynamic-position.ts',
+ `declare function applyAgentMarkdownWrite(...a: unknown[]): void;
+ function h(doc: unknown, pos: string) {
+ applyAgentMarkdownWrite(doc, 'x', pos);
+ }`,
+ );
+ const call = sf
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .find((c) => calleeName(c) === 'applyAgentMarkdownWrite');
+ expect(call).toBeDefined();
+ // No literal to reason about → in scope for the gate, not exempt.
+ expect(call ? positionLiterals(call).size : -1).toBe(0);
+ });
+});
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index b8bdf4d12..458262f76 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -296,6 +296,8 @@ import {
AgentSessionCapacityError,
type AgentSessionManager,
type AgentWriteContentDivergence,
+ agentWriteLossDetect,
+ agentWritePreDrain,
applyAgentMarkdownWrite,
applyAgentUndo,
iconFromClientName,
@@ -503,6 +505,7 @@ import {
} from './backlink-index.ts';
import { getBootTimings } from './boot-timings.ts';
import { composeAndWriteRawBody, type PrecomputedParse, replaceRawBody } from './bridge-intake.ts';
+import type { BridgeDeriveLossReporter } from './bridge-loss-detector.ts';
import { isConfigDoc, isLinkIndexExcludedDoc, isSystemDoc } from './cc1-broadcast.ts';
import { withHiddenWindowsConsole } from './child-process-windows-hide.ts';
import type { ResolveStrategy } from './conflict-storage.ts';
@@ -510,6 +513,7 @@ import type { ContentFilter } from './content-filter.ts';
import { isWithinContentDir, safeContentPath } from './content-path.ts';
import {
docNameToRelativePath,
+ extensionlessDocTreePath,
forgetDocExtension,
getDocExtension,
isSupportedAssetFile,
@@ -947,6 +951,22 @@ function safeDocPath(docName: string, contentRoot: string): { path: string } | {
return { path };
}
+/**
+ * Ordered tree-path candidates for resolving a doc's blob inside a commit at
+ * restore time. Full-tree checkpoints (Save Version, auto-consolidation,
+ * pre-rollback) hold the blob at the extension-full disk path; the silent
+ * single-blob checkpoint trees `saveInMemoryCheckpoint` writes hold it at the
+ * extension-less docName path. Probe extension-full first so a full-tree
+ * checkpoint always matches its real path before the extension-less twin is
+ * considered.
+ */
+function docTreePathCandidates(docName: string, contentRoot: string): readonly string[] {
+ const p = safeDocPath(docName, contentRoot);
+ if ('error' in p) return [`${docName}.md`];
+ const extless = extensionlessDocTreePath(p.path, docName);
+ return extless ? [p.path, extless] : [p.path];
+}
+
const GENERIC_PASTE_NAMES = /^(image\.(png|jpe?g|gif|webp)|Clipboard.*|Untitled.*)$/i;
// unicode-preserving. Permits any Unicode letter, number, or combining
@@ -2821,6 +2841,15 @@ export interface ApiExtensionOptions {
* carries the resolved src/href.
*/
resolveEmbed?: (basename: string, sourcePath: string) => string | null;
+ /**
+ * Paired-intake derive-loss reporter, threaded into every
+ * `reconcileDiskBeforeAgentWrite` call so the L1 reconcile's
+ * FILE_WATCHER_ORIGIN ingest carries the same `detect` wiring the file
+ * watcher's own path does. A GETTER, not a value: the reporter is built later
+ * in server init (after the loss ring) than this extension is constructed, and
+ * is absent entirely when the `bridge.lossDetector` kill-switch is off.
+ */
+ getBridgeLossReporter?: () => BridgeDeriveLossReporter | undefined;
/**
* Getter for the server's principal record. Called at request time so
* deferred async init propagates. Returns null if principal has not
@@ -3054,6 +3083,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
localOpCliArgs = ['open-knowledge'],
authStreamHeartbeatMs,
projectDir,
+ getBridgeLossReporter,
getPrincipal,
homeDirOverride,
acpRegistry,
@@ -4271,7 +4301,14 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
span.setAttribute('rename.rewrite_candidates', pendingRewrites.length);
assertRewriteTargetsNotConflicted(pendingRewrites.map((entry) => entry.docName));
- reconcileDiskBeforeAgentWrite(durabilityState, hocuspocus, sourceDocName, contentDir);
+ reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hocuspocus,
+ sourceDocName,
+ contentDir,
+ undefined,
+ getBridgeLossReporter?.(),
+ );
if (recentlyRemovedDocs && !isSystemDoc(sourceDocName) && !isConfigDoc(sourceDocName)) {
recentlyRemovedDocs.setDeleted(sourceDocName);
}
@@ -4532,7 +4569,14 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
// losslessly through the rename re-serialize and re-resolves on the
// next normal load/reconcile. The extension-level resolveEmbed is
// also shadowed by this function's own options param.
- reconcileDiskBeforeAgentWrite(durabilityState, hocuspocus, docName, contentDir);
+ reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hocuspocus,
+ docName,
+ contentDir,
+ undefined,
+ getBridgeLossReporter?.(),
+ );
const content = readCurrentDocumentContent(docName);
if (typeof content === 'string') {
snapshotContents.set(docName, content);
@@ -5207,6 +5251,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
docName,
contentDir,
options.resolveEmbed,
+ getBridgeLossReporter?.(),
);
const timestamp = new Date().toISOString();
@@ -5215,6 +5260,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
const { response: summaryResponse, stored: storedSummary } =
summaryResponseFields(normalizedSummary);
+ // Disarmed in `finally` so a write that produces no Y.Text delta (or
+ // throws before its transact) never leaves an armed observer behind to
+ // capture a later same-session write under this call's stale key.
+ let disposeEffectCapture: (() => void) | undefined;
// setPresence lives INSIDE the try so the pairing with touchMode('idle')
// in `finally` is atomic — any throw between setPresence and transact
// (even future code added here) flips the badge back to idle rather
@@ -5230,8 +5279,21 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
mode: 'writing',
ts: Date.now(),
});
- // Register one-shot observer BEFORE write transact so YTextEvent.delta is captured
- captureEffect(session.dc.document.getText('source'), agentId, colorSeed, clientName);
+ // Arm the origin-keyed effect observer BEFORE the write transact so the
+ // agent's own YTextEvent.delta is captured. Keyed on `session.origin`,
+ // so the pre-drain flush below (OBSERVER_SYNC_ORIGIN) passes through
+ // uncaptured instead of filing the user's keystroke as an agent effect.
+ disposeEffectCapture = captureEffect(
+ session.dc.document.getText('source'),
+ agentId,
+ session.origin,
+ colorSeed,
+ clientName,
+ );
+ // Pre-drain a non-overlapping pending keystroke into Y.Text before the
+ // write's own transact (own observer-origin transact — not the agent's
+ // undo frame) so the compose below rides it into the body.
+ agentWritePreDrain(session.dc.document, `${content}\n`, 'append');
// Use per-session origin, not shared AGENT_WRITE_ORIGIN (STOP rule)
session.dc.document.transact(() => {
const beforeBlocks = snapshotBlocks(session.dc.document);
@@ -5242,6 +5304,8 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
options.resolveEmbed
? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
: undefined,
+ undefined,
+ agentWriteLossDetect(session),
);
const changedBlocks =
@@ -5267,6 +5331,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
incrementAgentWriteCalls();
countNormalizedSummary(normalizedSummary);
} finally {
+ disposeEffectCapture?.();
agentPresenceBroadcaster?.touchMode(agentId, 'idle');
}
@@ -5402,6 +5467,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
resolvedDocName,
contentDir,
options.resolveEmbed,
+ getBridgeLossReporter?.(),
);
// Off-thread parse precompute (parse-pool): parse the projected
@@ -5426,6 +5492,11 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
// for production observability.
let writeDivergence: AgentWriteContentDivergence | undefined;
+ // Disarmed in `finally` so a write that produces no Y.Text delta (or
+ // throws before its transact) never leaves an armed observer behind to
+ // capture a later same-session write under this call's stale key.
+ let disposeEffectCapture: (() => void) | undefined;
+
// setPresence lives INSIDE the try so the pairing with touchMode('idle')
// in `finally` is atomic — any throw between setPresence and transact
// (even future code added here) flips the badge back to idle rather
@@ -5441,8 +5512,20 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
mode: 'writing',
ts: Date.now(),
});
- // Register one-shot observer BEFORE write transact so YTextEvent.delta is captured
- captureEffect(session.dc.document.getText('source'), agentId, colorSeed, clientName);
+ // Arm the origin-keyed effect observer BEFORE the write transact so the
+ // agent's own YTextEvent.delta is captured. Keyed on `session.origin`,
+ // so the pre-drain flush below (OBSERVER_SYNC_ORIGIN) passes through
+ // uncaptured instead of filing the user's keystroke as an agent effect.
+ disposeEffectCapture = captureEffect(
+ session.dc.document.getText('source'),
+ agentId,
+ session.origin,
+ colorSeed,
+ clientName,
+ );
+ // Pre-drain a non-overlapping pending keystroke into Y.Text before the
+ // write's transact so the compose below rides it into the body.
+ agentWritePreDrain(session.dc.document, body.markdown, position);
// Use per-session origin, not shared AGENT_WRITE_ORIGIN (STOP rule)
session.dc.document.transact(() => {
const beforeBlocks = snapshotBlocks(session.dc.document);
@@ -5452,6 +5535,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
position,
writeMdEmbedResolver,
writeMdPrecomputed,
+ agentWriteLossDetect(session),
);
const changedBlocks =
@@ -5492,6 +5576,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
incrementAgentWriteCalls();
countNormalizedSummary(normalizedSummary);
} finally {
+ disposeEffectCapture?.();
agentPresenceBroadcaster?.touchMode(agentId, 'idle');
}
@@ -5850,6 +5935,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
resolvedDocName,
contentDir,
options.resolveEmbed,
+ getBridgeLossReporter?.(),
);
// Off-thread parse precompute — same advisory pattern as the
@@ -5865,30 +5951,50 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
);
let writeDivergence: AgentWriteContentDivergence | undefined;
- // Register one-shot observer BEFORE write transact so YTextEvent.delta is captured
- captureEffect(session.dc.document.getText('source'), agentId, colorSeed, clientName);
- // Use per-session origin, not shared AGENT_WRITE_ORIGIN (STOP rule)
- session.dc.document.transact(() => {
- const beforeBlocks = snapshotBlocks(session.dc.document);
- writeDivergence = applyAgentMarkdownWrite(
- session.dc.document,
- entry.markdown,
- entry.position ?? 'append',
- entryEmbedResolver,
- entryPrecomputed,
- );
+ // Arm the origin-keyed effect observer BEFORE the write transact so
+ // the agent's own YTextEvent.delta is captured. Per-entry scope: the
+ // disposer runs right after this entry's transact so an entry whose
+ // compose is a no-op cannot capture the NEXT entry's delta.
+ const disposeEntryEffectCapture = captureEffect(
+ session.dc.document.getText('source'),
+ agentId,
+ session.origin,
+ colorSeed,
+ clientName,
+ );
+ // Pre-drain a non-overlapping pending keystroke into Y.Text before
+ // this entry's transact so the compose below rides it into the
+ // body. Its own observer-origin transact — never nested inside the
+ // agent's, which would capture the flush into the undo frame.
+ agentWritePreDrain(session.dc.document, entry.markdown, entry.position ?? 'append');
+ try {
+ // Use per-session origin, not shared AGENT_WRITE_ORIGIN (STOP rule)
+ session.dc.document.transact(() => {
+ const beforeBlocks = snapshotBlocks(session.dc.document);
+ writeDivergence = applyAgentMarkdownWrite(
+ session.dc.document,
+ entry.markdown,
+ entry.position ?? 'append',
+ entryEmbedResolver,
+ entryPrecomputed,
+ agentWriteLossDetect(session),
+ );
- const changedBlocks =
- changedBlockRange(beforeBlocks, snapshotBlocks(session.dc.document)) ?? undefined;
- const activityMap = session.dc.document.getMap('agent-flash');
- activityMap.set(agentId, {
- agentId,
- timestamp: Date.now(),
- type: 'insert',
- description: `Added (${agentName}): ${entry.markdown.trim().slice(0, 50)}`,
- ...(changedBlocks !== undefined ? { changedBlocks } : {}),
- });
- }, session.origin);
+ const changedBlocks =
+ changedBlockRange(beforeBlocks, snapshotBlocks(session.dc.document)) ??
+ undefined;
+ const activityMap = session.dc.document.getMap('agent-flash');
+ activityMap.set(agentId, {
+ agentId,
+ timestamp: Date.now(),
+ type: 'insert',
+ description: `Added (${agentName}): ${entry.markdown.trim().slice(0, 50)}`,
+ ...(changedBlocks !== undefined ? { changedBlocks } : {}),
+ });
+ }, session.origin);
+ } finally {
+ disposeEntryEffectCapture();
+ }
recordContentDivergenceGate('agent-write-batch', writeDivergence);
recordContributor(
@@ -6093,6 +6199,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
resolvedDocName,
contentDir,
options.resolveEmbed,
+ getBridgeLossReporter?.(),
);
// Optimistic off-thread parse precompute (parse-pool): apply the FM
@@ -7532,6 +7639,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
docName,
contentDir,
options.resolveEmbed,
+ getBridgeLossReporter?.(),
);
// Optimistic off-thread parse precompute (parse-pool): splice the
@@ -7574,6 +7682,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
// Site A content-divergence captured from the in-transact gate.
// Surfaced as the response's `warning` field on successful patches.
let patchDivergence: AgentWriteContentDivergence | undefined;
+ // Disarmed in `finally` so a patch that finds no match (and therefore
+ // produces no Y.Text delta) never leaves an armed observer behind to
+ // capture a later same-session write under this call's stale key.
+ let disposeEffectCapture: (() => void) | undefined;
// setPresence lives INSIDE the try so the pairing with touchMode('idle')
// in `finally` is atomic — any throw between setPresence and transact
// (even future code added here) flips the badge back to idle rather
@@ -7589,8 +7701,16 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
mode: 'writing',
ts: Date.now(),
});
- // Register one-shot observer BEFORE write transact so YTextEvent.delta is captured
- captureEffect(session.dc.document.getText('source'), agentId, colorSeed, clientName);
+ // Arm the origin-keyed effect observer BEFORE the write transact so the
+ // agent's own YTextEvent.delta is captured, never a foreign-origin write
+ // that lands between arming and the transact.
+ disposeEffectCapture = captureEffect(
+ session.dc.document.getText('source'),
+ agentId,
+ session.origin,
+ colorSeed,
+ clientName,
+ );
// Use per-session origin, not shared AGENT_WRITE_ORIGIN (STOP rule)
session.dc.document.transact(() => {
// Read current authoritative state from Y.Text — the user's
@@ -7667,6 +7787,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
'patch',
patchEmbedResolver,
patchPrecomputed,
+ agentWriteLossDetect(session),
);
const changedBlocks =
@@ -7713,6 +7834,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
recordContentDivergenceGate('agent-patch', patchDivergence);
}
} finally {
+ disposeEffectCapture?.();
agentPresenceBroadcaster?.touchMode(agentId, 'idle');
}
@@ -8825,10 +8947,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
sha,
branch,
renameLogIndex,
- (name) => {
- const p = safeDocPath(name, resolvedContentRoot);
- return 'error' in p ? `${name}.md` : p.path;
- },
+ (name) => docTreePathCandidates(name, resolvedContentRoot),
ancestorCache,
);
if (historicalPath === null) {
@@ -8935,10 +9054,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
commitSha,
branch,
renameLogIndex,
- (name) => {
- const p = safeDocPath(name, resolvedContentRoot);
- return 'error' in p ? `${name}.md` : p.path;
- },
+ (name) => docTreePathCandidates(name, resolvedContentRoot),
ancestorCache,
);
if (historicalPath === null) {
@@ -19977,6 +20093,8 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
options.resolveEmbed
? { resolveEmbed: options.resolveEmbed, sourcePath: resolvedDocName }
: undefined,
+ undefined,
+ agentWriteLossDetect(session),
);
}, session.origin);
diff --git a/packages/server/src/bridge-intake.ts b/packages/server/src/bridge-intake.ts
index 406c2fb4f..bd2b0fffd 100644
--- a/packages/server/src/bridge-intake.ts
+++ b/packages/server/src/bridge-intake.ts
@@ -44,10 +44,11 @@
* next non-paired ytext mutation would re-derive fragment from the STALE
* ytext bytes, silently reverting the write.
*/
-import { applyFastDiff, stripFrontmatter } from '@inkeep/open-knowledge-core';
+import { applyFastDiff, prependFrontmatter, stripFrontmatter } from '@inkeep/open-knowledge-core';
import type { JSONContent } from '@tiptap/core';
-import { updateYFragment } from '@tiptap/y-tiptap';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import type * as Y from 'yjs';
+import type { DeriveLossDetectOptions } from './bridge-loss-detector.ts';
import { mdManager, schema } from './md-manager.ts';
import { withSpanSync } from './telemetry.ts';
@@ -131,6 +132,52 @@ function buildParseOpts(embedResolver: EmbedResolverArg):
: undefined;
}
+/**
+ * Serialize a fragment's current markdown body — the at-risk pending content a
+ * paired derive is about to rebuild over. Captured BEFORE the rebuild so a loss
+ * detector can compare it against the post-rebuild forms. Called only when a
+ * detector is wired; the serialize cost is off otherwise.
+ */
+function serializeFragmentBody(xmlFragment: Y.XmlFragment): string {
+ return mdManager.serialize(yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON());
+}
+
+/**
+ * After a paired derive rebuilds the fragment, hand the wired detector the
+ * canonical before/after representations so it can checkpoint + observe content
+ * the rebuild discarded. All bodies are canonical markdown (frontmatter-
+ * stripped, one serializer) so the comparison is normalization-sound.
+ *
+ * `restoreFrontmatter` is the FM the recovery payload prepends to `pendingBody`
+ * — the pre-derive FM, so a restore reconstructs the document that held the
+ * pending content.
+ */
+function reportPairedDeriveLoss(
+ detect: DeriveLossDetectOptions,
+ pendingBody: string,
+ parsedJson: JSONContent,
+ xmlFragment: Y.XmlFragment,
+ restoreFrontmatter: string,
+ parseOpts: ReturnType<typeof buildParseOpts>,
+): void {
+ const rebuiltBody = serializeFragmentBody(xmlFragment);
+ // The parse result re-serialized directly — a canonical post-op derivation
+ // independent of the live fragment updateYFragment just mutated.
+ const ytextDerivedBody = mdManager.serialize(parsedJson);
+ // The pre-operation body canonicalized to the same space, so content the
+ // operation legitimately removed (which this baseline held) is excluded from
+ // the loss verdict — only never-propagated fragment content can trip.
+ const { body: baselineRawBody } = stripFrontmatter(detect.baselineFullMd);
+ const baselineBody = mdManager.serialize(mdManager.parseWithFallback(baselineRawBody, parseOpts));
+ detect.report({
+ pendingBody,
+ baselineBody,
+ ytextDerivedBody,
+ rebuiltBody,
+ restorePayload: prependFrontmatter(restoreFrontmatter, pendingBody),
+ });
+}
+
/**
* Apply raw composed bytes to Y.Text via an incremental line-aligned diff and derive
* XmlFragment via parse.
@@ -187,6 +234,7 @@ export function composeAndWriteRawBody(
surface: ComposeWriteSurface,
embedResolver?: EmbedResolverArg,
precomputed?: PrecomputedParse,
+ detect?: DeriveLossDetectOptions,
): void {
withSpanSync(
'bridge.composeAndWriteRawBody',
@@ -208,6 +256,11 @@ export function composeAndWriteRawBody(
const parsedJson = parseBodyWithPrecompute(document, rawContent, embedResolver, precomputed);
const pmNode = schema.nodeFromJSON(parsedJson);
+ // Capture the at-risk fragment content BEFORE the rebuild overwrites it —
+ // only when a detector is wired (the paired origin classified `detect`),
+ // so an ordinary write pays no serialize cost.
+ const pendingBody = detect ? serializeFragmentBody(xmlFragment) : undefined;
+
// Y.Text gets the raw bytes FIRST, then fragment derives. The order matters:
// Yjs transactions don't roll back on throw, so a partial failure mid-call
// leaves whichever side wrote last in the new state and the other side stale.
@@ -229,6 +282,18 @@ export function composeAndWriteRawBody(
const meta = { mapping: new Map(), isOMark: new Map() };
updateYFragment(document, xmlFragment, pmNode, meta);
+
+ if (detect && pendingBody !== undefined) {
+ const { frontmatter: restoreFrontmatter } = stripFrontmatter(detect.baselineFullMd);
+ reportPairedDeriveLoss(
+ detect,
+ pendingBody,
+ parsedJson,
+ xmlFragment,
+ restoreFrontmatter,
+ buildParseOpts(embedResolver),
+ );
+ }
},
);
}
@@ -261,6 +326,7 @@ export function replaceRawBody(
rawContent: string,
embedResolver?: EmbedResolverArg,
precomputed?: PrecomputedParse,
+ detect?: DeriveLossDetectOptions,
): void {
withSpanSync(
'bridge.replaceRawBody',
@@ -277,6 +343,10 @@ export function replaceRawBody(
const parsedJson = parseBodyWithPrecompute(document, rawContent, embedResolver, precomputed);
const pmNode = schema.nodeFromJSON(parsedJson);
+ // Capture the at-risk fragment content BEFORE the rebuild — only when a
+ // detector is wired (the paired origin classified `detect`).
+ const pendingBody = detect ? serializeFragmentBody(xmlFragment) : undefined;
+
const currentText = ytext.toString();
if (currentText !== rawContent) {
ytext.delete(0, currentText.length);
@@ -285,6 +355,18 @@ export function replaceRawBody(
const meta = { mapping: new Map(), isOMark: new Map() };
updateYFragment(document, xmlFragment, pmNode, meta);
+
+ if (detect && pendingBody !== undefined) {
+ const { frontmatter: restoreFrontmatter } = stripFrontmatter(detect.baselineFullMd);
+ reportPairedDeriveLoss(
+ detect,
+ pendingBody,
+ parsedJson,
+ xmlFragment,
+ restoreFrontmatter,
+ buildParseOpts(embedResolver),
+ );
+ }
},
);
}
@@ -309,16 +391,55 @@ export function replaceRawBody(
*
* @param document Y.Doc holding the doc's `default` XmlFragment and `source` Y.Text.
* @param embedResolver Optional `![[file.ext]]` resolver context.
+ * @param detect Optional post-condition observer. When supplied, the pre-derive
+ * fragment is serialized (the at-risk content) and, after the rebuild,
+ * `detect.report` is invoked with the canonical before/after representations
+ * so a caller can checkpoint + observe content the rebuild discarded. The
+ * serialize cost is paid ONLY when a detector is wired.
*/
-export function deriveFragmentFromYtext(document: Y.Doc, embedResolver?: EmbedResolverArg): void {
+export function deriveFragmentFromYtext(
+ document: Y.Doc,
+ embedResolver?: EmbedResolverArg,
+ detect?: DeriveLossDetectOptions,
+): void {
const xmlFragment = document.getXmlFragment('default');
const ytext = document.getText('source');
const fullMd = ytext.toString();
- const { body } = stripFrontmatter(fullMd);
- const parsedJson = mdManager.parseWithFallback(body, buildParseOpts(embedResolver));
+ const { frontmatter, body } = stripFrontmatter(fullMd);
+ const parseOpts = buildParseOpts(embedResolver);
+ const parsedJson = mdManager.parseWithFallback(body, parseOpts);
const pmNode = schema.nodeFromJSON(parsedJson);
+ // Capture the pre-derive fragment serialization only when a detector is
+ // wired — the extra serializes are off unless loss capture is enabled.
+ const pendingBody = detect
+ ? mdManager.serialize(yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON())
+ : undefined;
+
const meta = { mapping: new Map(), isOMark: new Map() };
updateYFragment(document, xmlFragment, pmNode, meta);
+
+ if (detect && pendingBody !== undefined) {
+ const rebuiltBody = mdManager.serialize(
+ yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON(),
+ );
+ // The parse result re-serialized directly — a canonical post-op ytext
+ // derivation independent of the live fragment updateYFragment just mutated.
+ const ytextDerivedBody = mdManager.serialize(parsedJson as JSONContent);
+ // The pre-operation Y.Text body canonicalized to the same space, so content
+ // the operation legitimately removed (which this baseline held) is excluded
+ // from the loss verdict — only never-propagated fragment content can trip.
+ const { body: baselineRawBody } = stripFrontmatter(detect.baselineFullMd);
+ const baselineBody = mdManager.serialize(
+ mdManager.parseWithFallback(baselineRawBody, parseOpts),
+ );
+ detect.report({
+ pendingBody,
+ baselineBody,
+ ytextDerivedBody,
+ rebuiltBody,
+ restorePayload: prependFrontmatter(frontmatter, pendingBody),
+ });
+ }
}
diff --git a/packages/server/src/bridge-loss-detector.test.ts b/packages/server/src/bridge-loss-detector.test.ts
new file mode 100644
index 000000000..b4779dafc
--- /dev/null
+++ b/packages/server/src/bridge-loss-detector.test.ts
@@ -0,0 +1,889 @@
+/**
+ * Observer-B (Y.Text→XmlFragment) derive-loss detection.
+ *
+ * Covers the pure twin verdict, the observation a real `deriveFragmentFromYtext`
+ * produces when the fragment holds content Y.Text lacks, and the reporter that
+ * writes a `bridge-derive-loss` checkpoint + content-free `detector-trip` ring
+ * event through real shadow git.
+ */
+
+import { readFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import {
+ normalizeBridge,
+ pendingContentLines,
+ stripFrontmatter,
+} from '@inkeep/open-knowledge-core';
+import { updateYFragment } from '@tiptap/y-tiptap';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as Y from 'yjs';
+import {
+ composeAndWriteRawBody,
+ deriveFragmentFromYtext,
+ replaceRawBody,
+} from './bridge-intake.ts';
+import {
+ createBridgeDeriveLossReporter,
+ DERIVE_LOSS_SITE_AGENT_UNDO,
+ DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE,
+ DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE,
+ type DeriveLossObservation,
+ detectApplyArmDrop,
+ detectDeriveLoss,
+ detectPairedIntakeLoss,
+} from './bridge-loss-detector.ts';
+import { DocumentDurabilityState } from './document-durability-state.ts';
+import { applyExternalChange } from './external-change.ts';
+import { LossCaptureRing, lossCaptureCurrentPath, parseLossCaptureLines } from './loss-capture.ts';
+import { mdManager, schema } from './md-manager.ts';
+import { setupServerObservers } from './server-observers.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+type RingEvent = ReturnType<typeof parseLossCaptureLines>[number];
+
+/** Poll the loss ring until an event matching `predicate` appears (bounded). */
+async function pollForEvent(
+ projectDir: string,
+ ring: LossCaptureRing,
+ predicate: (e: RingEvent) => boolean,
+ timeoutMs = 5000,
+): Promise<RingEvent> {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ await ring.drain();
+ try {
+ const events = parseLossCaptureLines(
+ readFileSync(lossCaptureCurrentPath(projectDir), 'utf-8'),
+ );
+ const found = events.find(predicate);
+ if (found) return found;
+ } catch {
+ // Ring file not written yet.
+ }
+ await new Promise((r) => setTimeout(r, 20));
+ }
+ throw new Error('timed out waiting for loss-ring event');
+}
+
+function buildFragment(doc: Y.Doc, body: string): void {
+ const xf = doc.getXmlFragment('default');
+ const pm = schema.nodeFromJSON(mdManager.parseWithFallback(body, undefined));
+ doc.transact(() => updateYFragment(doc, xf, pm, { mapping: new Map(), isOMark: new Map() }));
+}
+
+/** A doc whose fragment holds `pendingBody` while Y.Text still holds `syncedMd`. */
+function seedDivergedDoc(syncedMd: string, pendingBody: string): Y.Doc {
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, syncedMd);
+ // Fragment first materialized in sync, then advanced with the pending edit —
+ // Y.Text is left untouched, so the fragment holds content Y.Text lacks.
+ buildFragment(doc, stripFrontmatter(syncedMd).body);
+ buildFragment(doc, pendingBody);
+ return doc;
+}
+
+describe('detectDeriveLoss (the twin verdict)', () => {
+ it('flags a never-propagated fragment line that both twins lack', () => {
+ const obs: DeriveLossObservation = {
+ pendingBody: 'Shared body\n\nPending keystroke',
+ // The keystroke was never in Y.Text before the op.
+ baselineBody: 'Shared body',
+ ytextDerivedBody: 'Shared body',
+ rebuiltBody: 'Shared body',
+ restorePayload: 'Shared body\n\nPending keystroke',
+ };
+ expect(detectDeriveLoss(obs)).toEqual(['Pending keystroke']);
+ });
+
+ it('does NOT flag content the operation legitimately removed (an intended undo)', () => {
+ // The undone line WAS in the pre-op Y.Text (propagated), so the undo
+ // removing it is intended — not a loss. This is the fuzz-caught regression.
+ const obs: DeriveLossObservation = {
+ pendingBody: 'Line A\n\nLine B',
+ baselineBody: 'Line A\n\nLine B',
+ ytextDerivedBody: 'Line A',
+ rebuiltBody: 'Line A',
+ restorePayload: 'Line A\n\nLine B',
+ };
+ expect(detectDeriveLoss(obs)).toEqual([]);
+ });
+
+ it('returns empty when the rebuild preserved the at-risk content', () => {
+ const obs: DeriveLossObservation = {
+ pendingBody: 'Shared body\n\nKept line',
+ baselineBody: 'Shared body',
+ ytextDerivedBody: 'Shared body\n\nKept line',
+ rebuiltBody: 'Shared body\n\nKept line',
+ restorePayload: 'Shared body\n\nKept line',
+ };
+ expect(detectDeriveLoss(obs)).toEqual([]);
+ });
+
+ it('catches a loss via the independent twin when one representation is blind', () => {
+ // Planted producer-side blindness: the rebuilt live fragment still shows the
+ // content (as if updateYFragment silently kept it), so the producer check
+ // reports nothing — but the ytext-derived twin catches the real drop.
+ const obs: DeriveLossObservation = {
+ pendingBody: 'Shared body\n\nPending keystroke',
+ baselineBody: 'Shared body',
+ ytextDerivedBody: 'Shared body',
+ rebuiltBody: 'Shared body\n\nPending keystroke',
+ restorePayload: 'Shared body\n\nPending keystroke',
+ };
+ expect(detectDeriveLoss(obs)).toEqual(['Pending keystroke']);
+ });
+});
+
+describe('deriveFragmentFromYtext observation', () => {
+ it('reports the un-propagated fragment content the derive discards', () => {
+ const doc = seedDivergedDoc(
+ '# Title\n\nOriginal line',
+ '# Title\n\nOriginal line\n\nPending keystroke',
+ );
+ let captured: DeriveLossObservation | undefined;
+ const baselineFullMd = doc.getText('source').toString();
+ doc.transact(() => {
+ deriveFragmentFromYtext(doc, undefined, {
+ report: (obs) => {
+ captured = obs;
+ },
+ baselineFullMd,
+ });
+ });
+ expect(captured).toBeDefined();
+ const dropped = detectDeriveLoss(captured as DeriveLossObservation);
+ expect(dropped).toContain('Pending keystroke');
+ // The restore payload carries the pending content so it stays recoverable.
+ expect((captured as DeriveLossObservation).restorePayload).toContain('Pending keystroke');
+ doc.destroy();
+ });
+
+ it('reports no loss for an ordinary in-sync derive', () => {
+ const md = '# Title\n\nOnly line';
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, md);
+ buildFragment(doc, stripFrontmatter(md).body);
+ let captured: DeriveLossObservation | undefined;
+ const baselineFullMd = doc.getText('source').toString();
+ doc.transact(() => {
+ deriveFragmentFromYtext(doc, undefined, {
+ report: (obs) => {
+ captured = obs;
+ },
+ baselineFullMd,
+ });
+ });
+ expect(captured).toBeDefined();
+ expect(detectDeriveLoss(captured as DeriveLossObservation)).toEqual([]);
+ doc.destroy();
+ });
+});
+
+describe('createBridgeDeriveLossReporter (real shadow + ring)', () => {
+ let tmpDir: string;
+
+ beforeEach(async () => {
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-derive-loss-test-'));
+ });
+
+ afterEach(async () => {
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ async function setupShadow(): Promise<{ projectRoot: string; shadow: ShadowHandle }> {
+ const projectRoot = resolve(tmpDir, 'project');
+ const shadow = await initShadowRepo(projectRoot);
+ return { projectRoot, shadow };
+ }
+
+ it('writes a bridge-derive-loss checkpoint + detector-trip event whose sha resolves', async () => {
+ const { projectRoot, shadow } = await setupShadow();
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+ const reporter = createBridgeDeriveLossReporter({
+ shadow: () => shadow,
+ ring,
+ getBranch: () => 'main',
+ contentRoot: '',
+ });
+
+ const doc = seedDivergedDoc('# Title\n\nOriginal', '# Title\n\nOriginal\n\nPending keystroke');
+ const baselineFullMd = doc.getText('source').toString();
+ doc.transact(() => {
+ deriveFragmentFromYtext(doc, undefined, {
+ report: (obs) => reporter('intro', obs, 'agent-1'),
+ baselineFullMd,
+ });
+ });
+ doc.destroy();
+
+ // The checkpoint write is a real git commit; the sha-bearing ring event is
+ // written from its `.then`. Poll until it lands.
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) => e.event === 'detector-trip' && Boolean(e.checkpointSha),
+ );
+ expect(trip).toBeDefined();
+ expect(trip?.direction).toBe('b');
+ expect(trip?.docName).toBe('intro');
+ // Content-free: a length + a digest, never the bytes.
+ expect(typeof trip?.lostLen).toBe('number');
+ expect(trip?.digest).toBeTruthy();
+
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ const row = hist.entries.find((e) => e.sha === trip?.checkpointSha);
+ expect(row?.checkpoint?.kind).toBe('bridge-derive-loss');
+ });
+
+ it('writes nothing when the derive preserved all content', async () => {
+ const { projectRoot, shadow } = await setupShadow();
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+ const reporter = createBridgeDeriveLossReporter({
+ shadow: () => shadow,
+ ring,
+ getBranch: () => 'main',
+ contentRoot: '',
+ });
+
+ const md = '# Title\n\nOnly line';
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, md);
+ buildFragment(doc, stripFrontmatter(md).body);
+ const baselineFullMd = doc.getText('source').toString();
+ doc.transact(() => {
+ deriveFragmentFromYtext(doc, undefined, {
+ report: (obs) => reporter('intro', obs),
+ baselineFullMd,
+ });
+ });
+ doc.destroy();
+
+ await new Promise((r) => setTimeout(r, 0));
+ await ring.drain();
+
+ let events: ReturnType<typeof parseLossCaptureLines> = [];
+ try {
+ events = parseLossCaptureLines(readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'));
+ } catch {
+ // No ring file written at all is also a pass.
+ }
+ expect(events.filter((e) => e.event === 'detector-trip')).toEqual([]);
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ expect(hist.entries.some((e) => e.checkpoint?.kind === 'bridge-derive-loss')).toBe(false);
+ });
+});
+
+describe('detectApplyArmDrop (Observer-A apply verdict)', () => {
+ it('flags a substantive line the applied Y.Text dropped', () => {
+ const md = '# Title\n\nLine one\n\nLine two\n\nLine three';
+ const applied = '# Title\n\nLine one\n\nLine three';
+ expect(detectApplyArmDrop(md, normalizeBridge(md), applied, normalizeBridge(applied))).toEqual([
+ 'Line two',
+ ]);
+ });
+
+ it('returns empty for a byte-identical apply', () => {
+ const md = '# Title\n\nBody line';
+ expect(detectApplyArmDrop(md, normalizeBridge(md), md, normalizeBridge(md))).toEqual([]);
+ });
+
+ it('does not flag a normalization-only difference (raw vs canonical form)', () => {
+ // The byte-preserving splice legitimately leaves the raw multi-blank form in
+ // Y.Text while the fragment serializes to the single-blank canonical form.
+ const canonical = 'A paragraph\n\nAnother paragraph';
+ const raw = 'A paragraph\n\n\n\nAnother paragraph';
+ // Precondition: normalize-equal — a tolerance difference, not a loss.
+ expect(normalizeBridge(raw)).toBe(normalizeBridge(canonical));
+ expect(
+ detectApplyArmDrop(canonical, normalizeBridge(canonical), raw, normalizeBridge(raw)),
+ ).toEqual([]);
+ });
+});
+
+describe('Observer-A apply post-condition (real drain)', () => {
+ let tmpDir: string;
+
+ beforeEach(async () => {
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-apply-loss-test-'));
+ });
+
+ afterEach(async () => {
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ /** Delete `target` from Y.Text once — models an apply arm dropping content. */
+ function makeInjector(target: string): (yt: Y.Text) => void {
+ let fired = false;
+ return (yt) => {
+ if (fired) return;
+ const idx = yt.toString().indexOf(target);
+ if (idx >= 0) {
+ yt.delete(idx, target.length);
+ fired = true;
+ }
+ };
+ }
+
+ it('checkpoints + emits a detector-trip when an apply arm drops content', async () => {
+ const projectRoot = resolve(tmpDir, 'project');
+ const shadow = await initShadowRepo(projectRoot);
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+
+ const doc = new Y.Doc();
+ const ytext = doc.getText('source');
+ const xf = doc.getXmlFragment('default');
+ ytext.insert(0, '# Title\n\nLine one\n\nLine two');
+ buildFragment(doc, '# Title\n\nLine one\n\nLine two');
+
+ const cleanup = setupServerObservers({
+ doc,
+ xmlFragment: xf,
+ ytext,
+ mdManager,
+ schema,
+ docName: 'intro',
+ shadow: () => shadow,
+ getBranch: () => 'main',
+ contentRoot: '',
+ lossDetectorEnabled: true,
+ lossRing: ring,
+ __testApplyLossInjector: makeInjector('Line two'),
+ });
+
+ // Edit the fragment (adds a line) to drive an Observer-A apply drain; the
+ // injector then drops "Line two" from the applied Y.Text.
+ buildFragment(doc, '# Title\n\nLine one\n\nLine two\n\nLine three');
+
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) => e.event === 'detector-trip' && e.direction === 'a' && Boolean(e.checkpointSha),
+ );
+ expect(trip.docName).toBe('intro');
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ expect(
+ hist.entries.some(
+ // Its OWN kind, not Path B's — the two detection sites stay
+ // distinguishable by kind, counter, and retention budget.
+ (e) => e.sha === trip.checkpointSha && e.checkpoint?.kind === 'observer-a-apply-loss',
+ ),
+ ).toBe(true);
+
+ cleanup();
+ doc.destroy();
+ });
+
+ it('does not trip when the loss-detector kill-switch is off', async () => {
+ const projectRoot = resolve(tmpDir, 'project');
+ const shadow = await initShadowRepo(projectRoot);
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+
+ const doc = new Y.Doc();
+ const ytext = doc.getText('source');
+ const xf = doc.getXmlFragment('default');
+ ytext.insert(0, '# Title\n\nLine one\n\nLine two');
+ buildFragment(doc, '# Title\n\nLine one\n\nLine two');
+
+ const cleanup = setupServerObservers({
+ doc,
+ xmlFragment: xf,
+ ytext,
+ mdManager,
+ schema,
+ docName: 'intro',
+ shadow: () => shadow,
+ getBranch: () => 'main',
+ contentRoot: '',
+ lossDetectorEnabled: false,
+ lossRing: ring,
+ __testApplyLossInjector: makeInjector('Line two'),
+ });
+
+ buildFragment(doc, '# Title\n\nLine one\n\nLine two\n\nLine three');
+
+ await new Promise((r) => setTimeout(r, 100));
+ await ring.drain();
+ let events: RingEvent[] = [];
+ try {
+ events = parseLossCaptureLines(readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'));
+ } catch {
+ // No ring file is also a pass.
+ }
+ expect(events.filter((e) => e.event === 'detector-trip')).toEqual([]);
+
+ cleanup();
+ doc.destroy();
+ });
+});
+
+describe('paired-intake derive-loss (composeAndWriteRawBody / replaceRawBody, real shadow + ring)', () => {
+ let tmpDir: string;
+
+ beforeEach(async () => {
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-paired-intake-loss-test-'));
+ });
+
+ afterEach(async () => {
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ async function setupReporter(): Promise<{
+ projectRoot: string;
+ shadow: ShadowHandle;
+ ring: LossCaptureRing;
+ reporter: ReturnType<typeof createBridgeDeriveLossReporter>;
+ }> {
+ const projectRoot = resolve(tmpDir, 'project');
+ const shadow = await initShadowRepo(projectRoot);
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+ const reporter = createBridgeDeriveLossReporter({
+ shadow: () => shadow,
+ ring,
+ getBranch: () => 'main',
+ contentRoot: '',
+ });
+ return { projectRoot, shadow, ring, reporter };
+ }
+
+ async function assertNoTrip(projectRoot: string, ring: LossCaptureRing): Promise<void> {
+ await new Promise((r) => setTimeout(r, 0));
+ await ring.drain();
+ let events: RingEvent[] = [];
+ try {
+ events = parseLossCaptureLines(readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'));
+ } catch {
+ // No ring file is also a pass.
+ }
+ expect(events.filter((e) => e.event === 'detector-trip')).toEqual([]);
+ }
+
+ it('file-watcher intake: a disk write that drops un-propagated fragment content trips + checkpoints', async () => {
+ const { projectRoot, shadow, ring, reporter } = await setupReporter();
+ // Dirty open doc: the fragment holds a keystroke Y.Text never absorbed.
+ const doc = seedDivergedDoc('# Title\n\nOriginal', '# Title\n\nOriginal\n\nPending keystroke');
+ const baselineFullMd = doc.getText('source').toString();
+ doc.transact(() => {
+ composeAndWriteRawBody(
+ doc,
+ '# Title\n\nOriginal edited on disk',
+ 'file-watcher',
+ undefined,
+ undefined,
+ {
+ report: (obs) =>
+ reporter('intro', obs, 'file-system', DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE),
+ baselineFullMd,
+ },
+ );
+ });
+ doc.destroy();
+
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) =>
+ e.event === 'detector-trip' &&
+ e.site === DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE &&
+ Boolean(e.checkpointSha),
+ );
+ expect(trip.direction).toBe('b');
+ expect(trip.docName).toBe('intro');
+ expect(trip.writerId).toBe('file-system');
+ // Content-free: a length + a digest, never the bytes.
+ expect(typeof trip.lostLen).toBe('number');
+ expect(trip.digest).toBeTruthy();
+ expect(JSON.stringify(trip)).not.toContain('Pending keystroke');
+
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ const row = hist.entries.find((e) => e.sha === trip.checkpointSha);
+ expect(row?.checkpoint?.kind).toBe('bridge-derive-loss');
+ });
+
+ it('file-watcher intake: a clean doc (fragment == Y.Text) does not trip', async () => {
+ const { projectRoot, ring, reporter } = await setupReporter();
+ const md = '# Title\n\nOnly line';
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, md);
+ buildFragment(doc, stripFrontmatter(md).body);
+ const baselineFullMd = doc.getText('source').toString();
+ doc.transact(() => {
+ composeAndWriteRawBody(
+ doc,
+ '# Title\n\nOnly line edited',
+ 'file-watcher',
+ undefined,
+ undefined,
+ {
+ report: (obs) =>
+ reporter('intro', obs, 'file-system', DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE),
+ baselineFullMd,
+ },
+ );
+ });
+ doc.destroy();
+ await assertNoTrip(projectRoot, ring);
+ });
+
+ it('agent-write intake (replaceRawBody): an overwrite that drops un-propagated content trips with the agent-write site', async () => {
+ const { projectRoot, shadow, ring, reporter } = await setupReporter();
+ const doc = seedDivergedDoc('# Title\n\nOriginal', '# Title\n\nOriginal\n\nPending keystroke');
+ const baselineFullMd = doc.getText('source').toString();
+ doc.transact(() => {
+ replaceRawBody(doc, '# Title\n\nAgent replacement', undefined, undefined, {
+ report: (obs) => reporter('intro', obs, 'agent-1', DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE),
+ baselineFullMd,
+ });
+ });
+ doc.destroy();
+
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) =>
+ e.event === 'detector-trip' &&
+ e.site === DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE &&
+ Boolean(e.checkpointSha),
+ );
+ expect(trip.direction).toBe('b');
+ expect(trip.writerId).toBe('agent-1');
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ expect(
+ hist.entries.some(
+ (e) => e.sha === trip.checkpointSha && e.checkpoint?.kind === 'bridge-derive-loss',
+ ),
+ ).toBe(true);
+ });
+
+ it('agent-write intake: an overwrite that keeps the pending content does not trip', async () => {
+ const { projectRoot, ring, reporter } = await setupReporter();
+ const doc = seedDivergedDoc('# Title\n\nOriginal', '# Title\n\nOriginal\n\nPending keystroke');
+ const baselineFullMd = doc.getText('source').toString();
+ doc.transact(() => {
+ replaceRawBody(
+ doc,
+ '# Title\n\nOriginal\n\nPending keystroke\n\nAgent added',
+ undefined,
+ undefined,
+ {
+ report: (obs) => reporter('intro', obs, 'agent-1', DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE),
+ baselineFullMd,
+ },
+ );
+ });
+ doc.destroy();
+ await assertNoTrip(projectRoot, ring);
+ });
+
+ it('applyExternalChange builds + forwards the reporter and the file-watcher detector fires', async () => {
+ const { projectRoot, shadow, ring, reporter } = await setupReporter();
+ const doc = seedDivergedDoc('# Title\n\nOriginal', '# Title\n\nOriginal\n\nPending keystroke');
+ // The file-watcher intake spine: applyExternalChange resolves the doc, builds
+ // the paired-intake detect from the reporter (file-watcher is classified
+ // `detect`), and threads it through applyDiskContentToDoc → the primitive.
+ const hocuspocus = {
+ documents: { get: (n: string) => (n === 'intro' ? doc : undefined) },
+ } as unknown as Parameters<typeof applyExternalChange>[1];
+ applyExternalChange(
+ new DocumentDurabilityState(),
+ hocuspocus,
+ 'intro',
+ '# Title\n\nOriginal edited on disk',
+ undefined,
+ undefined,
+ reporter,
+ );
+
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) =>
+ e.event === 'detector-trip' &&
+ e.site === DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE &&
+ Boolean(e.checkpointSha),
+ );
+ expect(trip.direction).toBe('b');
+ expect(trip.docName).toBe('intro');
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ expect(
+ hist.entries.some(
+ (e) => e.sha === trip.checkpointSha && e.checkpoint?.kind === 'bridge-derive-loss',
+ ),
+ ).toBe(true);
+ doc.destroy();
+ });
+
+ it('a suppress-classified paired write (no detect option) never trips, even on a dirty fragment', async () => {
+ // Rollback + managed-rename callers pass NO detect option — the structural
+ // suppression the registry classifies. Even with a live reporter available,
+ // a write that omits the detect option runs the detector for nobody.
+ const { projectRoot, ring } = await setupReporter();
+ const doc = seedDivergedDoc('# Title\n\nOriginal', '# Title\n\nOriginal\n\nPending keystroke');
+ doc.transact(() => {
+ // The rollback/rename shape: a full overwrite with no detect wired.
+ replaceRawBody(doc, '# Title\n\nRolled back to an older version');
+ });
+ doc.destroy();
+ await assertNoTrip(projectRoot, ring);
+ });
+});
+
+describe('detectPairedIntakeLoss (the line-predicate floor)', () => {
+ // The substring twin diffs inserted segments; a short intra-line delta that
+ // coincidentally reappears in the write's new bytes is filtered out and the
+ // twin reports nothing (the customer `bod`→`body.` shape). The line predicate
+ // keys on whole raw lines, so the changed line — absent from both the target
+ // derivation and the pre-operation baseline — is flagged.
+ const INTRA_LINE_STOMP: DeriveLossObservation = {
+ pendingBody: 'Deploy the staging server now.',
+ baselineBody: 'Deploy the server now.',
+ ytextDerivedBody: 'Restart the staging cluster later.',
+ rebuiltBody: 'Restart the staging cluster later.',
+ restorePayload: 'Deploy the staging server now.',
+ };
+
+ it('flags an intra-line stomp the substring twin filters away', () => {
+ // The inserted "staging" reappears in the applied bytes, so the substring
+ // twin's filter drops it — the twin alone is blind here.
+ expect(detectDeriveLoss(INTRA_LINE_STOMP)).toEqual([]);
+ // The floor catches it via the line predicate.
+ expect(detectPairedIntakeLoss(INTRA_LINE_STOMP)).toContain('Deploy the staging server now.');
+ });
+
+ it('is a superset of the substring twin when the twin already catches the loss', () => {
+ const obs: DeriveLossObservation = {
+ pendingBody: 'Shared body\n\nPending keystroke',
+ baselineBody: 'Shared body',
+ ytextDerivedBody: 'Shared body',
+ rebuiltBody: 'Shared body',
+ restorePayload: 'Shared body\n\nPending keystroke',
+ };
+ expect(detectDeriveLoss(obs)).toEqual(['Pending keystroke']);
+ expect(detectPairedIntakeLoss(obs)).toContain('Pending keystroke');
+ });
+
+ it('does not flag an intended removal (the witness leg excludes it)', () => {
+ // The line was in the pre-operation Y.Text, so removing it is intended — not
+ // a never-propagated keystroke.
+ const obs: DeriveLossObservation = {
+ pendingBody: 'Line A\n\nLine B',
+ baselineBody: 'Line A\n\nLine B',
+ ytextDerivedBody: 'Line A',
+ rebuiltBody: 'Line A',
+ restorePayload: 'Line A\n\nLine B',
+ };
+ expect(detectPairedIntakeLoss(obs)).toEqual([]);
+ });
+});
+
+describe('paired-intake floor through the real pipeline (real shadow + ring)', () => {
+ let tmpDir: string;
+
+ beforeEach(async () => {
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-paired-floor-test-'));
+ });
+
+ afterEach(async () => {
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ // An intra-line stomp: the fragment holds "Deploy the staging server now." while
+ // Y.Text holds "Deploy the server now."; the write replaces the line with content
+ // that reuses "staging", so only the line predicate catches the loss.
+ const PRE_OP_BODY = '## Guide\n\nDeploy the server now.';
+ const PENDING_BODY = '## Guide\n\nDeploy the staging server now.';
+ const PENDING_LINE = 'Deploy the staging server now.';
+ const REPLACEMENT = '## Guide\n\nRestart the staging cluster later.';
+
+ async function setup(): Promise<{
+ projectRoot: string;
+ shadow: ShadowHandle;
+ ring: LossCaptureRing;
+ reporter: ReturnType<typeof createBridgeDeriveLossReporter>;
+ }> {
+ const projectRoot = resolve(tmpDir, 'project');
+ const shadow = await initShadowRepo(projectRoot);
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+ const reporter = createBridgeDeriveLossReporter({
+ shadow: () => shadow,
+ ring,
+ getBranch: () => 'main',
+ contentRoot: '',
+ });
+ return { projectRoot, shadow, ring, reporter };
+ }
+
+ it('agent-write (replaceRawBody): the line predicate trips + checkpoints an intra-line stomp the twin misses', async () => {
+ const { projectRoot, shadow, ring, reporter } = await setup();
+ const doc = seedDivergedDoc(PRE_OP_BODY, PENDING_BODY);
+ const baselineFullMd = doc.getText('source').toString();
+ let captured: DeriveLossObservation | undefined;
+ doc.transact(() => {
+ replaceRawBody(doc, REPLACEMENT, undefined, undefined, {
+ report: (obs) => {
+ captured = obs;
+ reporter('intro', obs, 'agent-1', DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE);
+ },
+ baselineFullMd,
+ });
+ });
+ doc.destroy();
+
+ // The captured observation proves the line predicate — not the substring
+ // twin — is what enables the trip through the real serialize pipeline.
+ expect(captured).toBeDefined();
+ const obs = captured as DeriveLossObservation;
+ expect(detectDeriveLoss(obs)).toEqual([]);
+ expect(detectPairedIntakeLoss(obs)).toContain(PENDING_LINE);
+
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) =>
+ e.event === 'detector-trip' &&
+ e.site === DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE &&
+ Boolean(e.checkpointSha),
+ );
+ expect(trip.direction).toBe('b');
+ // Content-free ring: never the lost bytes.
+ expect(JSON.stringify(trip)).not.toContain(PENDING_LINE);
+
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ expect(
+ hist.entries.some(
+ (e) => e.sha === trip.checkpointSha && e.checkpoint?.kind === 'bridge-derive-loss',
+ ),
+ ).toBe(true);
+ });
+
+ it('the checkpoint payload is the pre-derive FRAGMENT serialization (byte-level), not Y.Text', async () => {
+ const { projectRoot, shadow, ring, reporter } = await setup();
+ const doc = seedDivergedDoc(PRE_OP_BODY, PENDING_BODY);
+ const baselineFullMd = doc.getText('source').toString();
+ let captured: DeriveLossObservation | undefined;
+ doc.transact(() => {
+ replaceRawBody(doc, REPLACEMENT, undefined, undefined, {
+ report: (obs) => {
+ captured = obs;
+ reporter('intro', obs, 'agent-1', DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE);
+ },
+ baselineFullMd,
+ });
+ });
+ doc.destroy();
+ const obs = captured as DeriveLossObservation;
+
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) => e.event === 'detector-trip' && Boolean(e.checkpointSha),
+ );
+ const blob = (await shadowGit(shadow).raw('show', `${trip.checkpointSha}:intro`)).toString();
+
+ // Byte-identical to the captured restore payload …
+ expect(blob).toBe(obs.restorePayload);
+ // … which carries the un-propagated fragment keystroke Y.Text never held …
+ expect(blob).toContain(PENDING_LINE);
+ // … and is NOT the Y.Text-derived content the write applied (a Y.Text payload
+ // would miss the keystroke entirely).
+ expect(blob).not.toContain('Restart the staging cluster');
+ });
+
+ it('file-watcher (composeAndWriteRawBody): the line predicate trips + checkpoints an intra-line stomp', async () => {
+ const { projectRoot, shadow, ring, reporter } = await setup();
+ const doc = seedDivergedDoc(PRE_OP_BODY, PENDING_BODY);
+ const baselineFullMd = doc.getText('source').toString();
+ let captured: DeriveLossObservation | undefined;
+ doc.transact(() => {
+ composeAndWriteRawBody(doc, REPLACEMENT, 'file-watcher', undefined, undefined, {
+ report: (obs) => {
+ captured = obs;
+ reporter('intro', obs, 'file-system', DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE);
+ },
+ baselineFullMd,
+ });
+ });
+ doc.destroy();
+ const obs = captured as DeriveLossObservation;
+ expect(detectDeriveLoss(obs)).toEqual([]);
+ expect(detectPairedIntakeLoss(obs)).toContain(PENDING_LINE);
+
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) =>
+ e.event === 'detector-trip' &&
+ e.site === DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE &&
+ Boolean(e.checkpointSha),
+ );
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ expect(
+ hist.entries.some(
+ (e) => e.sha === trip.checkpointSha && e.checkpoint?.kind === 'bridge-derive-loss',
+ ),
+ ).toBe(true);
+ });
+
+ it('agent-undo (deriveFragmentFromYtext): the line predicate participates in the floor for every derive caller', async () => {
+ const { projectRoot, shadow, ring, reporter } = await setup();
+ const doc = seedDivergedDoc(
+ '## Guide\n\nOriginal.',
+ '## Guide\n\nOriginal.\n\nPending line here.',
+ );
+ const baselineFullMd = doc.getText('source').toString();
+ let captured: DeriveLossObservation | undefined;
+ doc.transact(() => {
+ deriveFragmentFromYtext(doc, undefined, {
+ report: (obs) => {
+ captured = obs;
+ reporter('intro', obs, 'agent-1', DERIVE_LOSS_SITE_AGENT_UNDO);
+ },
+ baselineFullMd,
+ });
+ });
+ doc.destroy();
+ const obs = captured as DeriveLossObservation;
+ // The line predicate flags the un-propagated fragment line for the agent-undo
+ // vector too — the floor covers every deriveFragmentFromYtext caller.
+ expect(pendingContentLines(obs.pendingBody, obs.ytextDerivedBody, obs.baselineBody)).toContain(
+ 'Pending line here.',
+ );
+ expect(detectPairedIntakeLoss(obs)).toContain('Pending line here.');
+
+ const trip = await pollForEvent(
+ projectRoot,
+ ring,
+ (e) =>
+ e.event === 'detector-trip' &&
+ e.site === DERIVE_LOSS_SITE_AGENT_UNDO &&
+ Boolean(e.checkpointSha),
+ );
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, '');
+ expect(
+ hist.entries.some(
+ (e) => e.sha === trip.checkpointSha && e.checkpoint?.kind === 'bridge-derive-loss',
+ ),
+ ).toBe(true);
+ });
+
+ it('a suppress-classified paired write (no detect) never trips, even on an intra-line dirty fragment', async () => {
+ const { projectRoot, ring } = await setup();
+ const doc = seedDivergedDoc(PRE_OP_BODY, PENDING_BODY);
+ doc.transact(() => {
+ // The rollback/rename shape: a full overwrite with no detect wired.
+ replaceRawBody(doc, REPLACEMENT);
+ });
+ doc.destroy();
+ await new Promise((r) => setTimeout(r, 0));
+ await ring.drain();
+ let events: RingEvent[] = [];
+ try {
+ events = parseLossCaptureLines(readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'));
+ } catch {
+ // No ring file is also a pass.
+ }
+ expect(events.filter((e) => e.event === 'detector-trip')).toEqual([]);
+ });
+});
diff --git a/packages/server/src/bridge-loss-detector.ts b/packages/server/src/bridge-loss-detector.ts
new file mode 100644
index 000000000..80d10d341
--- /dev/null
+++ b/packages/server/src/bridge-loss-detector.ts
@@ -0,0 +1,275 @@
+/**
+ * Content-loss detection for the Y.Text→XmlFragment (Observer B) direction.
+ *
+ * The paired agent-undo derive rebuilds the fragment from the post-undo Y.Text
+ * (`deriveFragmentFromYtext`). When the pre-derive fragment held authored
+ * content the authoritative Y.Text lacked — an un-propagated WYSIWYG keystroke —
+ * the rebuild discards it. This module observes that class at the bridge
+ * boundary: it computes a content-loss verdict, writes a `bridge-derive-loss`
+ * checkpoint of the pre-derive fragment (the restore anchor), and emits a
+ * content-free `detector-trip` ring event.
+ *
+ * This is a DETECTION site, not a recovery: the derive still proceeds
+ * (Y.Text-is-truth). The checkpoint keeps the discarded content restorable
+ * through the timeline floor; the ring event makes the loss observable.
+ */
+
+import { findDroppedContent, fnv1aDigest, pendingContentLines } from '@inkeep/open-knowledge-core';
+import { getLogger } from './logger.ts';
+import { LOSS_EVENT_DETECTOR_TRIP, type LossCaptureRing } from './loss-capture.ts';
+import { type ShadowHandle, saveInMemoryCheckpoint } from './shadow-repo.ts';
+
+const log = getLogger('bridge-loss-detector');
+const checkpointLog = getLogger('checkpoint');
+
+/**
+ * The Observer-A (XmlFragment→Y.Text) apply post-condition verdict: substantive
+ * content the fragment's intended markdown (`intendedMd`) holds that the applied
+ * Y.Text (`appliedYText`) dropped. Returns the dropped substrings; empty means
+ * nothing was lost.
+ *
+ * The comparison runs in normalized space so a raw-vs-canonical form difference
+ * a byte-preserving splice legitimately leaves in Y.Text (`__foo__` vs
+ * `**foo**`, an un-padded GFM table) is never read as a loss. `normIntended` is
+ * the drain's already-computed `normalizeBridge(md)`, reused so the only extra
+ * cost is one normalize of the applied bytes — and both a byte-identical apply
+ * and a normalize-equal apply short-circuit before the segment diff.
+ */
+export function detectApplyArmDrop(
+ intendedMd: string,
+ normIntended: string,
+ appliedYText: string,
+ /**
+ * `normalizeBridge(appliedYText)`. Supplied by the caller because the drain
+ * already needs it for its settlement check — computing it here too would pay
+ * a second O(doc bytes) pass on the per-keystroke path.
+ */
+ normApplied: string,
+): string[] {
+ if (intendedMd === appliedYText) return [];
+ if (normApplied === normIntended) return [];
+ return findDroppedContent(normIntended, normApplied, normApplied);
+}
+
+/**
+ * The representations a derive post-condition compares. All are canonical
+ * markdown BODIES (frontmatter-stripped, run through the same serializer) so
+ * the comparison is normalization-sound: a user-form difference the serializer
+ * canonicalizes identically on both sides (`__foo__` → `**foo**`) never reads
+ * as a loss. Comparing the canonical fragment against RAW Y.Text bytes would
+ * false-positive on exactly that class, so both twins are canonical.
+ */
+export interface DeriveLossObservation {
+ /** Serialization of the fragment BEFORE the rebuild — the at-risk content. */
+ pendingBody: string;
+ /**
+ * Canonical serialization of the Y.Text BEFORE the operation that preceded
+ * this derive (for agent-undo, the pre-undo Y.Text). This is the shared
+ * ancestor: content the pre-derive fragment holds that this baseline ALSO
+ * held was propagated content the operation legitimately removed (the undo's
+ * own effect) — NOT a loss. Only fragment content ABSENT from this baseline
+ * (a keystroke that never reached Y.Text) can be a silent loss. Comparing
+ * against the post-op Y.Text instead would misread every intended undo as a
+ * loss.
+ */
+ baselineBody: string;
+ /**
+ * Canonical serialization of the post-op Y.Text, obtained by re-serializing
+ * the parse result directly (independent of the live fragment).
+ */
+ ytextDerivedBody: string;
+ /** Serialization of the live fragment AFTER the rebuild (the second twin). */
+ rebuiltBody: string;
+ /**
+ * The full pre-derive document (frontmatter + `pendingBody`) written as the
+ * checkpoint's restore payload — the state a user recovers to.
+ */
+ restorePayload: string;
+}
+
+/**
+ * Producer + consumer twin on independent representations. Returns the dropped
+ * content substrings; empty means nothing was lost.
+ *
+ * At-risk content = content the pre-derive fragment holds that the pre-op
+ * `baselineBody` did NOT (a never-propagated keystroke). A drop is that at-risk
+ * content also missing from the rebuilt fragment (producer twin) or the post-op
+ * ytext-derived form (consumer twin):
+ *
+ * - producer (live-fragment side): the live fragment after the rebuild.
+ * - consumer (ytext-derived side): the ytext parsed and re-serialized directly
+ * — a derivation independent of the live fragment.
+ *
+ * All three are canonical, so the comparison is normalization-sound. The union
+ * is taken so a defect in either derivation is caught by the independent twin.
+ */
+export function detectDeriveLoss(obs: DeriveLossObservation): string[] {
+ const producer = findDroppedContent(obs.pendingBody, obs.baselineBody, obs.rebuiltBody);
+ const consumer = findDroppedContent(obs.pendingBody, obs.baselineBody, obs.ytextDerivedBody);
+ if (consumer.length === 0) return producer;
+ const merged = [...producer];
+ const seen = new Set(producer);
+ for (const seg of consumer) {
+ if (!seen.has(seg)) {
+ seen.add(seg);
+ merged.push(seg);
+ }
+ }
+ return merged;
+}
+
+/**
+ * The paired-intake loss floor: the union of the substring-drop verdict and the
+ * witness-aware line predicate, evaluated on the same three canonical bodies.
+ *
+ * The two catch different shapes, so neither alone is the floor:
+ *
+ * - `detectDeriveLoss` diffs at the substring level. It sees a mid-paragraph
+ * deletion the "fragment holds more" line predicate cannot express, but its
+ * inserted-segment filter drops a short intra-line delta that coincidentally
+ * appears elsewhere in the applied bytes (the customer `bod`→`body.` shape).
+ * - `pendingContentLines` keys on whole raw lines. It flags exactly that
+ * intra-line stomp — the changed line is a distinct raw key present in
+ * neither the target derivation nor the pre-operation baseline — but keys on
+ * lines, so it cannot report a sub-line loss the substring diff catches.
+ *
+ * The line predicate's witness leg is `baselineBody` (the pre-operation Y.Text):
+ * a line the fragment shares with that ancestor was propagated content the
+ * operation legitimately removed, never a never-propagated keystroke, so it is
+ * excluded. The union is deduplicated but not deep-merged: the two produce
+ * different string forms (trimmed segments vs raw lines), which only affects the
+ * content-free digest's granularity, never the trip decision.
+ */
+export function detectPairedIntakeLoss(obs: DeriveLossObservation): string[] {
+ const dropped = detectDeriveLoss(obs);
+ const pending = pendingContentLines(obs.pendingBody, obs.ytextDerivedBody, obs.baselineBody);
+ if (pending.length === 0) return dropped;
+ const seen = new Set(dropped);
+ const merged = [...dropped];
+ for (const line of pending) {
+ if (!seen.has(line)) {
+ seen.add(line);
+ merged.push(line);
+ }
+ }
+ return merged;
+}
+
+/**
+ * What a paired-derive caller wires into `deriveFragmentFromYtext` to enable the
+ * post-condition. The caller supplies the PRE-operation Y.Text so intended
+ * removals are excluded from the loss verdict; the primitive canonicalizes it.
+ */
+export interface DeriveLossDetectOptions {
+ /** Invoked with the canonical before/after representations after the rebuild. */
+ report: (obs: DeriveLossObservation) => void;
+ /**
+ * Full Y.Text (frontmatter + body) BEFORE the operation that preceded this
+ * derive — for agent-undo, the pre-undo Y.Text captured before `um.undo()`.
+ */
+ baselineFullMd: string;
+}
+
+/**
+ * Ring `site` values for the derive-loss reporter — one per paired vector whose
+ * ytext→fragment rebuild can discard pending fragment content. Distinguishes
+ * the ring events so a bundle can tell an agent-undo loss from a file-watcher
+ * overwrite from an agent-write overwrite.
+ */
+export const DERIVE_LOSS_SITE_AGENT_UNDO = 'agent-undo-derive';
+export const DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE = 'file-watcher-intake';
+export const DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE = 'agent-write-intake';
+
+/** A pre-bound derive-loss observer the caller invokes after a paired derive. */
+export type BridgeDeriveLossReporter = (
+ docName: string,
+ obs: DeriveLossObservation,
+ writerId?: string | null,
+ /** Which paired vector's derive ran — see the `DERIVE_LOSS_SITE_*` constants. */
+ site?: string,
+) => void;
+
+export interface BridgeDeriveLossReporterDeps {
+ /** Live shadow handle, or undefined when no shadow is configured. */
+ shadow: () => ShadowHandle | undefined;
+ /** Content-free loss ring; omitted when loss capture is disabled. */
+ ring?: Pick<LossCaptureRing, 'record'>;
+ /** Current project branch for the `refs/checkpoints/<branch>/*` namespace. */
+ getBranch: () => string;
+ /** Content root prefix for the checkpoint tree path. */
+ contentRoot: string;
+}
+
+/**
+ * Build a reporter closed over the shadow + ring. The reporter runs the
+ * paired-intake loss floor (the substring twin unioned with the line predicate)
+ * and, on loss, writes a `bridge-derive-loss` checkpoint (fire-and-forget) plus
+ * a `detector-trip` ring event carrying the resolved checkpoint sha. Never
+ * throws — a diagnostic failure must never break the undo path.
+ */
+export function createBridgeDeriveLossReporter(
+ deps: BridgeDeriveLossReporterDeps,
+): BridgeDeriveLossReporter {
+ return (docName, obs, writerId = null, site = DERIVE_LOSS_SITE_AGENT_UNDO) => {
+ const dropped = detectPairedIntakeLoss(obs);
+ if (dropped.length === 0) return;
+ const lostLen = dropped.reduce((n, s) => n + s.length, 0);
+ const digest = fnv1aDigest(dropped.join('\n'));
+ const shadow = deps.shadow();
+ if (!shadow) {
+ void deps.ring?.record({
+ event: LOSS_EVENT_DETECTOR_TRIP,
+ docName,
+ writerId,
+ direction: 'b',
+ site,
+ lostLen,
+ digest,
+ });
+ return;
+ }
+ const branch = deps.getBranch();
+ const contentRoot = deps.contentRoot;
+ queueMicrotask(() => {
+ saveInMemoryCheckpoint(shadow, contentRoot, {
+ kind: 'bridge-derive-loss',
+ docName,
+ contents: obs.restorePayload,
+ label: `Before ${site} content-loss @ ${new Date().toISOString()}`,
+ branch,
+ metadata: { lostSubstrings: dropped },
+ })
+ .then((sha) => {
+ void deps.ring?.record({
+ event: LOSS_EVENT_DETECTOR_TRIP,
+ docName,
+ writerId,
+ direction: 'b',
+ site,
+ lostLen,
+ digest,
+ checkpointSha: sha,
+ });
+ console.warn(
+ JSON.stringify({
+ event: 'bridge-derive-loss-checkpoint-created',
+ docName,
+ sha,
+ kind: 'bridge-derive-loss',
+ site,
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ })
+ .catch((checkpointErr: unknown) => {
+ const e =
+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
+ log.warn({ docName, err: e }, '[bridge-derive-loss] checkpoint write failed');
+ checkpointLog.warn(
+ { err: e, 'doc.name': docName, branch, kind: 'bridge-derive-loss' },
+ 'checkpoint write failed',
+ );
+ });
+ });
+ };
+}
diff --git a/packages/server/src/bridge-loss-suppression.test.ts b/packages/server/src/bridge-loss-suppression.test.ts
new file mode 100644
index 000000000..7ffd8cfb6
--- /dev/null
+++ b/packages/server/src/bridge-loss-suppression.test.ts
@@ -0,0 +1,171 @@
+/**
+ * Fail-closed sweep for the paired-intake content-loss classification.
+ *
+ * Every paired-write origin declared in production source must carry a
+ * `detect`/`suppress` classification, and every live classification must
+ * correspond to a real origin. A new paired write surface therefore cannot ship
+ * without a deliberate loss-detection decision.
+ */
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+ PAIRED_INTAKE_DETECTION,
+ pairedIntakeDetectionMode,
+ RESERVED_PAIRED_INTAKE_DETECTION,
+ shouldRunPairedIntakeDetection,
+} from './bridge-loss-suppression.ts';
+
+const SRC_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** Files whose `paired: true` literals are fixtures, not production origins. */
+function isProductionSource(name: string): boolean {
+ return (
+ name.endsWith('.ts') &&
+ !name.endsWith('.test.ts') &&
+ !name.endsWith('.test-helper.ts') &&
+ !name.endsWith('.d.ts')
+ );
+}
+
+/** Drop comment lines so JSDoc prose like "No `paired: true` flag" never matches. */
+function stripCommentLines(text: string): string {
+ return text
+ .split('\n')
+ .filter((line) => {
+ const t = line.trimStart();
+ return !(t.startsWith('*') || t.startsWith('//') || t.startsWith('/*') || t.startsWith('*/'));
+ })
+ .join('\n');
+}
+
+/**
+ * RECURSIVE — `packages/server/src` has 14+ subdirectories (`acp/`, `http/`,
+ * `mcp/`, `config/`, `content/`, `fs/`, ...) and a paired origin declared in any
+ * of them must not escape the sweep. A top-level-only `readdirSync` was blind to
+ * exactly the surface this gate exists to close; the sibling gate
+ * `paired-write-enforcement.test.ts` walks the tree for the same reason.
+ */
+function declaredPairedOrigins(root: string = SRC_DIR): Set<string> {
+ const origins = new Set<string>();
+ // Brace-flat object literals only: the `PairedWriteOrigin` type declaration
+ // (`origin: string`, unquoted + `readonly paired: true`) and the non-paired
+ // `observer-sync` origin (no `paired: true` in its object) are excluded.
+ const objLiteral = /\{[^{}]*\}/g;
+ for (const rel of readdirSync(root, { recursive: true, encoding: 'utf-8' })) {
+ const base = rel.split(sep).pop() ?? rel;
+ if (!isProductionSource(base)) continue;
+ let text: string;
+ try {
+ text = stripCommentLines(readFileSync(join(root, rel), 'utf-8'));
+ } catch {
+ continue; // a directory whose name ends in `.ts`, or a dangling link
+ }
+ for (const m of text.matchAll(objLiteral)) {
+ const obj = m[0];
+ if (!obj.includes('paired: true')) continue;
+ const originMatch = obj.match(/origin:\s*'([^']+)'/);
+ if (originMatch?.[1]) origins.add(originMatch[1]);
+ }
+ }
+ return origins;
+}
+
+const scratchDirs: string[] = [];
+afterEach(() => {
+ while (scratchDirs.length > 0) {
+ const dir = scratchDirs.pop();
+ if (dir) rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+/** A synthetic `src`-shaped tree: one top-level and one nested paired origin. */
+function plantSyntheticTree(): string {
+ const root = mkdtempSync(join(tmpdir(), 'ok-paired-scan-'));
+ scratchDirs.push(root);
+ writeFileSync(
+ join(root, 'top-level-surface.ts'),
+ "export const TOP = Object.freeze({ source: 'local', context: { origin: 'planted-top-level', paired: true } });\n",
+ 'utf-8',
+ );
+ mkdirSync(join(root, 'http', 'deeper'), { recursive: true });
+ writeFileSync(
+ join(root, 'http', 'nested-surface.ts'),
+ "export const NESTED = Object.freeze({ source: 'local', context: { origin: 'planted-subdirectory', paired: true } });\n",
+ 'utf-8',
+ );
+ writeFileSync(
+ join(root, 'http', 'deeper', 'deepest-surface.ts'),
+ "export const DEEP = Object.freeze({ source: 'local', context: { origin: 'planted-two-deep', paired: true } });\n",
+ 'utf-8',
+ );
+ // Test code at both depths must stay excluded.
+ writeFileSync(
+ join(root, 'http', 'nested-surface.test.ts'),
+ "const FIXTURE = { origin: 'planted-fixture-not-production', paired: true };\n",
+ 'utf-8',
+ );
+ return root;
+}
+
+describe('paired-intake detection classification (fail-closed sweep)', () => {
+ /**
+ * Scanner-level planted positive. The other cases test the CLASSIFICATION MAP;
+ * this one tests the SCANNER that feeds it — a paired origin declared one and
+ * two directories deep must be found, or the fail-closed set equality above is
+ * computed over a partial view of the tree and cannot bite.
+ */
+ it('the scanner finds paired origins declared in subdirectories, not just top-level files', () => {
+ const root = plantSyntheticTree();
+ const found = declaredPairedOrigins(root);
+
+ expect(found.has('planted-top-level')).toBe(true);
+ expect(found.has('planted-subdirectory')).toBe(true);
+ expect(found.has('planted-two-deep')).toBe(true);
+ // Test-file literals are fixtures, never production origins.
+ expect(found.has('planted-fixture-not-production')).toBe(false);
+ expect([...found].sort()).toEqual([
+ 'planted-subdirectory',
+ 'planted-top-level',
+ 'planted-two-deep',
+ ]);
+ });
+
+ it('classifies every paired-write origin declared in production source', () => {
+ const declared = declaredPairedOrigins();
+ // Guard-the-guard: the scan must actually find the known origins.
+ expect(declared.size).toBeGreaterThanOrEqual(5);
+ const unclassified = [...declared].filter((o) => pairedIntakeDetectionMode(o) === undefined);
+ expect(unclassified).toEqual([]);
+ });
+
+ it('has no phantom classification without a source origin', () => {
+ const declared = declaredPairedOrigins();
+ const phantom = Object.keys(PAIRED_INTAKE_DETECTION).filter((o) => !declared.has(o));
+ expect(phantom).toEqual([]);
+ });
+
+ it('keeps reserved classifications out of the live map until their constant lands', () => {
+ const declared = declaredPairedOrigins();
+ for (const reserved of Object.keys(RESERVED_PAIRED_INTAKE_DETECTION)) {
+ expect(PAIRED_INTAKE_DETECTION[reserved]).toBeUndefined();
+ expect(declared.has(reserved)).toBe(false);
+ }
+ });
+
+ it('flags a synthetic unclassified origin', () => {
+ expect(pairedIntakeDetectionMode('brand-new-write-surface')).toBeUndefined();
+ expect(shouldRunPairedIntakeDetection('brand-new-write-surface')).toBe(false);
+ });
+
+ it('runs the detector for content-preserving origins and suppresses replacements', () => {
+ expect(shouldRunPairedIntakeDetection('agent-write')).toBe(true);
+ expect(shouldRunPairedIntakeDetection('agent-undo')).toBe(true);
+ expect(shouldRunPairedIntakeDetection('file-watcher')).toBe(true);
+ expect(shouldRunPairedIntakeDetection('rollback-apply')).toBe(false);
+ expect(shouldRunPairedIntakeDetection('managed-rename')).toBe(false);
+ expect(shouldRunPairedIntakeDetection('park-snapshot')).toBe(false);
+ });
+});
diff --git a/packages/server/src/bridge-loss-suppression.ts b/packages/server/src/bridge-loss-suppression.ts
new file mode 100644
index 000000000..2d979c9ec
--- /dev/null
+++ b/packages/server/src/bridge-loss-suppression.ts
@@ -0,0 +1,93 @@
+/**
+ * Origin-aware classification for the paired-intake content-loss detector.
+ *
+ * Every paired-write origin (the `context.origin` of a `PairedWriteOrigin`) is
+ * classified `detect` or `suppress`:
+ *
+ * - `detect` — the paired write can silently discard content the fragment held
+ * but Y.Text never did (a never-propagated keystroke), so its intake derive
+ * runs the content-loss post-condition. The pre-operation Y.Text baseline
+ * already excludes content the operation legitimately removed, so a `detect`
+ * origin only trips on a genuine loss.
+ * - `suppress` — a legitimate full replacement (the user's explicit intent to
+ * discard the current state), a content-preserving move, or a no-mutation
+ * op. Running the detector here would be a false positive.
+ *
+ * Fail-closed: a paired origin with no entry fails the sweep meta-test, so a new
+ * write surface cannot silently escape the loss-detection contract. Reserved
+ * entries (no source constant yet) are listed separately so the conflict spec's
+ * machine-merge origin has a declared classification before it lands.
+ */
+
+/** Whether a paired origin's intake derive runs the content-loss post-condition. */
+export type PairedIntakeDetectionMode = 'detect' | 'suppress';
+
+interface PairedIntakeDetectionEntry {
+ mode: PairedIntakeDetectionMode;
+ /** Why this classification holds — read by the sweep test's reporting. */
+ why: string;
+}
+
+/**
+ * The classification of every live paired-write `context.origin`. Keyed by the
+ * origin string so the runtime consumer (the paired-intake wiring) and the
+ * source sweep both look up the same value.
+ */
+export const PAIRED_INTAKE_DETECTION: Record<string, PairedIntakeDetectionEntry> = {
+ 'agent-write': {
+ mode: 'detect',
+ why: 'An agent write can race un-propagated WYSIWYG content; the pre-write baseline excludes the write itself, so only a never-propagated keystroke trips.',
+ },
+ 'agent-undo': {
+ mode: 'detect',
+ why: 'The Observer-B agent-undo derive; the pre-undo baseline excludes the undo’s own removal, so only a never-propagated keystroke trips.',
+ },
+ 'file-watcher': {
+ mode: 'detect',
+ why: 'An external disk write overwriting a dirty open doc drops un-propagated content; the pre-write baseline excludes the incoming change itself.',
+ },
+ 'rollback-apply': {
+ mode: 'suppress',
+ why: 'An explicit restore of a historical version; discarding the current state is the user intent, and that state stays a timeline version.',
+ },
+ 'managed-rename': {
+ mode: 'suppress',
+ why: 'A rename re-writes the same content at a new path; no content is dropped by construction.',
+ },
+ 'park-snapshot': {
+ mode: 'suppress',
+ why: 'A read-only snapshot capture that makes no Y.Doc mutation, so no content can be lost.',
+ },
+};
+
+/**
+ * Reserved classifications for paired origins that have no source constant yet.
+ * The conflict spec's machine-merge origin registers here so the sweep passes
+ * before it lands; when its constant appears the sweep moves it to the live map.
+ */
+export const RESERVED_PAIRED_INTAKE_DETECTION: Record<string, PairedIntakeDetectionEntry> = {
+ 'machine-merge': {
+ mode: 'detect',
+ why: 'Reserved for the conflict spec: a machine merge landing into a dirty doc can drop un-propagated content; classified detect ahead of the constant.',
+ },
+};
+
+/**
+ * The classification for a paired origin, or `undefined` when it is unclassified
+ * (which the sweep meta-test treats as a fail-closed violation).
+ */
+export function pairedIntakeDetectionMode(
+ originContextOrigin: string,
+): PairedIntakeDetectionMode | undefined {
+ return PAIRED_INTAKE_DETECTION[originContextOrigin]?.mode;
+}
+
+/**
+ * Whether the paired-intake content-loss detector should run for this origin.
+ * An unclassified origin returns `false` (suppress) so an un-registered write
+ * surface never emits spurious detections at runtime — the sweep meta-test is
+ * what fails the build so the gap is closed before it can matter.
+ */
+export function shouldRunPairedIntakeDetection(originContextOrigin: string): boolean {
+ return PAIRED_INTAKE_DETECTION[originContextOrigin]?.mode === 'detect';
+}
diff --git a/packages/server/src/bridge-race-rig.test-helper.ts b/packages/server/src/bridge-race-rig.test-helper.ts
new file mode 100644
index 000000000..a3eadb9a3
--- /dev/null
+++ b/packages/server/src/bridge-race-rig.test-helper.ts
@@ -0,0 +1,341 @@
+/**
+ * Deterministic bridge-race rig — one shared substrate that drives the REAL
+ * `setupServerObservers` drain on a bare `Y.Doc`, so drain-race suites assert
+ * against the production observer bridge (the `afterAllTransactions`
+ * settlement dispatcher, both observer directions, all gates, the
+ * map-driven-splice / Path-B merge write paths, and the real Observer B
+ * `parseWithFallback → updateYFragment` re-derive) rather than a replica. It is
+ * imported by sibling `*.test.ts` files; it is not itself a test.
+ *
+ * Why per-stimulus grouping. `onDispatch` fires once per drain from inside
+ * `afterAllTransactions`, and a single outermost `doc.transact()` can produce
+ * several drains: the observer sync writes are themselves nested transactions
+ * whose own settlement dispatches fire (self-origin drains report 'none'). yjs
+ * runs all of that synchronously before the outermost `transact` returns, so
+ * the rig collects every drain's dispatch decision into one trace entry keyed
+ * to the stimulus, and snapshots the settled Y.Text bytes once the stimulus
+ * completes. A dual-CRDT stimulus therefore reads as e.g.
+ * `dispatches: ['a','none','b']` with the post-drain bytes.
+ *
+ * Deterministic freshness. Observer A's re-derive freshness gate reads
+ * `Date.now()` against the last external Y.Text change (a 2s quiescence window
+ * that is not injectable). The rig fakes only `Date` (`vi.useFakeTimers({
+ * toFake: ['Date'] })`, installed by the consuming test) and advances a
+ * mutable clock past that window before each default stimulus, so whether a
+ * drain runs freshness-safe or freshness-suppressed is scripted, not
+ * wall-clock-dependent. Faking only Date keeps span timing and the settlement
+ * dispatcher (which uses no wall clock, precedent #13(b)) untouched.
+ *
+ * The rig introduces no wall-clock scheduling of its own — it holds no timers
+ * and reads the clock only through the faked `Date` the consumer installs.
+ */
+
+import { type MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
+import { getSchema, type JSONContent } from '@tiptap/core';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { vi } from 'vitest';
+import * as Y from 'yjs';
+import { mdManager as productionMdManager } from './md-manager.ts';
+import type { ObserverDispatchKind, SetupServerObserversOpts } from './server-observers.ts';
+import { setupServerObservers } from './server-observers.ts';
+
+const schema = getSchema(sharedExtensions);
+
+/**
+ * Clock advance used to cross the server's hardcoded 2s freshness-quiescence
+ * window before a default stimulus. 3s leaves a full second of headroom.
+ */
+const FRESHNESS_ADVANCE_MS = 3_000;
+
+// Non-paired stimulus origins. Plain strings are neither OBSERVER_SYNC_ORIGIN
+// (self-skip) nor a frozen PairedWriteOrigin (isPairedWriteOrigin is a
+// structural check), so the observer callbacks treat them as external edits
+// and flag the corresponding CRDT dirty.
+const RIG_EXTERNAL_ORIGIN = 'bridge-race-rig/external';
+const RIG_FORCE_ORIGIN = 'bridge-race-rig/force-a-round';
+
+const EMPTY_UPDATE_META = () => ({ mapping: new Map(), isOMark: new Map() });
+
+interface StimulusOpts {
+ /**
+ * Advance the faked `Date` past the freshness-quiescence window before
+ * mutating (default true). Pass false to run the freshness-HOT path, where
+ * an external Y.Text change is still recent and Observer A serializes with
+ * `skipFreshnessDerive` (the producer guard is skipped as knowingly
+ * historical).
+ */
+ advanceFreshness?: boolean;
+}
+
+interface DrainTraceEntry {
+ /** Stable label identifying the stimulus that produced this entry. */
+ readonly label: string;
+ /** Every drain's dispatch decision during the stimulus, in fire order. */
+ readonly dispatches: readonly ObserverDispatchKind[];
+ /** Settled `Y.Text('source')` bytes after the stimulus completed. */
+ readonly bytes: string;
+ /** Canonical serialization of the settled XmlFragment (bridge md-side). */
+ readonly fragmentMd: string;
+ /** True when `bytes` differs from the previous entry's settled bytes. */
+ readonly byteChanged: boolean;
+}
+
+export interface BridgeRaceRig {
+ readonly doc: Y.Doc;
+ readonly xmlFragment: Y.XmlFragment;
+ readonly ytext: Y.Text;
+ /** The MarkdownManager the observers run through (production singleton unless overridden). */
+ readonly mdManager: MarkdownManager;
+ /** Ordered per-stimulus trace. */
+ readonly trace: readonly DrainTraceEntry[];
+ /** Every dispatch decision across all stimuli, flattened in fire order. */
+ dispatchLog(): ObserverDispatchKind[];
+ /** Compact, comparable trace lines for the determinism contract. */
+ traceLines(): string[];
+ /** Canonical markdown serialization of the current XmlFragment. */
+ serializeFragment(): string;
+ /** Advance the faked Date clock by `ms`. */
+ advanceClock(ms: number): void;
+ /** Advance the faked Date clock past the freshness-quiescence window. */
+ advancePastFreshness(): void;
+ /** Core recorder: run `mutate`, capture the stimulus's drains + settled state. */
+ stimulus(label: string, mutate: () => void, opts?: StimulusOpts): DrainTraceEntry;
+ /** External source-editor write: replace Y.Text with `md` under a non-paired origin. */
+ seedSource(md: string, opts?: StimulusOpts): DrainTraceEntry;
+ /** Arbitrary external Y.Text mutation under a non-paired origin. */
+ externalYtextEdit(
+ label: string,
+ mutate: (ytext: Y.Text) => void,
+ opts?: StimulusOpts,
+ ): DrainTraceEntry;
+ /** WYSIWYG-shaped fragment write (parse `md` → updateYFragment). */
+ editFragment(md: string, opts?: StimulusOpts): DrainTraceEntry;
+ /**
+ * WYSIWYG-shaped fragment write with the source-capture attrs stripped from
+ * the parsed PM JSON — models a remote client's PM churn dropping the
+ * unrendered `source*` / `position` capture attrs, the flow the bridge
+ * tolerance classes exist for.
+ */
+ churnedFragmentEdit(md: string, opts?: StimulusOpts): DrainTraceEntry;
+ /**
+ * Echo-shaped fragment write: parse `baseMd`, then rewrite the FIRST text leaf
+ * matching `from` to `to`, leaving the component `sourceRaw` capture attrs a
+ * generation behind the advanced children. Under freshness suppression
+ * (`advanceFreshness: false` with a recent external Y.Text write) Observer A
+ * serializes the stale `sourceRaw` and settles, leaving the fragment holding
+ * `to` while Y.Text still holds `from` — the un-propagated-keystroke shape a
+ * later source-editor write would stomp.
+ */
+ echoFragmentEdit(baseMd: string, from: string, to: string, opts?: StimulusOpts): DrainTraceEntry;
+ /** Same-transact fragment (`md`) + Y.Text mutation — the dual-CRDT drain shape. */
+ dualMutation(
+ md: string,
+ ytextEdit: (ytext: Y.Text) => void,
+ opts?: StimulusOpts,
+ ): DrainTraceEntry;
+ /**
+ * Byte-neutral forced Observer-A round: push then delete a paragraph element
+ * in one transact. Flags the fragment dirty (dispatches 'a') and runs every
+ * gate while leaving the serialized bytes unchanged — the settle probe.
+ */
+ forceARound(opts?: StimulusOpts): DrainTraceEntry;
+ /** Run `forceARound` `rounds` times; returns the produced entries. */
+ settle(rounds: number): DrainTraceEntry[];
+ /**
+ * Run a paired-write primitive under a paired origin (e.g.
+ * `composeAndWriteRawBody` under `AGENT_WRITE_ORIGIN`). Freshness is not
+ * advanced by default — paired vectors control their own timing.
+ */
+ pairedWrite(label: string, mutate: () => void, origin: unknown): DrainTraceEntry;
+ /** Detach observers and the settlement handler. */
+ cleanup(): void;
+}
+
+export interface CreateRigOpts {
+ docName?: string;
+ /**
+ * Overrides merged into the `setupServerObservers` opts — e.g. a
+ * serialize-recording MarkdownManager proxy, or a `shadow` accessor for
+ * checkpoint-writing suites.
+ */
+ setupOverrides?: Partial<SetupServerObserversOpts>;
+}
+
+/** Rewrite the first text leaf equal to `from` into `to`, in place. */
+function mutateFirstText(node: JSONContent, from: string, to: string): boolean {
+ if (typeof node.text === 'string' && node.text === from) {
+ node.text = to;
+ return true;
+ }
+ for (const child of node.content ?? []) {
+ if (mutateFirstText(child, from, to)) return true;
+ }
+ return false;
+}
+
+/** Recursively drop `source*` / `position` capture attrs from a PM JSON tree. */
+function stripCaptureAttrs(node: JSONContent): JSONContent {
+ let next = node;
+ if (next.attrs && typeof next.attrs === 'object') {
+ const kept: Record<string, unknown> = {};
+ for (const [k, v] of Object.entries(next.attrs)) {
+ if (k.startsWith('source') || k === 'position') continue;
+ kept[k] = v;
+ }
+ next = { ...next, attrs: kept };
+ }
+ if (Array.isArray(next.content)) {
+ next = { ...next, content: next.content.map(stripCaptureAttrs) };
+ }
+ return next;
+}
+
+/**
+ * Create a bridge-race rig. The consuming test MUST install
+ * `vi.useFakeTimers({ toFake: ['Date'] })` before driving default stimuli:
+ * `advanceClock` calls `vi.setSystemTime`, which requires fake timers.
+ */
+export function createBridgeRaceRig(opts: CreateRigOpts = {}): BridgeRaceRig {
+ const doc = new Y.Doc();
+ const xmlFragment = doc.getXmlFragment('default');
+ const ytext = doc.getText('source');
+ const mdManager = opts.setupOverrides?.mdManager ?? productionMdManager;
+
+ const trace: DrainTraceEntry[] = [];
+ const pending: ObserverDispatchKind[] = [];
+ let lastBytes = ytext.toString();
+
+ const onDispatch = (kind: ObserverDispatchKind): void => {
+ pending.push(kind);
+ opts.setupOverrides?.onDispatch?.(kind);
+ };
+
+ const cleanup = setupServerObservers({
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager,
+ schema,
+ docName: opts.docName,
+ ...opts.setupOverrides,
+ onDispatch,
+ });
+
+ const serializeFragment = (): string =>
+ mdManager.serialize(yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON());
+
+ const advanceClock = (ms: number): void => {
+ vi.setSystemTime(Date.now() + ms);
+ };
+ const advancePastFreshness = (): void => advanceClock(FRESHNESS_ADVANCE_MS);
+
+ const record = (label: string): DrainTraceEntry => {
+ const bytes = ytext.toString();
+ const entry: DrainTraceEntry = {
+ label,
+ dispatches: pending.slice(),
+ bytes,
+ fragmentMd: serializeFragment(),
+ byteChanged: bytes !== lastBytes,
+ };
+ lastBytes = bytes;
+ pending.length = 0;
+ trace.push(entry);
+ return entry;
+ };
+
+ const stimulus = (label: string, mutate: () => void, sopts?: StimulusOpts): DrainTraceEntry => {
+ if (sopts?.advanceFreshness !== false) advancePastFreshness();
+ pending.length = 0;
+ mutate();
+ return record(label);
+ };
+
+ const parseNode = (md: string, churn: boolean): ReturnType<typeof schema.nodeFromJSON> => {
+ const json = mdManager.parse(md);
+ return schema.nodeFromJSON(churn ? stripCaptureAttrs(json) : json);
+ };
+
+ const populateFragment = (md: string, churn: boolean): void => {
+ updateYFragment(doc, xmlFragment, parseNode(md, churn), EMPTY_UPDATE_META());
+ };
+
+ const rig: BridgeRaceRig = {
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager,
+ trace,
+ dispatchLog: () => trace.flatMap((e) => [...e.dispatches]),
+ traceLines: () =>
+ trace.map(
+ (e) => `${e.label} dispatch=[${e.dispatches.join(',')}] byteChanged=${e.byteChanged}`,
+ ),
+ serializeFragment,
+ advanceClock,
+ advancePastFreshness,
+ stimulus,
+ seedSource: (md, sopts) =>
+ stimulus(
+ 'seed-source',
+ () => {
+ doc.transact(() => {
+ ytext.delete(0, ytext.length);
+ ytext.insert(0, md);
+ }, RIG_EXTERNAL_ORIGIN);
+ },
+ sopts,
+ ),
+ externalYtextEdit: (label, mutate, sopts) =>
+ stimulus(label, () => doc.transact(() => mutate(ytext), RIG_EXTERNAL_ORIGIN), sopts),
+ editFragment: (md, sopts) =>
+ stimulus('edit-fragment', () => populateFragment(md, false), sopts),
+ churnedFragmentEdit: (md, sopts) =>
+ stimulus('churned-fragment', () => populateFragment(md, true), sopts),
+ echoFragmentEdit: (baseMd, from, to, sopts) =>
+ stimulus(
+ 'echo-fragment',
+ () => {
+ const json = mdManager.parse(baseMd);
+ if (!mutateFirstText(json, from, to)) {
+ throw new Error(`echoFragmentEdit: text leaf '${from}' not found in parse(baseMd)`);
+ }
+ updateYFragment(doc, xmlFragment, schema.nodeFromJSON(json), EMPTY_UPDATE_META());
+ },
+ sopts,
+ ),
+ dualMutation: (md, ytextEdit, sopts) =>
+ stimulus(
+ 'dual-mutation',
+ () => {
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, parseNode(md, false), EMPTY_UPDATE_META());
+ ytextEdit(ytext);
+ }, RIG_EXTERNAL_ORIGIN);
+ },
+ sopts,
+ ),
+ forceARound: (sopts) =>
+ stimulus(
+ 'force-a-round',
+ () => {
+ doc.transact(() => {
+ const el = new Y.XmlElement('paragraph');
+ xmlFragment.push([el]);
+ xmlFragment.delete(xmlFragment.length - 1, 1);
+ }, RIG_FORCE_ORIGIN);
+ },
+ sopts,
+ ),
+ settle: (rounds) => {
+ const out: DrainTraceEntry[] = [];
+ for (let i = 0; i < rounds; i++) out.push(rig.forceARound());
+ return out;
+ },
+ pairedWrite: (label, mutate, origin) =>
+ stimulus(label, () => doc.transact(mutate, origin), { advanceFreshness: false }),
+ cleanup,
+ };
+
+ return rig;
+}
diff --git a/packages/server/src/bridge-race-rig.test.ts b/packages/server/src/bridge-race-rig.test.ts
new file mode 100644
index 000000000..605f7b45c
--- /dev/null
+++ b/packages/server/src/bridge-race-rig.test.ts
@@ -0,0 +1,141 @@
+/**
+ * Smoke + determinism contract for the bridge-race rig
+ * (`bridge-race-rig.test-helper.ts`). Proves the rig drives the real
+ * `setupServerObservers` drain to a byte fixed point, that its trace is
+ * reproducible across runs (the substrate contract the drain-race suites rely
+ * on), and that the Observer A freshness-suppressed arm — previously unmodeled
+ * in the harness — is drivable on it.
+ */
+
+import {
+ MarkdownManager,
+ type SerializeCallOptions,
+ sharedExtensions,
+} from '@inkeep/open-knowledge-core';
+import type { JSONContent } from '@tiptap/core';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { type BridgeRaceRig, createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+
+/**
+ * Freshness-ON MarkdownManager (the server posture) wrapped to record the
+ * per-call `serialize` options Observer A passes, so a test can observe
+ * whether a drain served the freshness-safe or the freshness-suppressed byte
+ * path. Mirrors the proxy in `server-observers.path-b-respell.test.ts`.
+ */
+function makeRecordingManager(): {
+ manager: MarkdownManager;
+ serializeOpts: Array<SerializeCallOptions | undefined>;
+} {
+ const real = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+ });
+ const serializeOpts: Array<SerializeCallOptions | undefined> = [];
+ const manager = new Proxy(real, {
+ get(target, prop, receiver) {
+ if (prop === 'serialize') {
+ return (json: JSONContent, opts?: SerializeCallOptions) => {
+ serializeOpts.push(opts);
+ return target.serialize(json, opts);
+ };
+ }
+ const value = Reflect.get(target, prop, receiver);
+ return typeof value === 'function' ? value.bind(target) : value;
+ },
+ });
+ return { manager, serializeOpts };
+}
+
+describe('bridge-race rig — H1 substrate', () => {
+ beforeEach(() => {
+ // Only Date is faked so the settlement dispatcher and span timing stay
+ // real; the rig advances this clock to script freshness crossings.
+ vi.useFakeTimers({ toFake: ['Date'] });
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ /**
+ * One scripted interleaving that touches every stimulus shape and drives the
+ * doc to quiescence: an external source write, a WYSIWYG fragment write, a
+ * same-transact dual-CRDT mutation, a capture-attr-stripped (churned) write,
+ * then forced Observer-A settle rounds.
+ */
+ function driveScenario(): BridgeRaceRig {
+ const rig = createBridgeRaceRig({ docName: 'race-rig-smoke.md' });
+ rig.seedSource('# Doc\n\nOriginal body.\n');
+ rig.editFragment('# Doc\n\nOriginal body.\n\nWysiwyg paragraph.\n');
+ rig.dualMutation('# Doc\n\nOriginal body.\n\nWysiwyg paragraph two.\n', (yt) =>
+ yt.insert(yt.length, 'Source tail.\n'),
+ );
+ rig.churnedFragmentEdit(
+ '# Doc\n\nOriginal body.\n\nWysiwyg paragraph two.\n\nSource tail.\n\nExtra.\n',
+ );
+ rig.settle(3);
+ return rig;
+ }
+
+ test('drives a scripted interleaving to a byte fixed point on the production drain', () => {
+ const rig = driveScenario();
+ try {
+ // The forced settle rounds each dispatch 'a' (fragment perturbation) and
+ // reach a byte fixed point: the tail rounds emit zero bytes.
+ const tail = rig.trace.slice(-2);
+ expect(tail.every((e) => e.dispatches.join(',') === 'a' && e.byteChanged === false)).toBe(
+ true,
+ );
+ const last = rig.trace.at(-1);
+ expect(last?.bytes).toContain('Original body.');
+ // Both bridge representations agree at rest (Y.Text-is-truth, precedent #38).
+ expect(rig.serializeFragment()).toBe(last?.fragmentMd);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('trace is byte-identical across 3 consecutive runs (determinism contract)', () => {
+ const runs: string[][] = [];
+ for (let i = 0; i < 3; i++) {
+ const rig = driveScenario();
+ runs.push(rig.traceLines());
+ rig.cleanup();
+ }
+ expect(runs[1]).toEqual(runs[0]);
+ expect(runs[2]).toEqual(runs[0]);
+ // The scenario actually produced a non-trivial trace (guards against a
+ // vacuously-identical empty run).
+ expect(runs[0].length).toBeGreaterThan(4);
+ });
+
+ test('the freshness-suppressed Observer A arm is drivable on the rig (P2-1: DRIVABLE)', () => {
+ const { manager, serializeOpts } = makeRecordingManager();
+ const rig = createBridgeRaceRig({
+ docName: 'race-rig-freshness.md',
+ setupOverrides: { mdManager: manager },
+ });
+ try {
+ // Settle a doc so witnesses are coherent and the freshness window is open.
+ rig.seedSource('# Doc\n\nBody line.\n');
+ rig.settle(1);
+
+ // A quiescent forced A-round serializes freshness-SAFE.
+ let before = serializeOpts.length;
+ rig.forceARound();
+ const freshCalls = serializeOpts.slice(before);
+ expect(freshCalls.some((o) => o?.skipFreshnessDerive === false)).toBe(true);
+
+ // A recent external Y.Text change with no clock advance keeps the drain
+ // freshness-HOT: the next forced A-round serializes SUPPRESSED.
+ rig.externalYtextEdit('external-hot', (yt) => yt.insert(yt.length, 'Typed tail.\n'), {
+ advanceFreshness: false,
+ });
+ before = serializeOpts.length;
+ rig.forceARound({ advanceFreshness: false });
+ const hotCalls = serializeOpts.slice(before);
+ expect(hotCalls.some((o) => o?.skipFreshnessDerive === true)).toBe(true);
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/checkpoint-restore-floor.test.ts b/packages/server/src/checkpoint-restore-floor.test.ts
new file mode 100644
index 000000000..6696e87a7
--- /dev/null
+++ b/packages/server/src/checkpoint-restore-floor.test.ts
@@ -0,0 +1,162 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import simpleGit from 'simple-git';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { extensionlessDocTreePath } from './doc-extensions.ts';
+import {
+ batchCheckExistence,
+ createAncestorShaSetCache,
+ createEmptyIndex,
+ resolveDocPathAtCommit,
+} from './rename-log.ts';
+import {
+ commitWip,
+ initShadowRepo,
+ type ShadowHandle,
+ saveInMemoryCheckpoint,
+ saveVersion,
+ shadowGit,
+ type WriterIdentity,
+} from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+const CONTENT_ROOT = 'content/docs';
+
+const human: WriterIdentity = {
+ id: 'human-ada',
+ name: 'Ada Lovelace',
+ email: '[email protected]',
+};
+
+let tmpDir: string;
+
+beforeEach(async () => {
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-restore-floor-test-'));
+});
+
+afterEach(async () => {
+ await rm(tmpDir, { recursive: true, force: true });
+});
+
+async function setup(): Promise<{ contentDir: string; shadow: ShadowHandle }> {
+ const projectRoot = resolve(tmpDir, 'project');
+ const contentDir = resolve(projectRoot, CONTENT_ROOT);
+ mkdirSync(contentDir, { recursive: true });
+ const git = simpleGit(projectRoot);
+ await git.init();
+ await git.raw('config', 'user.name', 'Test');
+ await git.raw('config', 'user.email', '[email protected]');
+ writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');
+ await git.add('.');
+ await git.commit('Initial commit');
+ const shadow = await initShadowRepo(projectRoot);
+ return { contentDir, shadow };
+}
+
+/**
+ * The restore probe the API handlers build: extension-full disk path first
+ * (full-tree checkpoints), then the extension-less docName tree path (the
+ * single-blob trees `saveInMemoryCheckpoint` writes). Mirrors the handler
+ * closures so this suite exercises the same two-shape resolution production
+ * uses.
+ */
+function candidatesFor(name: string): readonly string[] {
+ const full = `${CONTENT_ROOT}/${name}.md`;
+ const extless = extensionlessDocTreePath(full, name);
+ return extless ? [full, extless] : [full];
+}
+
+describe('extension-less silent checkpoint restore floor', () => {
+ test('getDocumentHistory surfaces a silent bridge-merge-loss checkpoint row', async () => {
+ const { contentDir, shadow } = await setup();
+ writeFileSync(resolve(contentDir, 'intro.md'), '# Edited\n');
+ await commitWip(shadow, human, CONTENT_ROOT, 'WIP: edit');
+
+ // Production callers pass the extension-LESS Hocuspocus docName, so the
+ // blob lands at `content/docs/intro` (no `.md`).
+ const silentSha = await saveInMemoryCheckpoint(shadow, CONTENT_ROOT, {
+ kind: 'bridge-merge-loss',
+ docName: 'intro',
+ contents: '# Pre-loss baseline\n',
+ label: 'Before concurrent merge @ 2026-05-05T12:00:00Z',
+ branch: 'main',
+ metadata: { lostSubstrings: ['a lost keystroke'] },
+ });
+
+ const hist = await getDocumentHistory(shadow, { docName: 'intro' }, CONTENT_ROOT);
+ const cpRow = hist.entries.find((e) => e.sha === silentSha);
+ expect(cpRow).toBeDefined();
+ expect(cpRow?.type).toBe('checkpoint');
+ expect(cpRow?.checkpoint?.kind).toBe('bridge-merge-loss');
+ expect(cpRow?.message).toContain('Before concurrent merge');
+ });
+
+ test('resolveDocPathAtCommit resolves the extension-less blob and git show reads the content', async () => {
+ const { contentDir, shadow } = await setup();
+ writeFileSync(resolve(contentDir, 'intro.md'), '# Edited\n');
+ await commitWip(shadow, human, CONTENT_ROOT, 'WIP: edit');
+
+ const silentSha = await saveInMemoryCheckpoint(shadow, CONTENT_ROOT, {
+ kind: 'producer-guard-loss',
+ docName: 'intro',
+ contents: '# Rescued content\n',
+ label: 'Before producer-guard content-loss @ 2026-05-05T12:00:00Z',
+ branch: 'main',
+ metadata: { construct: 'paragraph' },
+ });
+
+ const index = createEmptyIndex();
+ const cache = createAncestorShaSetCache();
+ const resolved = await resolveDocPathAtCommit(
+ shadow,
+ 'intro',
+ silentSha,
+ 'main',
+ index,
+ candidatesFor,
+ cache,
+ );
+ expect(resolved).toBe(`${CONTENT_ROOT}/intro`);
+
+ const content = (await shadowGit(shadow).raw('show', `${silentSha}:${resolved}`)).toString();
+ expect(content).toBe('# Rescued content\n');
+ });
+
+ test('both shapes resolve: a full-tree Save Version still resolves via the extension-full path', async () => {
+ const { contentDir, shadow } = await setup();
+ writeFileSync(resolve(contentDir, 'intro.md'), '# Current disk state\n');
+ const sv = await saveVersion(shadow, CONTENT_ROOT, [human], 'main');
+ const svSha = sv.checkpointRef.match(/([0-9a-f]{40})$/)?.[1] ?? '';
+ expect(svSha).toMatch(/^[0-9a-f]{40}$/);
+
+ const index = createEmptyIndex();
+ const cache = createAncestorShaSetCache();
+ const resolved = await resolveDocPathAtCommit(
+ shadow,
+ 'intro',
+ svSha,
+ 'main',
+ index,
+ candidatesFor,
+ cache,
+ );
+ // Full-tree snapshots mirror disk (extension-full); the extension-full
+ // candidate is probed first, so it wins — no extension-less regression.
+ expect(resolved).toBe(`${CONTENT_ROOT}/intro.md`);
+ });
+
+ test('batchCheckExistence counts only blobs — a directory sharing the doc name does not resolve', async () => {
+ const { contentDir, shadow } = await setup();
+ writeFileSync(resolve(contentDir, 'intro.md'), '# Current\n');
+ const sv = await saveVersion(shadow, CONTENT_ROOT, [human], 'main');
+ const svSha = sv.checkpointRef.match(/([0-9a-f]{40})$/)?.[1] ?? '';
+
+ const res = await batchCheckExistence(shadow, [
+ { sha: svSha, path: CONTENT_ROOT }, // a directory (tree), not the doc blob
+ { sha: svSha, path: `${CONTENT_ROOT}/intro.md` }, // the doc blob
+ ]);
+ expect(res).toEqual([false, true]);
+ });
+});
diff --git a/packages/server/src/derive-defer-floor.test.ts b/packages/server/src/derive-defer-floor.test.ts
new file mode 100644
index 000000000..8e12a6f57
--- /dev/null
+++ b/packages/server/src/derive-defer-floor.test.ts
@@ -0,0 +1,271 @@
+/**
+ * The checkpoint floor under a DEFERRED keystroke, on the REAL
+ * `setupServerObservers` drain plus a real `AgentSessionManager` session.
+ *
+ * Staging is defer-then-trigger. A WYSIWYG keystroke sits un-propagated in the
+ * fragment, a source-editor write drives an Observer B re-derive that the
+ * derive-timing guard defers, and only then does a paired vector run. That
+ * ordering matters: a defer moves Y.Text past Observer A's raw witness without
+ * moving the witness, so the pre-drain planner's `witnessMatched` leg fails
+ * closed BEFORE it ever reaches the overlap classification. Every paired vector
+ * measured from this staging therefore lands on the checkpoint floor — the
+ * pre-drain flush carries none of them. Each arm below pins that the floor
+ * actually fired for its own vector: a `bridge-derive-loss` checkpoint whose
+ * payload carries the keystroke, reachable as a restore row on the timeline.
+ *
+ * The paired-intake floor is a union of a substring-drop twin and a
+ * whole-raw-line predicate; the deferred keystroke here is the intra-line
+ * `bod`→`body.` shape that only the line predicate can express, so these arms
+ * bind on that leg specifically.
+ *
+ * Not covered here, deliberately: the source-mode row. A source-editor edit
+ * arriving after a defer leaves the keystroke live in the fragment and neither
+ * carried into Y.Text nor checkpointed — it converges only on the next
+ * fragment-side edit and does not survive an unload. That is an open liveness
+ * gap, not intended behavior, so pinning it with a test would ratify it.
+ *
+ * A second residual, reachable from this rig but not from user typing: a stale
+ * `sourceRaw` capture whose component children have advanced can drive a shape
+ * that removes content from BOTH replicas. A real keystroke cannot present it —
+ * `packages/app/src/editor/extensions/source-dirty-observer.ts` (~line 153)
+ * flips `sourceDirty` on every component a user transaction edits, and
+ * `packages/app/src/editor/utils/reconstruct-source.ts` (~line 14) takes the
+ * verbatim `sourceRaw` fast path only while that flag is clean, with
+ * `packages/core/src/bridge/structural-freshness.ts` as the server-side
+ * backstop. It remains reachable in principle only on the raw-CRDT-peer surface
+ * that structural-freshness explicitly delegates to the producer guard, and only
+ * while a drain is freshness-suppressed (`server-observers.ts` ~line 1705). The
+ * rig stamps those attrs by hand, which is why it can reach a shape the product
+ * cannot.
+ */
+
+import { readFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import type { Hocuspocus } from '@hocuspocus/server';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+ type BridgeDeriveLossReporter,
+ createBridgeDeriveLossReporter,
+ DERIVE_LOSS_SITE_AGENT_UNDO,
+ DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE,
+ DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE,
+} from './bridge-loss-detector.ts';
+import { DocumentDurabilityState } from './document-durability-state.ts';
+import { applyExternalChange } from './external-change.ts';
+import {
+ type LossCaptureEvent,
+ LossCaptureRing,
+ lossCaptureCurrentPath,
+ parseLossCaptureLines,
+} from './loss-capture.ts';
+import {
+ createWiredPreDrainRig,
+ WIRED_PENDING_LINE,
+ type WiredPreDrainRig,
+} from './pre-drain-wired.test-helper.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+interface FloorHarness {
+ readonly wired: WiredPreDrainRig;
+ readonly shadow: ShadowHandle;
+ readonly ring: LossCaptureRing;
+ readonly docName: string;
+ /** How many drains the derive-timing guard has deferred so far. */
+ deferCount(): number;
+ /**
+ * Stage the un-propagated keystroke, then drive a source-editor write that
+ * the derive-timing guard defers. Asserts the defer actually fired, so an arm
+ * can never silently degrade into the never-deferred staging.
+ */
+ stageDeferredKeystroke(): void;
+ /** Poll until the floor's async checkpoint lands, or give up. */
+ awaitDetectorTrip(): Promise<LossCaptureEvent | undefined>;
+ cleanup(): Promise<void>;
+}
+
+async function createFloorHarness(docName: string): Promise<FloorHarness> {
+ const tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-defer-floor-'));
+ const projectRoot = resolve(tmpDir, 'project');
+ const shadow = await initShadowRepo(projectRoot);
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+ const reporter: BridgeDeriveLossReporter = createBridgeDeriveLossReporter({
+ shadow: () => shadow,
+ ring,
+ getBranch: () => 'main',
+ contentRoot: '',
+ });
+ let defers = 0;
+ const wired = await createWiredPreDrainRig({
+ docName,
+ reporter,
+ setupOverrides: {
+ onDeriveTimingDefer: () => {
+ defers += 1;
+ },
+ },
+ });
+
+ return {
+ wired,
+ shadow,
+ ring,
+ docName,
+ deferCount: () => defers,
+ stageDeferredKeystroke: () => {
+ wired.stageUnpropagatedKeystroke();
+ const before = defers;
+ // A source-editor write inside the freshness-hot window is the drain the
+ // guard defers; `advanceFreshness: false` keeps the window hot.
+ wired.rig.externalYtextEdit(
+ 'source-write',
+ (yt) => yt.insert(yt.length, '\nAnother source line.\n'),
+ { advanceFreshness: false },
+ );
+ expect(defers).toBeGreaterThan(before);
+ expect(wired.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(wired.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ },
+ awaitDetectorTrip: async () => {
+ let trip: LossCaptureEvent | undefined;
+ for (let i = 0; i < 100 && !trip; i++) {
+ await ring.drain();
+ try {
+ const events = parseLossCaptureLines(
+ readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'),
+ );
+ trip = events.find((e) => e.event === 'detector-trip' && Boolean(e.checkpointSha));
+ } catch {
+ /* the capture file may not exist until the first record flushes */
+ }
+ if (!trip) await new Promise((r) => setTimeout(r, 10));
+ }
+ return trip;
+ },
+ cleanup: async () => {
+ await wired.cleanup();
+ await rm(tmpDir, { recursive: true, force: true });
+ },
+ };
+}
+
+/**
+ * The shared floor assertions: a `bridge-derive-loss` checkpoint attributed to
+ * `expectedSite`, whose payload carries the deferred keystroke, surfaced as a
+ * restorable timeline row. The ring event itself stays content-free.
+ */
+async function expectRestorableFloorCheckpoint(
+ h: FloorHarness,
+ expectedSite: string,
+): Promise<void> {
+ const trip = await h.awaitDetectorTrip();
+ expect(trip).toBeDefined();
+ expect(trip?.site).toBe(expectedSite);
+ expect(typeof trip?.lostLen).toBe('number');
+ expect(JSON.stringify(trip)).not.toContain(WIRED_PENDING_LINE);
+
+ const blob = (
+ await shadowGit(h.shadow).raw('show', `${trip?.checkpointSha}:${h.docName}`)
+ ).toString();
+ expect(blob).toContain(WIRED_PENDING_LINE);
+
+ const hist = await getDocumentHistory(h.shadow, { docName: h.docName }, '');
+ const row = hist.entries.find((e) => e.sha === trip?.checkpointSha);
+ expect(row?.checkpoint?.kind).toBe('bridge-derive-loss');
+}
+
+describe('checkpoint floor after a derive-timing defer', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ test('agent append: the deferred keystroke lands on the floor, restorable', async () => {
+ const h = await createFloorHarness('floor-agent-append');
+ try {
+ h.stageDeferredKeystroke();
+
+ h.wired.agentWriteWithPreDrain('An appended agent paragraph.', 'append');
+
+ // Neither replica carries it forward — the floor is the only survival path.
+ expect(h.wired.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ expect(h.wired.serializeFragment()).not.toContain(WIRED_PENDING_LINE);
+ await expectRestorableFloorCheckpoint(h, DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('agent replace: the deferred keystroke lands on the floor, restorable', async () => {
+ const h = await createFloorHarness('floor-agent-replace');
+ try {
+ h.stageDeferredKeystroke();
+
+ h.wired.agentWriteWithPreDrain('## Replaced\n\nBrand new body.\n', 'replace');
+
+ expect(h.wired.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ expect(h.wired.serializeFragment()).not.toContain(WIRED_PENDING_LINE);
+ await expectRestorableFloorCheckpoint(h, DERIVE_LOSS_SITE_AGENT_WRITE_INTAKE);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('agent undo of a single frame: the deferred keystroke lands on the floor, restorable', async () => {
+ const h = await createFloorHarness('floor-agent-undo');
+ try {
+ // An agent write first, so the undo has exactly one frame to revert.
+ h.wired.agentWrite('Agent appended line.', 'append');
+ expect(h.wired.ytextString()).toContain('Agent appended line.');
+
+ h.stageDeferredKeystroke();
+
+ expect(h.wired.agentUndo('last')).toBe(true);
+
+ // The undo's own effect landed, and the keystroke went to the floor.
+ expect(h.wired.ytextString()).not.toContain('Agent appended line.');
+ expect(h.wired.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ expect(h.wired.serializeFragment()).not.toContain(WIRED_PENDING_LINE);
+ await expectRestorableFloorCheckpoint(h, DERIVE_LOSS_SITE_AGENT_UNDO);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('file-watcher change: the deferred keystroke lands on the floor, restorable', async () => {
+ const h = await createFloorHarness('floor-file-watcher');
+ try {
+ h.stageDeferredKeystroke();
+
+ // A disk edit arriving at the live doc, through the production handler.
+ const hocuspocus = {
+ documents: new Map([[h.docName, h.wired.doc]]),
+ } as unknown as Hocuspocus;
+ applyExternalChange(
+ new DocumentDurabilityState(),
+ hocuspocus,
+ h.docName,
+ '## Guide\n\nRewritten from disk.\n',
+ undefined,
+ undefined,
+ createBridgeDeriveLossReporter({
+ shadow: () => h.shadow,
+ ring: h.ring,
+ getBranch: () => 'main',
+ contentRoot: '',
+ }),
+ );
+
+ expect(h.wired.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ expect(h.wired.serializeFragment()).not.toContain(WIRED_PENDING_LINE);
+ await expectRestorableFloorCheckpoint(h, DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE);
+ } finally {
+ await h.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/derive-fixed-point-backstop.test.ts b/packages/server/src/derive-fixed-point-backstop.test.ts
new file mode 100644
index 000000000..05f3b5693
--- /dev/null
+++ b/packages/server/src/derive-fixed-point-backstop.test.ts
@@ -0,0 +1,504 @@
+/**
+ * Re-derive-loop fixed-point backstop (the loud re-derive-loop tripwire) on the REAL
+ * `setupServerObservers` drain via the shared bridge-race rig.
+ *
+ * The Y.Text→XmlFragment re-derive cycle terminates on a RAW-BYTE fixed point: a
+ * drain whose settled Y.Text raw-equals the fragment's canonical serialization.
+ * A run of re-derive drains that never reaches one hits a drain-count backstop
+ * that freezes the B-direction re-derive loop LOUDLY — a checkpoint of the
+ * authoritative Y.Text plus a distinguishable `backstop-trip` ring event, never
+ * a silent truncate-and-continue. The A-direction (user edits) and persistence
+ * stay live.
+ *
+ * Distinguishing a loop from progress. A doc that never reaches a raw fixed
+ * point but keeps advancing to NEW states is forward progress (a large
+ * residual-bearing edit stream), not a loop. A doc that never converges and
+ * REVISITS a recently-settled state is oscillating. The backstop counts
+ * consecutive corrective drains whose settled Y.Text revisits the recent ring;
+ * a run reaching the bound freezes the B-direction loop.
+ *
+ * The revisit signal is raw bytes, not `normalizeBridge` tolerance: two forms
+ * that are normalize-EQUAL but byte-different (a trailing-whitespace residual
+ * serialize never reproduces) are distinct states, so an oscillation between
+ * them still trips — which a normalize-tolerant check would mask. Single-server
+ * flows self-correct to a fixed point,
+ * so a sustained oscillation is the un-probed echo/normalize-UNEQUAL residue
+ * this cap exists to bound; the synthetic corrective-write loop below drives it.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import simpleGit from 'simple-git';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+import { LOSS_EVENT_BACKSTOP_TRIP, type LossCaptureEventInput } from './loss-capture.ts';
+import { getMetrics } from './metrics.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+const CONTENT_ROOT = 'content/docs';
+
+// Two non-round-trip source forms that are normalize-EQUAL to their canonical
+// (the trailing whitespace is tolerated but stripped by serialize, so neither
+// reaches a raw-byte fixed point) yet byte-different from each other. Alternating
+// them is a 2-cycle: the doc revisits a recent state every round without ever
+// converging — the synthetic corrective-write loop.
+const CYCLE_FORM_A = '# Cycle\n\nalpha side of the loop \n';
+const CYCLE_FORM_B = '# Cycle\n\nbravo side of the loop \n';
+function cycleForm(i: number): string {
+ return i % 2 === 0 ? CYCLE_FORM_A : CYCLE_FORM_B;
+}
+
+/** Drive the oscillation until the backstop trips (or a generous ceiling). */
+function driveCycleUntilTrip(rig: ReturnType<typeof createBridgeRaceRig>, trips: number[]): void {
+ for (let i = 0; i < 24 && trips.length === 0; i++) rig.seedSource(cycleForm(i));
+}
+
+describe('re-derive fixed-point backstop (H4)', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ test('a normalize-equal-but-byte-different loop is not treated as converged and trips the backstop loudly', () => {
+ const trips: number[] = [];
+ const recorded: LossCaptureEventInput[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'backstop-trip.md',
+ setupOverrides: {
+ onReDeriveBackstop: (rounds) => trips.push(rounds),
+ lossRing: {
+ record: async (input) => {
+ recorded.push(input);
+ },
+ },
+ },
+ });
+ const before = getMetrics().reDeriveBackstopTripped;
+ try {
+ // The doc revisits two byte-different, normalize-equal states every round
+ // and never converges. A normalize-tolerant termination check would call
+ // both states converged and never trip.
+ driveCycleUntilTrip(rig, trips);
+
+ // Loud trip: exactly one, with the drain-count bound reported.
+ expect(trips.length).toBe(1);
+ const rounds = trips[0] ?? 0;
+ // Cap is at least 4 (2x the worst measured legitimate run of 1).
+ expect(rounds).toBeGreaterThanOrEqual(4);
+ expect(getMetrics().reDeriveBackstopTripped).toBe(before + 1);
+
+ // A distinguishable, content-free backstop-trip ring event fired.
+ const evt = recorded.find((e) => e.event === LOSS_EVENT_BACKSTOP_TRIP);
+ expect(evt).toBeDefined();
+ expect(evt?.direction).toBe('b');
+ expect(evt?.site).toBe('rederive-backstop');
+ // No `lostLen`: the freeze loses nothing — Y.Text stays authoritative and
+ // the checkpoint anchors it. Only the B-direction re-derive stops.
+ expect(evt?.lostLen).toBeUndefined();
+ // Content-free: the document text never rides the event.
+ expect(JSON.stringify(evt)).not.toContain('side of the loop');
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a churned-table respell oscillation trips: alternating pipe-dash table forms revisit without converging', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'table-cycle.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ // Two table forms (canonical pipe-dash delimiter, so no watchdog trip) that
+ // carry a trailing-whitespace residual serialize strips — non-round-trip and
+ // byte-different from each other. Alternating them revisits a recent state
+ // every round without converging: the churned-table respell as a sustained
+ // corrective-write loop.
+ const tableA = '| a | alpha |\n| - | - |\n| 1 | 2 | \n';
+ const tableB = '| a | bravo |\n| - | - |\n| 1 | 2 | \n';
+ for (let i = 0; i < 24 && trips.length === 0; i++) {
+ rig.seedSource(i % 2 === 0 ? tableA : tableB);
+ }
+ expect(trips.length).toBe(1);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('forward progress never trips: a monotonic non-round-trip edit stream advances without oscillating', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'progress.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ // Each round is a NEW state carrying a trailing-whitespace residual (never a
+ // raw-byte fixed point), but the content keeps advancing — forward progress,
+ // not a revisit. The backstop must not freeze a doc that is simply large or
+ // residual-bearing.
+ for (let i = 0; i < 40; i++) rig.seedSource(`# Doc\n\nrunning body line ${i} \n`);
+ expect(trips).toEqual([]);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('legitimate flows never trip: WYSIWYG typing, round-trip source typing, and a churned-table respell all settle', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'legit.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ // WYSIWYG typing: each keystroke is new content that converges (A writes
+ // the canonical serialization, so Y.Text raw-equals the fragment).
+ for (let i = 0; i < 20; i++) rig.editFragment(`# Doc\n\nbody line ${i}\n`);
+ // Round-trip-stable source typing: parse captures the bytes, so each
+ // re-derive reaches a raw fixed point.
+ for (let i = 0; i < 20; i++) rig.seedSource(`# Doc\n\nsource line ${i}\n`);
+ // A churned-table respell (pipe-dash canonicalization) is k=1 stable — it
+ // canonicalizes in one round and settles, never a sustained loop.
+ for (let i = 0; i < 20; i++) rig.churnedFragmentEdit(`| a | b${i} |\n|---|---|\n| 1 | 2 |\n`);
+
+ expect(trips).toEqual([]);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test("the spike's masking-class fixtures each settle to a fixed point without tripping", () => {
+ // The tolerance classes canonicalize on the first materializing write and
+ // then rest (k<=1 per the oscillation spike). Repeatedly re-churning each one
+ // stays at that fixed point — a settled residual, never a revisiting loop.
+ const maskingFixtures = [
+ '# Escape\n\n_leading underscore word\n\n[bracket opener text\n',
+ 'Wrap **before ** mid ** after** end.\n',
+ '- top\n - nested four\n - deeper eight\n',
+ '# Title \n\nParagraph one ends here. \n\nLast.\n',
+ '1. one\n1. two\n1. three\n',
+ ];
+ for (const fixture of maskingFixtures) {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'masking.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ // Re-churn the same fixture repeatedly (models a client dropping the
+ // source-capture attrs): the canonicalization is a one-way ratchet, so it
+ // settles after the first round and never accumulates.
+ for (let i = 0; i < 20; i++) rig.churnedFragmentEdit(fixture);
+ rig.settle(4);
+ expect(trips).toEqual([]);
+ } finally {
+ rig.cleanup();
+ }
+ }
+ });
+
+ test('forced settlement rounds on a converged doc are fixed points, not events', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'rest.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ rig.seedSource('# Rest\n\nsettled body.\n');
+ // Byte-neutral forced Observer-A rounds: A runs every gate and emits zero
+ // new bytes — a zero-byte round IS the fixed point, even when a re-derive
+ // fires. No round accumulates.
+ rig.settle(20);
+ expect(trips).toEqual([]);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('D2-deferred drains are non-events for the backstop', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'defer-noevent.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ const beforeForceResolve = getMetrics().deriveTimingDeferForceResolved;
+ try {
+ // Stage an un-propagated keystroke, then sustain the freshness-hot window so
+ // the defer guard defers up to its own bound and force-resolves. Those
+ // deferred drains must not feed the backstop counter: the defer path drives
+ // to its force-resolve without the backstop tripping first.
+ rig.editFragment(
+ '## Guide\n\nIntro.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n',
+ );
+ rig.settle(1);
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing.\n'));
+ rig.echoFragmentEdit(rig.ytext.toString(), 'Step one bod', 'Step one body.', {
+ advanceFreshness: false,
+ });
+ for (let i = 0; i < 30; i++) {
+ rig.externalYtextEdit('src', (yt) => yt.insert(yt.length, `\nt-${i}\n`), {
+ advanceFreshness: false,
+ });
+ if (getMetrics().deriveTimingDeferForceResolved > beforeForceResolve) break;
+ }
+ // The defer path fired its own loud force-resolve; the backstop stayed
+ // silent — deferred drains never counted toward its bound.
+ expect(getMetrics().deriveTimingDeferForceResolved).toBeGreaterThan(beforeForceResolve);
+ expect(trips).toEqual([]);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('freeze scope: the B-direction is frozen while persistence stays live', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'freeze-b.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ driveCycleUntilTrip(rig, trips);
+ expect(trips.length).toBe(1);
+ const frozenFragment = rig.serializeFragment();
+
+ // B is frozen: a further source edit does NOT rebuild the fragment (it
+ // stays at the pre-freeze content) — the B-direction re-derive is skipped.
+ rig.seedSource('# Cycle\n\na fresh source edit B will not re-derive while frozen \n');
+ expect(rig.serializeFragment()).toBe(frozenFragment);
+ // Persistence stays live: Y.Text (the source of truth) still holds the edit.
+ expect(rig.ytext.toString()).toContain('a fresh source edit B will not re-derive');
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('freeze scope: the A-direction stays live and a converging drain unfreezes the loop', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'freeze-a.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ driveCycleUntilTrip(rig, trips);
+ expect(trips.length).toBe(1);
+
+ // The A-direction stays live: a WYSIWYG fragment edit right after the trip
+ // (Y.Text still matches the last settlement witness, so Observer A takes the
+ // clean Path-A write) propagates to a raw-equal Y.Text, which unfreezes the
+ // loop. A subsequent source edit then re-derives normally again.
+ rig.editFragment('# Recovered\n\nwysiwyg edit converges the doc\n');
+ expect(rig.ytext.toString()).toContain('wysiwyg edit converges the doc');
+ rig.seedSource('# After\n\nsource edit re-derives after the unfreeze\n');
+ expect(rig.serializeFragment()).toContain('source edit re-derives after the unfreeze');
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('typing during a freeze persists — the user-edit path and Y.Text stay live while the B loop is frozen', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'freeze-persists.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ driveCycleUntilTrip(rig, trips);
+ expect(trips.length).toBe(1);
+ const frozenFragment = rig.serializeFragment();
+
+ // Persistence stays live through the freeze: a source keystroke (direct
+ // Y.Text) lands in the authoritative bytes and is not lost, while the B
+ // re-derive loop stays frozen (the fragment does not rebuild). Freeze
+ // scope is B-only; Y.Text-is-truth persistence is never part of it.
+ rig.seedSource('# Cycle\n\ntyped into source while the loop is frozen — not lost \n');
+ expect(rig.serializeFragment()).toBe(frozenFragment);
+ expect(rig.ytext.toString()).toContain(
+ 'typed into source while the loop is frozen — not lost',
+ );
+
+ // The A-direction stays live too: a WYSIWYG edit propagates through
+ // Observer A into Y.Text. Observer A runs before (and independently of) the
+ // frozen B re-derive, so user typing keeps reaching the source of truth.
+ rig.editFragment('# Typed\n\nwysiwyg content typed during the freeze reaches Y.Text\n');
+ expect(rig.ytext.toString()).toContain(
+ 'wysiwyg content typed during the freeze reaches Y.Text',
+ );
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('kill-switch OFF: the loop churns unbounded with no trip; default-ON pinned', () => {
+ const off: number[] = [];
+ const rigOff = createBridgeRaceRig({
+ docName: 'backstop-off.md',
+ setupOverrides: { fixedPointBackstopEnabled: false, onReDeriveBackstop: (r) => off.push(r) },
+ });
+ try {
+ for (let i = 0; i < 24; i++) rigOff.seedSource(cycleForm(i));
+ // Inert: the same oscillation that trips when ON churns unbounded.
+ expect(off).toEqual([]);
+ // B is never frozen — the last source edit still re-derives.
+ expect(rigOff.serializeFragment()).toContain('bravo side of the loop');
+ } finally {
+ rigOff.cleanup();
+ }
+
+ // Default-ON: an unconfigured rig (no fixedPointBackstopEnabled) trips.
+ const on: number[] = [];
+ const rigOn = createBridgeRaceRig({
+ docName: 'backstop-default.md',
+ setupOverrides: { onReDeriveBackstop: (r) => on.push(r) },
+ });
+ try {
+ driveCycleUntilTrip(rigOn, on);
+ expect(on.length).toBe(1);
+ } finally {
+ rigOn.cleanup();
+ }
+ });
+});
+
+describe('re-derive fixed-point backstop — checkpoint floor', () => {
+ let tmpDir: string;
+
+ beforeEach(async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-backstop-'));
+ });
+ afterEach(async () => {
+ vi.useRealTimers();
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ async function setupShadow(): Promise<ShadowHandle> {
+ const projectRoot = resolve(tmpDir, 'project');
+ const contentDir = resolve(projectRoot, CONTENT_ROOT);
+ mkdirSync(contentDir, { recursive: true });
+ const git = simpleGit(projectRoot);
+ await git.init();
+ await git.raw('config', 'user.name', 'Test');
+ await git.raw('config', 'user.email', '[email protected]');
+ writeFileSync(resolve(contentDir, 'backstop.md'), '# Seed\n');
+ await git.add('.');
+ await git.commit('Initial commit');
+ return initShadowRepo(projectRoot);
+ }
+
+ test('a trip writes a resolvable bridge-backstop-trip checkpoint holding the frozen Y.Text', async () => {
+ const shadow = await setupShadow();
+ const recorded: LossCaptureEventInput[] = [];
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'backstop',
+ setupOverrides: {
+ onReDeriveBackstop: (r) => trips.push(r),
+ shadow: () => shadow,
+ getBranch: () => 'main',
+ contentRoot: CONTENT_ROOT,
+ lossRing: {
+ record: async (input) => {
+ recorded.push(input);
+ },
+ },
+ },
+ });
+ try {
+ // Capture the authoritative Y.Text at the exact drain that trips — later
+ // source edits still land in Y.Text (persistence stays live), so the
+ // post-loop bytes differ from what the checkpoint anchored at freeze time.
+ let frozenYText = '';
+ for (let i = 0; i < 24; i++) {
+ rig.seedSource(cycleForm(i));
+ if (!frozenYText && trips.length > 0) {
+ frozenYText = rig.ytext.toString();
+ break;
+ }
+ }
+ expect(frozenYText).not.toBe('');
+
+ // The checkpoint is fire-and-forget (queueMicrotask + real git); the
+ // sha-bearing ring event fires from inside its `then`.
+ await vi.waitFor(() =>
+ expect(
+ recorded.some(
+ (e) => e.event === LOSS_EVENT_BACKSTOP_TRIP && typeof e.checkpointSha === 'string',
+ ),
+ ).toBe(true),
+ );
+ const evt = recorded.find(
+ (e) => e.event === LOSS_EVENT_BACKSTOP_TRIP && typeof e.checkpointSha === 'string',
+ );
+ const sha = evt?.checkpointSha;
+ expect(sha).toMatch(/^[0-9a-f]{40}$/);
+
+ // The sha resolves against the checkpoint store as a bridge-backstop-trip row.
+ const hist = await getDocumentHistory(shadow, { docName: 'backstop' }, CONTENT_ROOT);
+ const row = hist.entries.find((e) => e.sha === sha);
+ expect(row?.type).toBe('checkpoint');
+ expect(row?.checkpoint?.kind).toBe('bridge-backstop-trip');
+
+ // The checkpoint holds the authoritative Y.Text at freeze time — the
+ // restore anchor for the pre-freeze state.
+ const content = (
+ await shadowGit(shadow).raw('show', `${sha}:${CONTENT_ROOT}/backstop`)
+ ).toString();
+ expect(content).toBe(frozenYText);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a checkpoint-write failure still fires a sha-less backstop-trip ring event (never silent)', async () => {
+ const recorded: LossCaptureEventInput[] = [];
+ const trips: number[] = [];
+ // A shadow handle pointing at a non-existent git dir makes the REAL
+ // saveInMemoryCheckpoint write reject — the compound shadow-write-failure
+ // path (disk full, permissions, collision) the no-shadow branch can't reach.
+ const brokenShadow: ShadowHandle = {
+ gitDir: resolve(tmpDir, 'no-such-shadow.git'),
+ workTree: resolve(tmpDir, 'no-such-worktree'),
+ };
+ const rig = createBridgeRaceRig({
+ docName: 'backstop',
+ setupOverrides: {
+ onReDeriveBackstop: (r) => trips.push(r),
+ shadow: () => brokenShadow,
+ getBranch: () => 'main',
+ contentRoot: CONTENT_ROOT,
+ lossRing: {
+ record: async (input) => {
+ recorded.push(input);
+ },
+ },
+ },
+ });
+ const before = getMetrics().reDeriveBackstopTripped;
+ try {
+ driveCycleUntilTrip(rig, trips);
+ expect(trips.length).toBe(1);
+ // The trip is real: the counter moved even though the checkpoint write is
+ // about to fail — the "metric up" half the ring must corroborate.
+ expect(getMetrics().reDeriveBackstopTripped).toBe(before + 1);
+
+ // The checkpoint write rejects (bogus git dir), so the catch runs. It must
+ // still emit a sha-less backstop-trip ring event — otherwise the fire is
+ // invisible in loss-current.jsonl and the freeze reads like "ring disabled".
+ await vi.waitFor(() =>
+ expect(recorded.some((e) => e.event === LOSS_EVENT_BACKSTOP_TRIP)).toBe(true),
+ );
+ const evt = recorded.find((e) => e.event === LOSS_EVENT_BACKSTOP_TRIP);
+ expect(evt?.direction).toBe('b');
+ expect(evt?.site).toBe('rederive-backstop');
+ // Sha-less: the checkpoint never landed, so there is no restore anchor.
+ expect(evt?.checkpointSha).toBeUndefined();
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/derive-fixed-point-comparand.test.ts b/packages/server/src/derive-fixed-point-comparand.test.ts
new file mode 100644
index 000000000..a32a21f42
--- /dev/null
+++ b/packages/server/src/derive-fixed-point-comparand.test.ts
@@ -0,0 +1,103 @@
+/**
+ * The raw-byte fixed-point comparand, pinned on the arm the pure-B suites
+ * cannot reach: a drain where Observer A runs BEFORE Observer B.
+ *
+ * The fixed point is defined as "the settled Y.Text raw-equals the fragment's
+ * canonical serialization" — the termination signal that resets the oscillation
+ * run and releases a backstop freeze — and the release is owed to the next
+ * fixed-point-REACHING drain. Observer A refreshes the RAW witness from `ytext`
+ * at every settlement and then enqueues a same-drain Observer B when the
+ * settlement is split-brain, so on that arm the raw witness and Observer B's
+ * `ytext.toString()` are the same string by construction. Testing the fixed
+ * point against the raw witness there is a tautology: the non-converged drain
+ * declares convergence, clears the oscillation ring, and unfreezes a live
+ * backstop — which lets the very loop the backstop just froze start over.
+ *
+ * The dual-CRDT drain below is the reachable shape: one external transaction
+ * mutates both CRDTs, Observer A routes the Path-B merge and settles
+ * residual-bearing, and its split-brain check enqueues Observer B into the same
+ * drain.
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+
+// Two normalize-EQUAL, byte-different forms (the trailing whitespace is
+// tolerated but stripped by serialize, so neither reaches a raw-byte fixed
+// point). Alternating them is the oscillation the backstop bounds.
+const CYCLE_FORM_A = '# Cycle\n\nalpha side of the loop \n';
+const CYCLE_FORM_B = '# Cycle\n\nbravo side of the loop \n';
+
+function driveCycle(
+ rig: ReturnType<typeof createBridgeRaceRig>,
+ trips: number[],
+ untilTripCount: number,
+): void {
+ for (let i = 0; i < 40 && trips.length < untilTripCount; i++) {
+ rig.seedSource(i % 2 === 0 ? CYCLE_FORM_A : CYCLE_FORM_B);
+ }
+}
+
+describe('raw-byte fixed point on an A-then-B drain', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ test('a dual-CRDT drain that settles residual-bearing does NOT release a live backstop freeze', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'ab-comparand.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ driveCycle(rig, trips, 1);
+ expect(trips.length).toBe(1);
+
+ // One transaction mutates BOTH CRDTs: Observer A merges (Path B), settles,
+ // and its split-brain check enqueues Observer B into the same drain — where
+ // the raw witness Observer A just refreshed equals this very `ytext`.
+ rig.dualMutation('# Cycle\n\ngamma side of the loop\n', (yt) => {
+ yt.insert(yt.length, 'concurrent tail \n');
+ });
+ // The drain settled NON-converged: the authoritative bytes and the
+ // fragment's canonical form disagree, so this was not a fixed point.
+ expect(rig.ytext.toString()).not.toBe(rig.serializeFragment());
+
+ // The freeze must survive it. If the drain had (wrongly) been read as a
+ // fixed point, the oscillation ring would be cleared and the B-direction
+ // unfrozen — letting the same loop run to a SECOND trip.
+ driveCycle(rig, trips, 2);
+ expect(trips.length).toBe(1);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a genuinely converged drain still unfreezes', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'ab-comparand-converge.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ driveCycle(rig, trips, 1);
+ expect(trips.length).toBe(1);
+
+ // A clean WYSIWYG edit: Observer A's Path-A write lands the canonical
+ // serialization into Y.Text, so the drain reaches a true raw-byte fixed
+ // point and the freeze lifts — the stricter comparand must not block
+ // legitimate recovery.
+ rig.editFragment('# Recovered\n\nwysiwyg edit converges the doc\n');
+ expect(rig.ytext.toString()).toContain('wysiwyg edit converges the doc');
+
+ rig.seedSource('# After\n\nsource edit re-derives after the unfreeze\n');
+ expect(rig.serializeFragment()).toContain('source edit re-derives after the unfreeze');
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/derive-pre-drain.test.ts b/packages/server/src/derive-pre-drain.test.ts
new file mode 100644
index 000000000..468fbdc3f
--- /dev/null
+++ b/packages/server/src/derive-pre-drain.test.ts
@@ -0,0 +1,214 @@
+/**
+ * Pre-drain paired-vector suite (H15) — the wired arms, on the REAL
+ * `setupServerObservers` drain + a real agent session.
+ *
+ * A pending WYSIWYG keystroke that provably does not overlap a paired op's
+ * target is flushed into Y.Text before the paired transact so it survives the
+ * derive; overlapping / unmodellable cases fall closed to the checkpoint floor.
+ */
+
+import { readFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { createBridgeDeriveLossReporter } from './bridge-loss-detector.ts';
+import { LossCaptureRing, lossCaptureCurrentPath, parseLossCaptureLines } from './loss-capture.ts';
+import {
+ createWiredPreDrainRig,
+ WIRED_PENDING_LINE,
+ WIRED_STALE_LINE,
+} from './pre-drain-wired.test-helper.ts';
+import { getPreDrainController } from './server-observers.ts';
+import { initShadowRepo, shadowGit } from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+describe('pre-drain paired-vector arms (H15)', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ test('CROSS-BLOCK undo: the pending keystroke survives in Y.Text and the re-derived fragment', async () => {
+ const rig = await createWiredPreDrainRig({ docName: 'cross-undo.md' });
+ try {
+ // An agent append in a different block creates the frame the undo reverts.
+ rig.agentWrite('Agent appended line.', 'append');
+ expect(rig.ytextString()).toContain('Agent appended line.');
+
+ // A pending keystroke lands inside the component, cross-block from the append.
+ rig.stageUnpropagatedKeystroke();
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(rig.ytextString()).not.toContain(WIRED_PENDING_LINE);
+
+ const undone = rig.agentUndo('last');
+
+ expect(undone).toBe(true);
+ // The keystroke survived into Y.Text AND the re-derived fragment...
+ expect(rig.ytextString()).toContain(WIRED_PENDING_LINE);
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ // ...and the agent op was still reverted.
+ expect(rig.ytextString()).not.toContain('Agent appended line.');
+ expect(rig.serializeFragment()).not.toContain('Agent appended line.');
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ test('CROSS-BLOCK agent append: the pending keystroke survives and the append lands', async () => {
+ const rig = await createWiredPreDrainRig({ docName: 'cross-append.md' });
+ try {
+ // A pending keystroke inside the component, cross-block from the append seam.
+ rig.stageUnpropagatedKeystroke();
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(rig.ytextString()).not.toContain(WIRED_PENDING_LINE);
+
+ rig.agentWriteWithPreDrain('A fresh agent paragraph.', 'append');
+
+ // The keystroke survived AND the agent's append applied.
+ expect(rig.ytextString()).toContain(WIRED_PENDING_LINE);
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(rig.ytextString()).toContain('A fresh agent paragraph.');
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ test('kill-switch OFF: the cross-block keystroke is NOT flushed (left for the floor)', async () => {
+ const rig = await createWiredPreDrainRig({
+ docName: 'kill-off.md',
+ setupOverrides: { preDrainEnabled: false },
+ });
+ try {
+ rig.agentWrite('Agent appended line.', 'append');
+ rig.stageUnpropagatedKeystroke();
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+
+ rig.agentUndo('last');
+
+ // Guard off: the derive rebuilt from stale Y.Text and dropped the keystroke.
+ expect(rig.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ expect(rig.serializeFragment()).not.toContain(WIRED_PENDING_LINE);
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ test('dirty-flag gating: a clean paired op short-circuits without a discriminator pass', async () => {
+ const rig = await createWiredPreDrainRig({ docName: 'clean-op.md' });
+ try {
+ // No pending content staged — the doc rests converged.
+ const controller = getPreDrainController(rig.doc);
+ expect(controller).toBeDefined();
+ const verdict = controller?.preDrain({
+ kind: 'agent-write',
+ composedBody: 'anything',
+ writeKind: 'append',
+ });
+ // The cheap gate fired: no un-propagated content, no serialize, no flush.
+ expect(verdict?.reason).toBe('skip-no-pending');
+ expect(verdict?.preDrain).toBe(false);
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ test('INERT on replace-intent: a whole-doc replace op declines and never flushes', async () => {
+ const rig = await createWiredPreDrainRig({ docName: 'replace-inert.md' });
+ try {
+ rig.stageUnpropagatedKeystroke();
+ const before = rig.ytextString();
+ expect(before).toContain(WIRED_STALE_LINE);
+ expect(before).not.toContain(WIRED_PENDING_LINE);
+
+ const verdict = getPreDrainController(rig.doc)?.preDrain({
+ kind: 'agent-write',
+ composedBody: '## Replaced\n\nBrand new body.\n',
+ writeKind: 'replace',
+ });
+
+ // A full overwrite launders everything, so pre-drain is inert — decline,
+ // and Y.Text is untouched (nothing flushed).
+ expect(verdict?.preDrain).toBe(false);
+ expect(rig.ytextString()).toBe(before);
+ expect(rig.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ test('NO-TARGET: an undo with an empty stack neither flushes nor throws', async () => {
+ const rig = await createWiredPreDrainRig({ docName: 'no-target.md' });
+ try {
+ rig.stageUnpropagatedKeystroke();
+ const before = rig.ytextString();
+
+ // No agent frame was created, so the undo stack is empty.
+ const undone = rig.agentUndo('last');
+
+ expect(undone).toBe(false);
+ // Nothing flushed and nothing crashed; the content is unchanged in Y.Text.
+ expect(rig.ytextString()).toBe(before);
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ test('SAME-BLOCK / overlap: a replace over the pending content checkpoints it byte-level, restorable', async () => {
+ const tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-pre-drain-floor-'));
+ const projectRoot = resolve(tmpDir, 'project');
+ const shadow = await initShadowRepo(projectRoot);
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+ const reporter = createBridgeDeriveLossReporter({
+ shadow: () => shadow,
+ ring,
+ getBranch: () => 'main',
+ contentRoot: '',
+ });
+ const rig = await createWiredPreDrainRig({ docName: 'overlap', reporter });
+ try {
+ rig.stageUnpropagatedKeystroke();
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+
+ // A whole-doc replace: pre-drain declines (overlap) and the paired-write
+ // floor captures the dropped fragment content.
+ rig.agentWriteWithPreDrain('## Replaced\n\nBrand new body.\n', 'replace');
+
+ // The floor's checkpoint lands async (real git in a microtask).
+ let trip: ReturnType<typeof parseLossCaptureLines>[number] | undefined;
+ for (let i = 0; i < 100 && !trip; i++) {
+ await ring.drain();
+ try {
+ const events = parseLossCaptureLines(
+ readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'),
+ );
+ trip = events.find((e) => e.event === 'detector-trip' && Boolean(e.checkpointSha));
+ } catch {
+ /* file may not exist yet */
+ }
+ if (!trip) await new Promise((r) => setTimeout(r, 10));
+ }
+ expect(trip).toBeDefined();
+ // Content-free ring event: a length + digest, never the bytes.
+ expect(typeof trip?.lostLen).toBe('number');
+ expect(JSON.stringify(trip)).not.toContain(WIRED_PENDING_LINE);
+
+ // The checkpoint payload is the pre-derive FRAGMENT-md (holds the keystroke).
+ const blob = (
+ await shadowGit(shadow).raw('show', `${trip?.checkpointSha}:overlap`)
+ ).toString();
+ expect(blob).toContain(WIRED_PENDING_LINE);
+
+ // Restore-reachable: the checkpoint surfaces as a history row.
+ const hist = await getDocumentHistory(shadow, { docName: 'overlap' }, '');
+ const row = hist.entries.find((e) => e.sha === trip?.checkpointSha);
+ expect(row?.checkpoint?.kind).toBe('bridge-derive-loss');
+ } finally {
+ await rig.cleanup();
+ await rm(tmpDir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/packages/server/src/derive-timing-exhaustion.test.ts b/packages/server/src/derive-timing-exhaustion.test.ts
new file mode 100644
index 000000000..427e9cfd4
--- /dev/null
+++ b/packages/server/src/derive-timing-exhaustion.test.ts
@@ -0,0 +1,248 @@
+/**
+ * Derive-timing defer exhaustion — the loud force-resolve at the drain-count
+ * bound, on the REAL `setupServerObservers` drain via the shared bridge-race rig.
+ *
+ * The defer guard keeps an un-propagated WYSIWYG keystroke alive by deferring
+ * the re-derive that would stomp it. Under sustained typing the freshness window
+ * never quiets, so Observer A never gets a drain to propagate the keystroke and
+ * the defer would repeat forever. This suite pins the bound: after
+ * `MAX_DERIVE_TIMING_DEFERS` deferrals the guard stops deferring and
+ * force-resolves LOUDLY — it checkpoints the pre-resolve fragment (which still
+ * holds the keystroke) and emits a distinguishable ring event carrying that
+ * checkpoint's sha, then lets the re-derive proceed. Never a silent clamp: the
+ * content leaves the live fragment but stays restorable through the timeline.
+ *
+ * The re-derive cadence interleaves defers with witness-settling early-exits, so
+ * a fixed drain count would be brittle; the suites drive drains until the guard
+ * force-resolves, under a ceiling comfortably above the ~15 drains a fresh doc
+ * needs — a real regression (force-resolve unreachable) fails fast at the cap.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import simpleGit from 'simple-git';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { type BridgeRaceRig, createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+import type { LossCaptureEventInput } from './loss-capture.ts';
+import { getMetrics } from './metrics.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+const PENDING_LINE = 'Step one body.';
+const STALE_LINE = 'Step one bod';
+const CONTENT_ROOT = 'content/docs';
+
+// Ceiling on drains driven while waiting for the force-resolve. The measured
+// worst case on a fresh doc is ~15 drains; this leaves headroom for the
+// defer/early-exit cadence to vary while still failing fast if force-resolve
+// ever becomes unreachable.
+const MAX_DRAINS = 30;
+
+/**
+ * Leave the fragment holding the pending `PENDING_LINE` while Y.Text still holds
+ * `STALE_LINE`, with the settlement witnesses stale — the un-propagated-keystroke
+ * shape whose re-derive the guard defers. Mirrors the H2 stomp suite's staging.
+ */
+function stageUnpropagatedKeystroke(rig: BridgeRaceRig): void {
+ rig.editFragment(GEN1);
+ rig.settle(1);
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing.\n'));
+ rig.echoFragmentEdit(rig.ytext.toString(), STALE_LINE, PENDING_LINE, {
+ advanceFreshness: false,
+ });
+}
+
+/** A source-editor / non-paired Y.Text write, freshness held hot (sustained typing). */
+function sourceWrite(rig: BridgeRaceRig, text: string): void {
+ rig.externalYtextEdit('source-write', (yt) => yt.insert(yt.length, `\n${text}\n`), {
+ advanceFreshness: false,
+ });
+}
+
+describe('derive-timing defer exhaustion (H2 exhaustion arm)', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ test('sustained deferral preserves the keystroke until the guard force-resolves loudly', () => {
+ const recorded: LossCaptureEventInput[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'exhaustion-bound.md',
+ setupOverrides: {
+ lossRing: {
+ record: async (input) => {
+ recorded.push(input);
+ },
+ },
+ },
+ });
+ const before = getMetrics().deriveTimingDeferForceResolved;
+ try {
+ stageUnpropagatedKeystroke(rig);
+
+ let forced = false;
+ for (let i = 0; i < MAX_DRAINS && !forced; i++) {
+ // The keystroke survives every drain up to (and including) the one that
+ // force-resolves — it is only ever dropped by the loud path, never by a
+ // silent defer that lost it.
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+ sourceWrite(rig, `trailing-${i}`);
+ forced = getMetrics().deriveTimingDeferForceResolved > before;
+ }
+
+ expect(forced).toBe(true);
+ // Force-resolve rebuilt the fragment from Y.Text, so the pending content
+ // left the live fragment (the checkpoint below keeps it restorable).
+ expect(rig.serializeFragment()).not.toContain(PENDING_LINE);
+ expect(getMetrics().deriveTimingDeferForceResolved).toBe(before + 1);
+
+ // Loud, not a quiet clamp: a distinguishable, content-free ring event fired.
+ const evt = recorded.find(
+ (e) => e.event === 'checkpoint-write' && e.site === 'derive-timing-exhaustion',
+ );
+ expect(evt).toBeDefined();
+ expect(evt?.direction).toBe('b');
+ expect(typeof evt?.lostLen).toBe('number');
+ expect(JSON.stringify(evt)).not.toContain(PENDING_LINE);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a deferring doc reaches the bound through pure drains under a frozen clock', () => {
+ const rig = createBridgeRaceRig({ docName: 'exhaustion-quiescent.md' });
+ const before = getMetrics().deriveTimingDeferForceResolved;
+ try {
+ stageUnpropagatedKeystroke(rig);
+ // One source write starts the deferring state; after that, no further
+ // content — only ambient settlement drains, with the clock never advanced.
+ sourceWrite(rig, 'kick');
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+
+ let forced = false;
+ for (let i = 0; i < MAX_DRAINS && !forced; i++) {
+ rig.forceARound({ advanceFreshness: false });
+ forced = getMetrics().deriveTimingDeferForceResolved > before;
+ }
+
+ // The bound was reached by drain count alone — the clock stayed frozen, so
+ // a wall-clock bound could never have tripped.
+ expect(forced).toBe(true);
+ expect(rig.serializeFragment()).not.toContain(PENDING_LINE);
+ expect(getMetrics().deriveTimingDeferForceResolved).toBe(before + 1);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('with the guard off nothing defers, so the exhaustion path never fires', () => {
+ const rig = createBridgeRaceRig({
+ docName: 'exhaustion-guard-off.md',
+ setupOverrides: { deferGuardEnabled: false },
+ });
+ const before = getMetrics().deriveTimingDeferForceResolved;
+ try {
+ stageUnpropagatedKeystroke(rig);
+ // With no defer, the first drain stomps the keystroke outright — there is
+ // nothing to accumulate toward the bound.
+ for (let i = 0; i < MAX_DRAINS; i++) sourceWrite(rig, `x-${i}`);
+ expect(rig.serializeFragment()).not.toContain(PENDING_LINE);
+ expect(getMetrics().deriveTimingDeferForceResolved).toBe(before);
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
+
+describe('derive-timing defer exhaustion — checkpoint floor', () => {
+ let tmpDir: string;
+
+ beforeEach(async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-defer-exhaustion-'));
+ });
+ afterEach(async () => {
+ vi.useRealTimers();
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ async function setupShadow(): Promise<{ shadow: ShadowHandle }> {
+ const projectRoot = resolve(tmpDir, 'project');
+ const contentDir = resolve(projectRoot, CONTENT_ROOT);
+ mkdirSync(contentDir, { recursive: true });
+ const git = simpleGit(projectRoot);
+ await git.init();
+ await git.raw('config', 'user.name', 'Test');
+ await git.raw('config', 'user.email', '[email protected]');
+ writeFileSync(resolve(contentDir, 'exhaustion.md'), '# Seed\n');
+ await git.add('.');
+ await git.commit('Initial commit');
+ return { shadow: await initShadowRepo(projectRoot) };
+ }
+
+ test('force-resolve writes a resolvable defer-exhaustion-loss checkpoint holding the pre-resolve fragment', async () => {
+ const { shadow } = await setupShadow();
+ const recorded: LossCaptureEventInput[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'exhaustion',
+ setupOverrides: {
+ shadow: () => shadow,
+ getBranch: () => 'main',
+ contentRoot: CONTENT_ROOT,
+ lossRing: {
+ record: async (input) => {
+ recorded.push(input);
+ },
+ },
+ },
+ });
+ const before = getMetrics().deriveTimingDeferForceResolved;
+ try {
+ stageUnpropagatedKeystroke(rig);
+ for (let i = 0; i < MAX_DRAINS; i++) {
+ sourceWrite(rig, `t-${i}`);
+ if (getMetrics().deriveTimingDeferForceResolved > before) break;
+ }
+
+ // The checkpoint is written fire-and-forget (queueMicrotask + real git);
+ // the ring event fires from inside its `then`, so waiting for the sha-
+ // bearing event is waiting for the checkpoint to have landed.
+ await vi.waitFor(() =>
+ expect(
+ recorded.some(
+ (e) => e.event === 'checkpoint-write' && typeof e.checkpointSha === 'string',
+ ),
+ ).toBe(true),
+ );
+
+ const evt = recorded.find(
+ (e) => e.event === 'checkpoint-write' && e.site === 'derive-timing-exhaustion',
+ );
+ const sha = evt?.checkpointSha;
+ expect(sha).toMatch(/^[0-9a-f]{40}$/);
+
+ // The sha resolves against the checkpoint store as a defer-exhaustion-loss row.
+ const hist = await getDocumentHistory(shadow, { docName: 'exhaustion' }, CONTENT_ROOT);
+ const row = hist.entries.find((e) => e.sha === sha);
+ expect(row?.type).toBe('checkpoint');
+ expect(row?.checkpoint?.kind).toBe('defer-exhaustion-loss');
+
+ // The checkpoint holds the pre-resolve FRAGMENT serialization — the payload
+ // that still carries the un-propagated keystroke a Y.Text payload would miss.
+ const content = (
+ await shadowGit(shadow).raw('show', `${sha}:${CONTENT_ROOT}/exhaustion`)
+ ).toString();
+ expect(content).toContain(PENDING_LINE);
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/derive-timing-guard.test.ts b/packages/server/src/derive-timing-guard.test.ts
new file mode 100644
index 000000000..24650ed6b
--- /dev/null
+++ b/packages/server/src/derive-timing-guard.test.ts
@@ -0,0 +1,245 @@
+/**
+ * Derive-timing defer guard — the stomp suite, on the REAL
+ * `setupServerObservers` drain via the shared bridge-race rig.
+ *
+ * The loss class: a WYSIWYG keystroke advances a component's children past its
+ * stamped `sourceRaw`, and a freshness-suppressed Observer A settles that drain
+ * with stale witnesses, leaving the fragment holding the keystroke while Y.Text
+ * lacks it. A subsequent source-editor / non-paired Y.Text write then triggers
+ * an Observer B re-derive that rebuilds the fragment from Y.Text and silently
+ * discards the keystroke. The guard checks, before rebuilding, whether the
+ * fragment holds a line neither Y.Text nor the last convergence had, and defers
+ * the re-derive when it does — so the keystroke survives and converges once
+ * freshness quiesces, instead of being stomped.
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { type BridgeRaceRig, createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+import type { LossCaptureEventInput } from './loss-capture.ts';
+
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+const PENDING_LINE = 'Step one body.';
+const STALE_LINE = 'Step one bod';
+
+/**
+ * Leave the fragment holding the pending `PENDING_LINE` while Y.Text still holds
+ * `STALE_LINE`, with the settlement witnesses stale — the un-propagated-keystroke
+ * shape a drain-shaped re-derive would stomp.
+ */
+function stageUnpropagatedKeystroke(rig: BridgeRaceRig): void {
+ rig.editFragment(GEN1);
+ rig.settle(1);
+ // Reset the freshness-quiescence clock so the echo drain runs suppressed.
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing.\n'));
+ rig.echoFragmentEdit(rig.ytext.toString(), STALE_LINE, PENDING_LINE, {
+ advanceFreshness: false,
+ });
+}
+
+/** A source-editor / non-paired Y.Text write that triggers an Observer B re-derive. */
+function sourceWrite(rig: BridgeRaceRig, text: string): void {
+ rig.externalYtextEdit('source-write', (yt) => yt.insert(yt.length, `\n${text}\n`), {
+ advanceFreshness: false,
+ });
+}
+
+describe('derive-timing defer guard (H2)', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ test('an un-propagated WYSIWYG keystroke survives a drain-shaped re-derive', () => {
+ const rig = createBridgeRaceRig({ docName: 'defer-survives.md' });
+ try {
+ stageUnpropagatedKeystroke(rig);
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+
+ sourceWrite(rig, 'Another source line.');
+
+ // The re-derive deferred: the keystroke is still in the fragment.
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('with the guard OFF the same drain stomps the keystroke', () => {
+ const rig = createBridgeRaceRig({
+ docName: 'defer-off.md',
+ setupOverrides: { deferGuardEnabled: false },
+ });
+ try {
+ stageUnpropagatedKeystroke(rig);
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+
+ sourceWrite(rig, 'Another source line.');
+
+ // No guard: the re-derive rebuilt the fragment from stale Y.Text.
+ expect(rig.serializeFragment()).not.toContain(PENDING_LINE);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('the guard is default-ON (no explicit flag)', () => {
+ const rig = createBridgeRaceRig({ docName: 'defer-default.md' });
+ try {
+ stageUnpropagatedKeystroke(rig);
+ sourceWrite(rig, 'Another source line.');
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('continued WYSIWYG typing carries the deferred keystroke into Y.Text', () => {
+ const rig = createBridgeRaceRig({ docName: 'defer-converge.md' });
+ try {
+ stageUnpropagatedKeystroke(rig);
+ sourceWrite(rig, 'Another source line.');
+ expect(rig.ytext.toString()).not.toContain(PENDING_LINE);
+
+ // The user keeps typing in the WYSIWYG: a real fragment write, in a block
+ // away from the deferred keystroke, on a freshness-safe drain. The defer
+ // left Y.Text past the raw witness, so Observer A routes this through the
+ // Path-B three-way merge — which is what has to carry BOTH sides.
+ const typed = rig.serializeFragment().replace('Intro paragraph.', 'Intro paragraph typed.');
+ expect(typed).toContain(PENDING_LINE);
+ rig.editFragment(typed);
+
+ // The fragment's un-propagated keystroke and the freshly typed text both
+ // reached Y.Text, and the merge did not drop the Y.Text-side source line.
+ expect(rig.ytext.toString()).toContain(PENDING_LINE);
+ expect(rig.ytext.toString()).toContain('Intro paragraph typed.');
+ expect(rig.ytext.toString()).toContain('Another source line.');
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a pure source-editor write near a component does not defer', () => {
+ let deferCount = 0;
+ const rig = createBridgeRaceRig({
+ docName: 'no-false-defer-source.md',
+ setupOverrides: {
+ onDeriveTimingDefer: () => {
+ deferCount += 1;
+ },
+ },
+ });
+ try {
+ // Converge GEN1 cleanly (fragment and Y.Text agree, no pending content).
+ rig.editFragment(GEN1);
+ rig.settle(2);
+ expect(rig.ytext.toString()).toContain(STALE_LINE);
+ // Pure source edit: no fragment change, no pending content.
+ sourceWrite(rig, 'New source paragraph.');
+ // The re-derive ran (pulled the edit into the fragment); it did not defer.
+ expect(rig.serializeFragment()).toContain('New source paragraph.');
+ expect(deferCount).toBe(0);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a Y.Text-only residual (fragment holds less) does not defer', () => {
+ let deferCount = 0;
+ const rig = createBridgeRaceRig({
+ docName: 'no-false-defer-ytext.md',
+ setupOverrides: {
+ onDeriveTimingDefer: () => {
+ deferCount += 1;
+ },
+ },
+ });
+ try {
+ rig.seedSource('# Title\n\nAlpha paragraph.\n');
+ rig.settle(1);
+ // Y.Text gains a line the fragment lacks (fragment holds LESS) — the
+ // re-derive must run to absorb it, never defer.
+ sourceWrite(rig, 'Beta paragraph.');
+ expect(rig.serializeFragment()).toContain('Beta paragraph.');
+ expect(deferCount).toBe(0);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a deferring drain does not move the settlement witnesses', () => {
+ const snapshots: Array<{ canonicalWitness: string; rawWitness: string }> = [];
+ const rig = createBridgeRaceRig({
+ docName: 'defer-atomicity.md',
+ setupOverrides: {
+ onDeriveTimingDefer: (s) => snapshots.push(s),
+ },
+ });
+ try {
+ stageUnpropagatedKeystroke(rig);
+ // Two in-window source writes each trigger a defer; the witnesses must be
+ // byte-identical across both (a deferring drain is not a settlement).
+ sourceWrite(rig, 'First trailing.');
+ sourceWrite(rig, 'Second trailing.');
+ expect(snapshots.length).toBeGreaterThanOrEqual(2);
+ expect(snapshots[1]?.canonicalWitness).toBe(snapshots[0]?.canonicalWitness);
+ expect(snapshots[1]?.rawWitness).toBe(snapshots[0]?.rawWitness);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('each defer records a distinguishable guard-defer loss-ring event', () => {
+ const recorded: LossCaptureEventInput[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'defer-ring.md',
+ setupOverrides: {
+ lossRing: {
+ record: async (input) => {
+ recorded.push(input);
+ },
+ },
+ },
+ });
+ try {
+ stageUnpropagatedKeystroke(rig);
+ sourceWrite(rig, 'Another source line.');
+ expect(recorded.length).toBeGreaterThanOrEqual(1);
+ const evt = recorded[0];
+ expect(evt?.event).toBe('guard-defer');
+ expect(evt?.docName).toBe('defer-ring.md');
+ expect(evt?.direction).toBe('b');
+ // Content-free: only a byte length is carried, never the bytes.
+ expect(typeof evt?.lostLen).toBe('number');
+ expect(JSON.stringify(evt)).not.toContain(PENDING_LINE);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a Y.Text-ahead divergence re-derives (does not defer) — direction-aware', () => {
+ let deferCount = 0;
+ const rig = createBridgeRaceRig({
+ docName: 'direction-aware.md',
+ setupOverrides: {
+ onDeriveTimingDefer: () => {
+ deferCount += 1;
+ },
+ },
+ });
+ try {
+ rig.editFragment(GEN1);
+ rig.settle(2);
+ // Y.Text diverges ahead of the fragment (a source-mode edit that adds
+ // content the fragment lacks). Observer B must re-derive to pull it in.
+ sourceWrite(rig, 'Divergent source content.');
+ expect(rig.serializeFragment()).toContain('Divergent source content.');
+ expect(deferCount).toBe(0);
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/disk-content-intake.ts b/packages/server/src/disk-content-intake.ts
index 98622ee56..f9a0cdf9c 100644
--- a/packages/server/src/disk-content-intake.ts
+++ b/packages/server/src/disk-content-intake.ts
@@ -1,5 +1,6 @@
import type * as Y from 'yjs';
import { composeAndWriteRawBody } from './bridge-intake.ts';
+import type { DeriveLossDetectOptions } from './bridge-loss-detector.ts';
import type { PairedWriteOrigin } from './server-observers.ts';
/**
@@ -16,6 +17,11 @@ export const FILE_WATCHER_ORIGIN = {
/**
* Apply raw disk bytes through the shared paired-write primitive. The caller
* owns the outer `document.transact(..., FILE_WATCHER_ORIGIN)` boundary.
+ *
+ * `detect` opts this write into paired-intake derive-loss detection. Omitting
+ * it leaves the write serialize-free, which is why the persistence and
+ * managed-artifact callers pass nothing: they re-apply bytes the fragment is
+ * already derived from, so there is no un-propagated editor content to lose.
*/
export function applyDiskContentToDoc(
document: Y.Doc,
@@ -23,8 +29,9 @@ export function applyDiskContentToDoc(
resolveEmbed?: (basename: string, sourcePath: string) => string | null,
sourcePath?: string,
resolveSize?: (basename: string, sourcePath: string) => number | null,
+ detect?: DeriveLossDetectOptions,
): void {
const embedResolver =
resolveEmbed && sourcePath ? { resolveEmbed, resolveSize, sourcePath } : undefined;
- composeAndWriteRawBody(document, content, 'file-watcher', embedResolver);
+ composeAndWriteRawBody(document, content, 'file-watcher', embedResolver, undefined, detect);
}
diff --git a/packages/server/src/doc-extensions.ts b/packages/server/src/doc-extensions.ts
index 9c692d43f..9f09039b9 100644
--- a/packages/server/src/doc-extensions.ts
+++ b/packages/server/src/doc-extensions.ts
@@ -176,6 +176,30 @@ export function docNameToRelativePath(docName: string): string {
: `${docName}${getDocExtension(docName)}`;
}
+/**
+ * The extension-less twin of a resolved content-tree path.
+ *
+ * Full-tree checkpoints (Save Version, auto-consolidation, pre-rollback) store
+ * a doc's blob at the extension-full disk path (`<root>/foo.md`). The silent
+ * single-blob checkpoint trees `saveInMemoryCheckpoint` writes instead store it
+ * at the extension-LESS docName path (`<root>/foo`), because the Hocuspocus doc
+ * name that flows through the CRDT layer is already extension-less. A restore
+ * probe therefore has to try both shapes.
+ *
+ * Returns the path with `getDocExtension(docName)` stripped, or null when the
+ * path does not carry that appended extension (managed-artifact `.ok/...` keys
+ * and mermaid docNames already hold their own suffix — those are full-tree only
+ * and have no extension-less twin).
+ */
+export function extensionlessDocTreePath(fullPath: string, docName: string): string | null {
+ const ext = getDocExtension(docName);
+ if (ext.length > 0 && fullPath.endsWith(ext)) {
+ const stripped = fullPath.slice(0, -ext.length);
+ if (stripped.length > 0 && stripped !== fullPath) return stripped;
+ }
+ return null;
+}
+
/** Clear the recorded extension for a docName (e.g. on file delete). */
export function forgetDocExtension(docName: string): void {
docExtensionByName.delete(docName);
diff --git a/packages/server/src/external-change.ts b/packages/server/src/external-change.ts
index 87ba406f4..7e4a6f802 100644
--- a/packages/server/src/external-change.ts
+++ b/packages/server/src/external-change.ts
@@ -16,6 +16,12 @@ import {
stripFrontmatter,
} from '@inkeep/open-knowledge-core';
import { formatReconcileSubject } from '@inkeep/open-knowledge-core/shadow-repo-layout';
+import {
+ type BridgeDeriveLossReporter,
+ DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE,
+ type DeriveLossDetectOptions,
+} from './bridge-loss-detector.ts';
+import { shouldRunPairedIntakeDetection } from './bridge-loss-suppression.ts';
import { isConfigDoc, isMermaidDoc, isSystemDoc } from './cc1-broadcast.ts';
import { isDocInConflict } from './conflict-errors.ts';
import { isWithinContentDir, safeContentPath } from './content-path.ts';
@@ -70,6 +76,7 @@ export function applyExternalChange(
content: string,
resolveEmbed?: (basename: string, sourcePath: string) => string | null,
resolveSize?: (basename: string, sourcePath: string) => number | null,
+ bridgeLossReporter?: BridgeDeriveLossReporter,
): void {
if (isSystemDoc(docName) || isConfigDoc(docName) || isMermaidDoc(docName)) return;
const document = hocuspocus.documents.get(docName);
@@ -95,12 +102,33 @@ export function applyExternalChange(
const priorFm = stripFrontmatter(currentSource).frontmatter;
const { frontmatter: nextFm } = stripFrontmatter(content);
+ // A dirty OPEN doc (fragment holds un-propagated WYSIWYG content) is about to
+ // have that content rebuilt over by the disk bytes — a silent loss vector.
+ // Wire the paired-intake derive-loss detector when a reporter is present and
+ // the file-watcher origin is classified `detect`; the pre-write Y.Text is the
+ // baseline so a disk edit that legitimately replaces propagated content never
+ // trips, only never-propagated fragment content does. Off (no reporter) leaves
+ // the write serialize-free.
+ const detect: DeriveLossDetectOptions | undefined =
+ bridgeLossReporter && shouldRunPairedIntakeDetection(FILE_WATCHER_ORIGIN.context.origin)
+ ? {
+ report: (obs) =>
+ bridgeLossReporter(
+ docName,
+ obs,
+ FILE_SYSTEM_WRITER.id,
+ DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE,
+ ),
+ baselineFullMd: currentSource,
+ }
+ : undefined;
+
// Caller wraps for atomicity + paired-write FILE_WATCHER_ORIGIN identity
// (precedent #24). The transact moved out of applyDiskContentToDoc so the
// per-surface origin reaches observer guards.
try {
document.transact(() => {
- applyDiskContentToDoc(document, content, resolveEmbed, docName, resolveSize);
+ applyDiskContentToDoc(document, content, resolveEmbed, docName, resolveSize, detect);
}, FILE_WATCHER_ORIGIN);
} catch (err) {
// Yjs transactions don't roll back on throw — `applyFastDiff` may have
@@ -169,10 +197,19 @@ export function createExternalChangeHandler(
hocuspocus: Hocuspocus,
resolveEmbed?: (basename: string, sourcePath: string) => string | null,
resolveSize?: (basename: string, sourcePath: string) => number | null,
+ bridgeLossReporter?: BridgeDeriveLossReporter,
): (docName: string, content: string) => Promise<void> {
return async (docName: string, content: string): Promise<void> => {
try {
- applyExternalChange(durabilityState, hocuspocus, docName, content, resolveEmbed, resolveSize);
+ applyExternalChange(
+ durabilityState,
+ hocuspocus,
+ docName,
+ content,
+ resolveEmbed,
+ resolveSize,
+ bridgeLossReporter,
+ );
getLogger('file-watcher').info({ docName }, 'applied external change');
} catch (err) {
if (
@@ -303,6 +340,13 @@ export function reconcileDiskBeforeAgentWrite(
docName: string,
contentDir: string,
resolveEmbed?: (basename: string, sourcePath: string) => string | null,
+ /**
+ * Paired-intake derive-loss reporter, forwarded to the `applyExternalChange`
+ * ingest below. This is the dirty-open-doc watcher positive on the HOTTEST
+ * intake path — every agent content write reconciles through here — so it
+ * carries the same `detect` wiring the file-watcher's own handler does.
+ */
+ bridgeLossReporter?: BridgeDeriveLossReporter,
): ReconcileBeforeWriteResult {
if (isSystemDoc(docName) || isConfigDoc(docName) || isMermaidDoc(docName)) return NOT_RECONCILED;
@@ -443,7 +487,15 @@ export function reconcileDiskBeforeAgentWrite(
// FILE_WATCHER_ORIGIN transact and advances reconciledBase
// synchronously.
const ingest = outcome.kind === 'clean' ? diskContent : outcome.newContent;
- applyExternalChange(durabilityState, hocuspocus, docName, ingest, resolveEmbed);
+ applyExternalChange(
+ durabilityState,
+ hocuspocus,
+ docName,
+ ingest,
+ resolveEmbed,
+ undefined,
+ bridgeLossReporter,
+ );
if (outcome.kind === 'merged') {
// The base must track the DISK bytes, not the memory-only merged
// content: the L3 store backstop and the watcher's queued event for
diff --git a/packages/server/src/loss-capture.test.ts b/packages/server/src/loss-capture.test.ts
new file mode 100644
index 000000000..014ac76e4
--- /dev/null
+++ b/packages/server/src/loss-capture.test.ts
@@ -0,0 +1,237 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+ LOSS_CAPTURE_SCHEMA_VERSION,
+ LOSS_EVENT_BACKSTOP_TRIP,
+ LOSS_EVENT_CHECKPOINT_WRITE,
+ LOSS_EVENT_DETECTOR_TRIP,
+ LOSS_EVENT_GUARD_DEFER,
+ LOSS_EVENT_KINDS,
+ LOSS_EVENT_PERSISTENCE_HOLD,
+ type LossCaptureEvent,
+ LossCaptureEventSchema,
+ LossCaptureRing,
+ lossCaptureCurrentPath,
+ lossCapturePreviousPath,
+ parseLossCaptureLines,
+} from './loss-capture.ts';
+
+// The real RotatingAppender writes to disk with raw fs; every test gets its own
+// tmpdir so runs are hermetic and parallel-safe. No mocks — the ring is
+// exercised against the production appender exactly as it runs in the server.
+let projectDir: string;
+
+beforeEach(() => {
+ projectDir = mkdtempSync(join(tmpdir(), 'ok-loss-capture-'));
+});
+
+afterEach(() => {
+ rmSync(projectDir, { recursive: true, force: true });
+});
+
+/** Read + parse whichever generation files exist, oldest generation first. */
+function readAllRetained(): LossCaptureEvent[] {
+ const prevPath = lossCapturePreviousPath(projectDir);
+ const currentPath = lossCaptureCurrentPath(projectDir);
+ const events: LossCaptureEvent[] = [];
+ if (existsSync(prevPath)) {
+ events.push(...parseLossCaptureLines(readFileSync(prevPath, 'utf-8')));
+ }
+ if (existsSync(currentPath)) {
+ events.push(...parseLossCaptureLines(readFileSync(currentPath, 'utf-8')));
+ }
+ return events;
+}
+
+describe('LossCaptureRing.record', () => {
+ it('writes a content-free event line under .ok/local/loss-capture/', async () => {
+ const ring = new LossCaptureRing({ projectDir, maxBytes: 1_000_000, now: () => 4242 });
+ await ring.record({
+ event: LOSS_EVENT_GUARD_DEFER,
+ docName: 'notes/plan',
+ writerId: null,
+ site: 'site-2',
+ lostLen: 12,
+ digest: 'deadbeef',
+ });
+ await ring.drain();
+
+ const currentPath = lossCaptureCurrentPath(projectDir);
+ expect(currentPath.endsWith(join('.ok', 'local', 'loss-capture', 'loss-current.jsonl'))).toBe(
+ true,
+ );
+ expect(existsSync(currentPath)).toBe(true);
+
+ const events = parseLossCaptureLines(readFileSync(currentPath, 'utf-8'));
+ expect(events).toEqual([
+ {
+ ts: 4242,
+ schemaVersion: LOSS_CAPTURE_SCHEMA_VERSION,
+ seq: 1,
+ event: LOSS_EVENT_GUARD_DEFER,
+ docName: 'notes/plan',
+ writerId: null,
+ site: 'site-2',
+ lostLen: 12,
+ digest: 'deadbeef',
+ },
+ ]);
+ });
+
+ it('produces one distinguishable kind per loss-class mechanism', async () => {
+ // The kinds must never alias — a bundle reader distinguishes a deferred
+ // re-derive from a tripped detector/backstop from a written checkpoint from
+ // a tolerated persistence hold by this field alone.
+ expect(new Set(LOSS_EVENT_KINDS).size).toBe(5);
+
+ const ring = new LossCaptureRing({ projectDir, maxBytes: 1_000_000, now: () => 1 });
+ for (const kind of LOSS_EVENT_KINDS) {
+ await ring.record({ event: kind, docName: 'd', writerId: null });
+ }
+ await ring.drain();
+
+ const kinds = readAllRetained().map((e) => e.event);
+ expect(kinds).toEqual([
+ LOSS_EVENT_GUARD_DEFER,
+ LOSS_EVENT_DETECTOR_TRIP,
+ LOSS_EVENT_BACKSTOP_TRIP,
+ LOSS_EVENT_CHECKPOINT_WRITE,
+ LOSS_EVENT_PERSISTENCE_HOLD,
+ ]);
+ expect(new Set(kinds).size).toBe(5);
+ });
+
+ it('keeps the newest events when the file rotates at its cap', async () => {
+ // A small cap forces several rotations. The two-generation ring drops the
+ // OLDEST events; the newest must always survive.
+ const ring = new LossCaptureRing({ projectDir, maxBytes: 400, now: () => 7 });
+ const total = 24;
+ for (let i = 0; i < total; i++) {
+ await ring.record({ event: LOSS_EVENT_GUARD_DEFER, docName: 'doc', writerId: null });
+ }
+ await ring.drain();
+
+ // Rotation actually happened (a previous generation exists).
+ expect(existsSync(lossCapturePreviousPath(projectDir))).toBe(true);
+
+ const retained = readAllRetained();
+ const seqs = retained.map((e) => e.seq);
+ // Newest event is present; oldest were dropped (footprint bounded).
+ expect(Math.max(...seqs)).toBe(total);
+ expect(retained.length).toBeLessThan(total);
+ expect(retained.length).toBeGreaterThan(0);
+ });
+
+ it('keeps per-doc counters monotonic across rotation, independent per doc', async () => {
+ const ring = new LossCaptureRing({ projectDir, maxBytes: 400, now: () => 9 });
+ const perDoc = 20;
+ for (let i = 0; i < perDoc; i++) {
+ await ring.record({ event: LOSS_EVENT_DETECTOR_TRIP, docName: 'alpha', writerId: null });
+ await ring.record({ event: LOSS_EVENT_DETECTOR_TRIP, docName: 'beta', writerId: null });
+ }
+ await ring.drain();
+ expect(existsSync(lossCapturePreviousPath(projectDir))).toBe(true);
+
+ const retained = readAllRetained();
+ for (const docName of ['alpha', 'beta']) {
+ const seqs = retained.filter((e) => e.docName === docName).map((e) => e.seq);
+ expect(seqs.length).toBeGreaterThan(0);
+ // Strictly increasing across the retained window: a reset (restart at 1)
+ // after rotation would show a decrease, so this pins "no reset".
+ for (let i = 1; i < seqs.length; i++) {
+ expect(seqs[i]).toBeGreaterThan(seqs[i - 1] as number);
+ }
+ // The counter counted every event for this doc — it never reset to the
+ // file's contents, so its max equals the number recorded.
+ expect(Math.max(...seqs)).toBe(perDoc);
+ }
+ });
+});
+
+describe('LossCaptureEventSchema (content-free BY SCHEMA)', () => {
+ it('declares exactly the shape+correlation fields — no content field can exist', () => {
+ const keys = Object.keys(LossCaptureEventSchema.shape).sort();
+ expect(keys).toEqual([
+ 'checkpointSha',
+ 'digest',
+ 'direction',
+ 'docName',
+ 'event',
+ 'lostLen',
+ 'schemaVersion',
+ 'seq',
+ 'site',
+ 'ts',
+ 'writerId',
+ ]);
+ // Belt-and-suspenders: none of the fields is a content-bearing name. The
+ // exact key set above is the real guard (adding any field fails this test);
+ // this names the class the schema must never carry.
+ const contentShaped = [
+ 'content',
+ 'body',
+ 'text',
+ 'preview',
+ 'snippet',
+ 'payload',
+ 'lostContent',
+ 'value',
+ 'raw',
+ 'bytes',
+ ];
+ expect(keys.filter((k) => contentShaped.includes(k))).toEqual([]);
+ });
+
+ it('round-trips serialize -> parse -> deep-equal', () => {
+ const event: LossCaptureEvent = {
+ ts: 1234,
+ schemaVersion: LOSS_CAPTURE_SCHEMA_VERSION,
+ seq: 3,
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName: 'projects/roadmap',
+ writerId: 'agent-7',
+ direction: 'B',
+ lostLen: 88,
+ digest: 'abc123',
+ checkpointSha: 'f00dcafe',
+ };
+ const roundTripped = LossCaptureEventSchema.parse(JSON.parse(JSON.stringify(event)));
+ expect(roundTripped).toEqual(event);
+ });
+
+ it('tolerates a newer-schema row with an unknown kind (forward-compat)', () => {
+ // A reader on schema version N must not choke on a row a future version
+ // wrote: an unrecognized `event` kind is preserved, and an unknown extra
+ // field is dropped rather than rejected.
+ const futureRow = JSON.stringify({
+ ts: 500,
+ schemaVersion: LOSS_CAPTURE_SCHEMA_VERSION + 1,
+ seq: 1,
+ event: 'some-future-kind',
+ docName: 'd',
+ writerId: null,
+ someFutureField: { nested: true },
+ });
+ const events = parseLossCaptureLines(futureRow);
+ expect(events).toHaveLength(1);
+ expect(events[0]?.event).toBe('some-future-kind');
+ expect(events[0]?.schemaVersion).toBe(LOSS_CAPTURE_SCHEMA_VERSION + 1);
+ expect(events[0]).not.toHaveProperty('someFutureField');
+ });
+
+ it('skips a malformed trailing line (SIGKILL-partial tolerance)', () => {
+ const good = JSON.stringify({
+ ts: 1,
+ schemaVersion: LOSS_CAPTURE_SCHEMA_VERSION,
+ seq: 1,
+ event: LOSS_EVENT_GUARD_DEFER,
+ docName: 'd',
+ writerId: null,
+ });
+ const events = parseLossCaptureLines(`${good}\n{"ts":2,"schemaVersio`);
+ expect(events).toHaveLength(1);
+ expect(events[0]?.seq).toBe(1);
+ });
+});
diff --git a/packages/server/src/loss-capture.ts b/packages/server/src/loss-capture.ts
new file mode 100644
index 000000000..dbd347879
--- /dev/null
+++ b/packages/server/src/loss-capture.ts
@@ -0,0 +1,213 @@
+/**
+ * Content-free local ring for bridge loss-class events.
+ *
+ * Every event that a loss-class mechanism produces — a deferred re-derive, a
+ * tripped post-condition detector, a tripped re-derive backstop, a written
+ * recovery checkpoint — lands here as one line of JSON under
+ * `<projectDir>/.ok/local/loss-capture/loss-current.jsonl`. The ring rides the
+ * shared two-generation `RotatingAppender` at its own cap so it never competes
+ * with the larger telemetry span / server-log rings; `ok diagnose bundle`
+ * stages it at the Detailed-diagnostics tier so a bug bundle carries loss
+ * signal without a live repro.
+ *
+ * The event carries shape + correlation only: a byte length and a
+ * caller-supplied digest, never the lost bytes themselves. Content-free is a
+ * property of the SCHEMA, not a runtime scrub — `record()` has no channel that
+ * accepts document content, so no content can flow in. The producer computes
+ * any digest before it reaches the ring.
+ */
+
+import { join } from 'node:path';
+import { z } from 'zod';
+import { getLogger } from './logger.ts';
+import { RotatingAppender } from './telemetry-file-sink.ts';
+
+const log = getLogger('loss-capture');
+
+/**
+ * Bumped only when the on-disk event shape changes in a way older readers must
+ * be told about. Readers tolerate a higher value on a row (see
+ * {@link parseLossCaptureLines}) — the field exists so a future migration can
+ * branch on it, not so a mismatch is rejected.
+ */
+export const LOSS_CAPTURE_SCHEMA_VERSION = 1;
+
+// Distinguishable loss-class event kinds — the field-metric vocabulary a bug
+// bundle (and opt-in OTel) reports against. Producers emit these constants; the
+// read schema keeps `event` open (`z.string()`) so a reader tolerates a row
+// whose kind a newer version introduced. Extending the vocabulary is a
+// deliberate one-line edit here, never an accident at a call site.
+export const LOSS_EVENT_GUARD_DEFER = 'guard-defer';
+export const LOSS_EVENT_DETECTOR_TRIP = 'detector-trip';
+export const LOSS_EVENT_BACKSTOP_TRIP = 'backstop-trip';
+export const LOSS_EVENT_CHECKPOINT_WRITE = 'checkpoint-write';
+// Persistence declined to rebuild the fragment because the whole divergence was
+// content the derive-timing guard is holding — a HOLD, not a loss. Its own kind
+// so a bundle reader can tell "the hygiene layer tolerated a divergence" from
+// "a detector tripped", which are opposite outcomes at the same boundary.
+export const LOSS_EVENT_PERSISTENCE_HOLD = 'persistence-hold';
+
+export const LOSS_EVENT_KINDS = [
+ LOSS_EVENT_GUARD_DEFER,
+ LOSS_EVENT_DETECTOR_TRIP,
+ LOSS_EVENT_BACKSTOP_TRIP,
+ LOSS_EVENT_CHECKPOINT_WRITE,
+ LOSS_EVENT_PERSISTENCE_HOLD,
+] as const;
+
+type LossEventKind = (typeof LOSS_EVENT_KINDS)[number];
+
+/**
+ * The persisted event shape. Every field is shape or correlation — there is no
+ * body-text / content field, and `loss-capture.test.ts` asserts the key set
+ * exactly so one can never be added without that test failing (content-free BY
+ * SCHEMA). `z.object` strips unknown keys on read, which is what makes a row
+ * written by a newer schema tolerable to an older reader.
+ */
+export const LossCaptureEventSchema = z.object({
+ /** Event wall-clock time in epoch milliseconds (stamped by the ring). */
+ ts: z.number(),
+ /** {@link LOSS_CAPTURE_SCHEMA_VERSION} at write time. */
+ schemaVersion: z.number(),
+ /** Per-doc monotonic sequence, assigned at record time; survives rotation. */
+ seq: z.number(),
+ /** Loss-class kind. Open string so future kinds parse on an older reader. */
+ event: z.string(),
+ /** Raw document name (kept raw locally; consent-gated at bundle time). */
+ docName: z.string(),
+ /** Writer identity when known; null otherwise (a slot future writers fill). */
+ writerId: z.string().nullable(),
+ /** Re-derive site the event fired at, when applicable. */
+ site: z.string().optional(),
+ /** Observer direction the event fired on, when applicable. */
+ direction: z.string().optional(),
+ /** Byte length of the at-risk / lost content — a length, never the bytes. */
+ lostLen: z.number().optional(),
+ /** Caller-computed digest of the at-risk content — a hash, never the bytes. */
+ digest: z.string().optional(),
+ /** Git sha of the checkpoint that preserved the content, when one was written. */
+ checkpointSha: z.string().optional(),
+});
+
+export type LossCaptureEvent = z.infer<typeof LossCaptureEventSchema>;
+
+/**
+ * What a producer supplies to {@link LossCaptureRing.record}. The ring stamps
+ * `ts`, `schemaVersion`, and the per-doc `seq`; everything else the producer
+ * fills. `event` is the closed producer vocabulary — new kinds extend
+ * {@link LOSS_EVENT_KINDS}.
+ */
+export interface LossCaptureEventInput {
+ event: LossEventKind;
+ docName: string;
+ writerId: string | null;
+ site?: string;
+ direction?: string;
+ lostLen?: number;
+ digest?: string;
+ checkpointSha?: string;
+}
+
+const LOSS_CAPTURE_SUBDIR = ['.ok', 'local', 'loss-capture'] as const;
+const LOSS_CURRENT_FILENAME = 'loss-current.jsonl';
+const LOSS_PREVIOUS_FILENAME = 'loss-prev.jsonl';
+
+/** Active loss-capture file path under `<projectDir>/.ok/local/loss-capture/`. */
+export function lossCaptureCurrentPath(projectDir: string): string {
+ return join(projectDir, ...LOSS_CAPTURE_SUBDIR, LOSS_CURRENT_FILENAME);
+}
+
+/** Previous-generation loss-capture file path. */
+export function lossCapturePreviousPath(projectDir: string): string {
+ return join(projectDir, ...LOSS_CAPTURE_SUBDIR, LOSS_PREVIOUS_FILENAME);
+}
+
+export interface LossCaptureRingOpts {
+ /** Project root (where `.ok/` lives). */
+ projectDir: string;
+ /** Rotation threshold for `loss-current.jsonl`. */
+ maxBytes: number;
+ /**
+ * Clock source. Injected because time is a system boundary — tests pin it for
+ * deterministic `ts` stamps. Defaults to `Date.now`.
+ */
+ now?: () => number;
+}
+
+/**
+ * Serialize `raw` (the contents of one loss-capture file) into events, oldest
+ * first. Lines that fail to `JSON.parse` are skipped — the appender's SIGKILL
+ * contract can leave one partial trailing line, and repair is the reader's job.
+ * A row whose `event` kind or `schemaVersion` an older reader does not
+ * recognize still parses; any unknown extra field is dropped.
+ */
+export function parseLossCaptureLines(raw: string): LossCaptureEvent[] {
+ const out: LossCaptureEvent[] = [];
+ for (const line of raw.split('\n')) {
+ if (line.length === 0) continue;
+ let json: unknown;
+ try {
+ json = JSON.parse(line);
+ } catch {
+ continue;
+ }
+ const parsed = LossCaptureEventSchema.safeParse(json);
+ if (parsed.success) out.push(parsed.data);
+ }
+ return out;
+}
+
+/**
+ * Append-only ring for loss-class events. One instance per project; wiring
+ * gates construction on the `lossCapture.enabled` config leaf, so a disabled
+ * ring is simply never built. `record()` is best-effort — a failed diagnostic
+ * write is logged and swallowed, never propagated into the caller's write path.
+ */
+export class LossCaptureRing {
+ readonly #appender: RotatingAppender;
+ readonly #now: () => number;
+ // In-memory per-doc counter, so a file rotation (which renames the file) does
+ // not reset the sequence — the counter lives with the process, not the file.
+ readonly #seqByDoc = new Map<string, number>();
+
+ constructor(opts: LossCaptureRingOpts) {
+ this.#appender = new RotatingAppender({
+ currentPath: lossCaptureCurrentPath(opts.projectDir),
+ previousPath: lossCapturePreviousPath(opts.projectDir),
+ maxBytes: opts.maxBytes,
+ });
+ this.#now = opts.now ?? Date.now;
+ }
+
+ /**
+ * Record one loss-class event. Resolves once the write settles (or its
+ * failure is logged); never rejects, so a producer can fire-and-forget from a
+ * hot path. The `seq` is assigned synchronously at call time, so event order
+ * on disk matches call order regardless of when the async write completes.
+ */
+ record(input: LossCaptureEventInput): Promise<void> {
+ const seq = (this.#seqByDoc.get(input.docName) ?? 0) + 1;
+ this.#seqByDoc.set(input.docName, seq);
+ const event: LossCaptureEvent = {
+ ts: this.#now(),
+ schemaVersion: LOSS_CAPTURE_SCHEMA_VERSION,
+ seq,
+ event: input.event,
+ docName: input.docName,
+ writerId: input.writerId,
+ ...(input.site !== undefined ? { site: input.site } : {}),
+ ...(input.direction !== undefined ? { direction: input.direction } : {}),
+ ...(input.lostLen !== undefined ? { lostLen: input.lostLen } : {}),
+ ...(input.digest !== undefined ? { digest: input.digest } : {}),
+ ...(input.checkpointSha !== undefined ? { checkpointSha: input.checkpointSha } : {}),
+ };
+ return this.#appender.append(`${JSON.stringify(event)}\n`).catch((err: unknown) => {
+ log.warn({ event: input.event, err }, '[loss-capture] failed to write loss-class event');
+ });
+ }
+
+ /** Resolve once any enqueued writes have settled — for tests + shutdown. */
+ async drain(): Promise<void> {
+ await this.#appender.drain();
+ }
+}
diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.ts
index a17279a72..6c2ad092c 100644
--- a/packages/server/src/metrics.ts
+++ b/packages/server/src/metrics.ts
@@ -278,6 +278,50 @@ export interface ReconciliationMetrics {
observerADuplicationRederives: number;
/** Successful duplication-recovery checkpoint writes — the forensic anchor for a destructive re-derive; divergence from `observerADuplicationRederives` means anchors are being lost. */
observerADuplicationCheckpointCreated: number;
+ /** Count of Observer A APPLY-arm content-loss trips — the byte-preserving
+ * apply arms (map-driven splice / incremental diff) dropped content the
+ * fragment's intended markdown held. An INDEPENDENT detection site from the
+ * Path-B merge post-condition, so it keeps its own event counter rather than
+ * inflating `bridgeMergeContentLoss` — an operator reading the
+ * anchors-per-loss ratio must be able to tell an apply drop from a merge
+ * drop. Increments on every trip, including one with no shadow wired, so a
+ * run whose checkpoint writes all fail does not read as healthy. */
+ observerAApplyLoss: number;
+ /** Successful `observer-a-apply-loss` checkpoint writes — the paired
+ * `...CheckpointCreated` sibling. `observerAApplyLoss - observerAApplyLossCheckpointCreated`
+ * is exactly the number of trips whose restore anchor never landed. */
+ observerAApplyLossCheckpointCreated: number;
+ /** Count of derive-timing defer-guard force-resolves — the guard reached its
+ * drain-count bound and resolved the re-derive loudly, checkpointing the
+ * pre-resolve fragment. A nonzero value in CI or a dogfood bundle is a
+ * surfaced regression: a doc was stuck in sustained defer-exhaustion. */
+ deriveTimingDeferForceResolved: number;
+ /** Count of persistence pre-write checks that HELD the fragment instead of
+ * rebuilding it, because the whole divergence was content the derive-timing
+ * guard is protecting. A tolerated divergence, not a loss: Y.Text still went
+ * to disk. A sustained nonzero rate on one doc is the quiescent-hold signal
+ * — the keystroke is alive in the fragment but not yet durable. */
+ persistenceDeferHold: number;
+ /** Count of persistence pre-write checks that found a divergence OUTSIDE the
+ * guard's protected set and rebuilt the fragment. Increments on every trip,
+ * including deduped ones and ones with no shadow wired, so a run whose
+ * anchors never landed does not read as healthy. */
+ persistenceReconcileLoss: number;
+ /** Successful `persistence-reconcile-loss` checkpoint writes. With the
+ * deduped sibling this closes the identity
+ * `persistenceReconcileLoss = created + deduped + (anchors that never landed)`. */
+ persistenceReconcileLossCheckpointCreated: number;
+ /** Trips whose pre-rebuild fragment state was byte-identical to the anchor
+ * already on the timeline for that doc, so no new checkpoint was minted. A
+ * doc resting on a construct that diverges on every write-back lives here;
+ * without the dedup it would evict its own useful anchors. */
+ persistenceReconcileLossDeduped: 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
+ * dogfood bundle is a surfaced regression: a doc was stuck in a runaway
+ * re-derive loop. */
+ reDeriveBackstopTripped: number;
/** Y.Text-is-truth contract (precedent #38) — count of Observer A
* settlement checks that detected a drain settling split-brain (Y.Text
* vs serialize(fragment) divergence beyond `normalizeBridge` tolerance)
@@ -479,6 +523,14 @@ const counters: ReconciliationMetrics = {
observerAResidualMergeRuns: 0,
observerADuplicationRederives: 0,
observerADuplicationCheckpointCreated: 0,
+ observerAApplyLoss: 0,
+ observerAApplyLossCheckpointCreated: 0,
+ deriveTimingDeferForceResolved: 0,
+ persistenceDeferHold: 0,
+ persistenceReconcileLoss: 0,
+ persistenceReconcileLossCheckpointCreated: 0,
+ persistenceReconcileLossDeduped: 0,
+ reDeriveBackstopTripped: 0,
bridgeSplitBrainRederives: 0,
bridgeSplitBrainRederivesSuppressed: 0,
persistenceReconciliationFailures: 0,
@@ -683,6 +735,38 @@ export function incrementObserverADuplicationCheckpointCreated(): void {
counters.observerADuplicationCheckpointCreated++;
}
+export function incrementObserverAApplyLoss(): void {
+ counters.observerAApplyLoss++;
+}
+
+export function incrementObserverAApplyLossCheckpointCreated(): void {
+ counters.observerAApplyLossCheckpointCreated++;
+}
+
+export function incrementDeriveTimingDeferForceResolved(): void {
+ counters.deriveTimingDeferForceResolved++;
+}
+
+export function incrementPersistenceDeferHold(): void {
+ counters.persistenceDeferHold++;
+}
+
+export function incrementPersistenceReconcileLoss(): void {
+ counters.persistenceReconcileLoss++;
+}
+
+export function incrementPersistenceReconcileLossCheckpointCreated(): void {
+ counters.persistenceReconcileLossCheckpointCreated++;
+}
+
+export function incrementPersistenceReconcileLossDeduped(): void {
+ counters.persistenceReconcileLossDeduped++;
+}
+
+export function incrementReDeriveBackstopTripped(): void {
+ counters.reDeriveBackstopTripped++;
+}
+
export function incrementBridgeSplitBrainRederives(): void {
counters.bridgeSplitBrainRederives++;
}
@@ -761,10 +845,22 @@ export function incrementCollabMessageTooLarge(): void {
counters.collabMessageTooLargeCount++;
}
+export function incrementShadowMigrationLegacyRefsDeleted(count: number): void {
+ counters.shadowMigrationLegacyRefsDeleted += count;
+}
+
+export function incrementEffectDiffCaptureFailures(): void {
+ counters.effectDiffCaptureFailures++;
+}
+
+export function incrementAgentPresenceMutationError(): void {
+ counters.agentPresenceMutationErrors++;
+}
+
/**
* Classify a collab-socket error. Returns `true` if the error is a
* known-safe kernel TCP-teardown signal (EPIPE or ECONNRESET) that should
- * be filtered out of logs per precedent §23. As a side effect, increments
+ * be filtered out of logs per precedent #22. As a side effect, increments
* the corresponding per-code metric counter so operators can see the rate
* during incident triage.
*
@@ -790,18 +886,6 @@ export function incrementCollabMessageTooLarge(): void {
* ws.terminate();
* });
*/
-export function incrementShadowMigrationLegacyRefsDeleted(count: number): void {
- counters.shadowMigrationLegacyRefsDeleted += count;
-}
-
-export function incrementEffectDiffCaptureFailures(): void {
- counters.effectDiffCaptureFailures++;
-}
-
-export function incrementAgentPresenceMutationError(): void {
- counters.agentPresenceMutationErrors++;
-}
-
export function handleCollabSocketError(err: NodeJS.ErrnoException): boolean {
if (err.code === 'EPIPE' || err.code === 'ECONNRESET') {
incrementCollabSocketFilteredError(err.code);
@@ -881,6 +965,14 @@ export function resetMetrics(): void {
counters.observerAResidualMergeRuns = 0;
counters.observerADuplicationRederives = 0;
counters.observerADuplicationCheckpointCreated = 0;
+ counters.observerAApplyLoss = 0;
+ counters.observerAApplyLossCheckpointCreated = 0;
+ counters.deriveTimingDeferForceResolved = 0;
+ counters.persistenceDeferHold = 0;
+ counters.persistenceReconcileLoss = 0;
+ counters.persistenceReconcileLossCheckpointCreated = 0;
+ counters.persistenceReconcileLossDeduped = 0;
+ counters.reDeriveBackstopTripped = 0;
counters.bridgeSplitBrainRederives = 0;
counters.bridgeSplitBrainRederivesSuppressed = 0;
counters.persistenceReconciliationFailures = 0;
diff --git a/packages/server/src/normalize-write-sink-gate.test.ts b/packages/server/src/normalize-write-sink-gate.test.ts
new file mode 100644
index 000000000..cdb3a0c9e
--- /dev/null
+++ b/packages/server/src/normalize-write-sink-gate.test.ts
@@ -0,0 +1,214 @@
+/**
+ * `normalizeBridge` output must never drive a byte write.
+ *
+ * `normalizeBridge` collapses tolerance-class differences (trailing whitespace,
+ * blank-line runs, escape forms) so two representations can be COMPARED for
+ * bridge equality. Its output is a lossy canonical form — writing it back to
+ * disk or into `Y.Text`/`Y.XmlFragment` would silently rewrite the user's
+ * byte-sacred source (precedent #57). Every `normalizeBridge` caller today is
+ * comparison-only; this gate keeps it that way by failing the build when a
+ * `normalizeBridge` result flows (directly, or via a one-hop local const) into
+ * a byte-write sink argument.
+ *
+ * Blindness residual: cross-function flow (a function that RETURNS
+ * `normalizeBridge` output whose caller then writes it) is not statically
+ * traced here — that needs whole-program type resolution. The compensating
+ * controls are the manual audit that verified every caller comparison-only and
+ * the per-write-path byte-sacred discipline (precedent #57). The realistic
+ * regression — someone writing a freshly-normalized value — is caught.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Node, Project, type SourceFile, SyntaxKind } from 'ts-morph';
+import { describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packagesDir = join(here, '..', '..');
+const SCAN_ROOTS = [
+ join(packagesDir, 'app', 'src'),
+ join(packagesDir, 'server', 'src'),
+ join(packagesDir, 'core', 'src'),
+];
+
+/** Functions that write bytes to disk or to the body CRDTs. */
+const SINK_FUNCTIONS = new Set<string>([
+ 'tracedWriteFile',
+ 'tracedWriteFileSync',
+ 'writeFile',
+ 'writeFileSync',
+ 'composeAndWriteRawBody',
+ 'replaceRawBody',
+]);
+
+/** Content-bearing CRDT mutation methods (a normalized value as an arg = a write). */
+const SINK_METHODS = new Set<string>(['insert', 'splice', 'applyDelta', 'push', 'unshift']);
+
+const NORMALIZE_FN = 'normalizeBridge';
+
+interface Violation {
+ readonly file: string;
+ readonly line: number;
+ readonly detail: string;
+}
+
+function calleeName(call: Node): string | null {
+ if (!Node.isCallExpression(call)) return null;
+ const callee = call.getExpression();
+ if (callee.isKind(SyntaxKind.Identifier)) return callee.getText();
+ if (callee.isKind(SyntaxKind.PropertyAccessExpression)) return callee.getName();
+ return null;
+}
+
+/** True when `node` is or contains a `normalizeBridge(...)` call. */
+function containsNormalize(node: Node): boolean {
+ if (Node.isCallExpression(node) && calleeName(node) === NORMALIZE_FN) return true;
+ return node
+ .getDescendantsOfKind(SyntaxKind.CallExpression)
+ .some((c) => calleeName(c) === NORMALIZE_FN);
+}
+
+/** Local var names whose initializer is derived from `normalizeBridge`. */
+function taintedConstNames(sf: SourceFile): Set<string> {
+ const names = new Set<string>();
+ for (const decl of sf.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+ const init = decl.getInitializer();
+ if (!init) continue;
+ if (containsNormalize(init)) {
+ const nameNode = decl.getNameNode();
+ if (nameNode.isKind(SyntaxKind.Identifier)) names.add(nameNode.getText());
+ }
+ }
+ return names;
+}
+
+function isSinkCall(call: Node): boolean {
+ if (!Node.isCallExpression(call)) return false;
+ const name = calleeName(call);
+ if (!name) return false;
+ if (SINK_FUNCTIONS.has(name)) return true;
+ return call.getExpression().isKind(SyntaxKind.PropertyAccessExpression) && SINK_METHODS.has(name);
+}
+
+function analyzeSourceFile(rel: string, sf: SourceFile): Violation[] {
+ const tainted = taintedConstNames(sf);
+ const violations: Violation[] = [];
+ for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+ if (!isSinkCall(call)) continue;
+ for (const arg of call.getArguments()) {
+ const argTainted =
+ containsNormalize(arg) || (arg.isKind(SyntaxKind.Identifier) && tainted.has(arg.getText()));
+ if (argTainted) {
+ violations.push({
+ file: rel,
+ line: call.getStartLineNumber(),
+ detail: `${calleeName(call)}(...) receives a normalizeBridge-derived (canonicalized) value as a byte-write argument`,
+ });
+ break;
+ }
+ }
+ }
+ return violations;
+}
+
+function isScannableFile(name: string): boolean {
+ if (!name.endsWith('.ts') && !name.endsWith('.tsx')) return false;
+ if (name.endsWith('.d.ts')) return false;
+ if (name.includes('.test-helper.')) return false;
+ if (/\.(test|spec|e2e)\./.test(name)) return false;
+ return true;
+}
+
+function collectCandidateFiles(root: string): string[] {
+ const out: string[] = [];
+ const walk = (dir: string): void => {
+ let entries: string[];
+ try {
+ entries = readdirSync(dir);
+ } catch {
+ return;
+ }
+ for (const entry of entries) {
+ if (entry === 'node_modules' || entry === 'dist' || entry === '__mocks__') continue;
+ const abs = join(dir, entry);
+ if (statSync(abs).isDirectory()) walk(abs);
+ else if (isScannableFile(entry) && readFileSync(abs, 'utf8').includes(`${NORMALIZE_FN}(`))
+ out.push(abs);
+ }
+ };
+ walk(root);
+ return out;
+}
+
+function newProject(): Project {
+ return new Project({
+ skipFileDependencyResolution: true,
+ skipLoadingLibFiles: true,
+ skipAddingFilesFromTsConfig: true,
+ compilerOptions: { noLib: true, allowJs: false },
+ });
+}
+
+describe('normalize-write-sink gate', () => {
+ it('no normalizeBridge output flows into a byte-write sink', () => {
+ const project = newProject();
+ const files: Array<readonly [string, SourceFile]> = [];
+ for (const root of SCAN_ROOTS) {
+ for (const abs of collectCandidateFiles(root)) {
+ files.push([abs.slice(packagesDir.length + 1), project.addSourceFileAtPath(abs)] as const);
+ }
+ }
+ expect(files.length).toBeGreaterThan(0);
+
+ const violations = files.flatMap(([rel, sf]) => analyzeSourceFile(rel, sf));
+ if (violations.length > 0) {
+ const lines = violations.map((v) => ` ${v.file}:${v.line} — ${v.detail}`).join('\n');
+ throw new Error(
+ `Found ${violations.length} normalizeBridge-to-write-sink flow(s):\n${lines}\n` +
+ `normalizeBridge is comparison-only; write RAW bytes, never the canonicalized form.`,
+ );
+ }
+ });
+
+ it('catches a direct normalizeBridge-to-sink write (planted positive)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-direct.ts',
+ `function w(path: string, body: string, ytext: any) {
+ tracedWriteFile(path, normalizeBridge(body));
+ ytext.insert(0, normalizeBridge(body));
+ }`,
+ );
+ expect(analyzeSourceFile('planted-direct.ts', sf)).toHaveLength(2);
+ });
+
+ it('catches a one-hop normalizeBridge-to-sink write (planted positive)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-onehop.ts',
+ `function w(path: string, body: string) {
+ const canonical = normalizeBridge(body);
+ tracedWriteFile(path, canonical);
+ }`,
+ );
+ const violations = analyzeSourceFile('planted-onehop.ts', sf);
+ expect(violations).toHaveLength(1);
+ expect(violations[0]?.detail).toContain('normalizeBridge-derived');
+ });
+
+ it('passes comparison-only and raw-byte-write sites (positive controls)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'controls.ts',
+ `function compare(disk: string, base: string) {
+ return normalizeBridge(disk) === normalizeBridge(base);
+ }
+ function rawWrite(path: string, rawBody: string, ytext: any) {
+ const norm = normalizeBridge(rawBody);
+ if (norm !== '') tracedWriteFile(path, rawBody);
+ ytext.insert(0, rawBody);
+ }`,
+ );
+ expect(analyzeSourceFile('controls.ts', sf)).toHaveLength(0);
+ });
+});
diff --git a/packages/server/src/paired-intake-detection-wiring.test.ts b/packages/server/src/paired-intake-detection-wiring.test.ts
new file mode 100644
index 000000000..1939dc11b
--- /dev/null
+++ b/packages/server/src/paired-intake-detection-wiring.test.ts
@@ -0,0 +1,223 @@
+/**
+ * `PAIRED_INTAKE_DETECTION` is load-bearing at every wired intake, not
+ * decoration.
+ *
+ * The registry declares, per paired-write origin, whether that origin's intake
+ * derive runs the content-loss post-condition. A site that decides on reporter
+ * presence alone still LOOKS correct while the registry says `detect` — the
+ * divergence only surfaces the day someone reclassifies an origin to `suppress`
+ * and nothing changes. These tests flip each classification at runtime and
+ * assert the wired site actually follows it, so the registry cannot silently
+ * become advisory at any one site.
+ */
+
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Hocuspocus } from '@hocuspocus/server';
+import { sharedExtensions } from '@inkeep/open-knowledge-core';
+import { getSchema } from '@tiptap/core';
+import { updateYFragment } from '@tiptap/y-tiptap';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import type * as Y from 'yjs';
+import {
+ type BridgeDeriveLossReporter,
+ type DeriveLossObservation,
+ detectPairedIntakeLoss,
+} from './bridge-loss-detector.ts';
+import {
+ PAIRED_INTAKE_DETECTION,
+ type PairedIntakeDetectionMode,
+} from './bridge-loss-suppression.ts';
+import { DocumentDurabilityState } from './document-durability-state.ts';
+import { reconcileDiskBeforeAgentWrite } from './external-change.ts';
+import { mdManager } from './md-manager.ts';
+import { createWiredPreDrainRig, WIRED_PENDING_LINE } from './pre-drain-wired.test-helper.ts';
+
+const schema = getSchema(sharedExtensions);
+
+/** Run `fn` with one origin temporarily reclassified, then restore. */
+function withMode(origin: string, mode: PairedIntakeDetectionMode, fn: () => void): void;
+function withMode(
+ origin: string,
+ mode: PairedIntakeDetectionMode,
+ fn: () => Promise<void>,
+): Promise<void>;
+function withMode(
+ origin: string,
+ mode: PairedIntakeDetectionMode,
+ fn: () => void | Promise<void>,
+): void | Promise<void> {
+ const entry = PAIRED_INTAKE_DETECTION[origin];
+ if (!entry) throw new Error(`unclassified paired origin: ${origin}`);
+ const previous = entry.mode;
+ entry.mode = mode;
+ const restore = () => {
+ entry.mode = previous;
+ };
+ try {
+ const out = fn();
+ if (out instanceof Promise) return out.finally(restore);
+ restore();
+ return out;
+ } catch (err) {
+ restore();
+ throw err;
+ }
+}
+
+/** Collect only OBSERVATIONS that actually carry a loss verdict. */
+function lossCollector(): { trips: DeriveLossObservation[]; reporter: BridgeDeriveLossReporter } {
+ const trips: DeriveLossObservation[] = [];
+ return {
+ trips,
+ reporter: (_docName, obs) => {
+ if (detectPairedIntakeLoss(obs).length > 0) trips.push(obs);
+ },
+ };
+}
+
+describe('paired-intake detection follows the registry at every wired site', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ test('agent-undo: reclassifying to suppress actually stops the undo-derive detection', async () => {
+ // Baseline: classified `detect`, so the undo derive over an un-propagated
+ // keystroke trips. (Pre-drain off so the content reaches the floor rather
+ // than being flushed to safety first.)
+ const on = lossCollector();
+ const rigOn = await createWiredPreDrainRig({
+ docName: 'undo-detect.md',
+ reporter: on.reporter,
+ setupOverrides: { preDrainEnabled: false },
+ });
+ try {
+ rigOn.agentWrite('Agent appended line.', 'append');
+ rigOn.stageUnpropagatedKeystroke();
+ expect(rigOn.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ rigOn.agentUndo('last');
+ expect(on.trips.length).toBeGreaterThan(0);
+ } finally {
+ await rigOn.cleanup();
+ }
+
+ const off = lossCollector();
+ const rigOff = await createWiredPreDrainRig({
+ docName: 'undo-suppress.md',
+ reporter: off.reporter,
+ setupOverrides: { preDrainEnabled: false },
+ });
+ try {
+ await withMode('agent-undo', 'suppress', async () => {
+ rigOff.agentWrite('Agent appended line.', 'append');
+ rigOff.stageUnpropagatedKeystroke();
+ expect(rigOff.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ rigOff.agentUndo('last');
+ });
+ expect(off.trips).toEqual([]);
+ } finally {
+ await rigOff.cleanup();
+ }
+ });
+
+ test('agent-write: reclassifying to suppress actually stops the write-intake detection', async () => {
+ const on = lossCollector();
+ const rigOn = await createWiredPreDrainRig({
+ docName: 'write-detect.md',
+ reporter: on.reporter,
+ setupOverrides: { preDrainEnabled: false },
+ });
+ try {
+ rigOn.stageUnpropagatedKeystroke();
+ rigOn.agentWrite('## Replaced\n\nBrand new body.\n', 'replace');
+ expect(on.trips.length).toBeGreaterThan(0);
+ } finally {
+ await rigOn.cleanup();
+ }
+
+ const off = lossCollector();
+ const rigOff = await createWiredPreDrainRig({
+ docName: 'write-suppress.md',
+ reporter: off.reporter,
+ setupOverrides: { preDrainEnabled: false },
+ });
+ try {
+ await withMode('agent-write', 'suppress', async () => {
+ rigOff.stageUnpropagatedKeystroke();
+ rigOff.agentWrite('## Replaced\n\nBrand new body.\n', 'replace');
+ });
+ expect(off.trips).toEqual([]);
+ } finally {
+ await rigOff.cleanup();
+ }
+ });
+
+ test('file-watcher: reclassifying to suppress actually stops the reconcile-intake detection', async () => {
+ const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-registry-wiring-')));
+ const hp = new Hocuspocus({ quiet: true });
+ const durabilityState = new DocumentDurabilityState();
+ const base = '# Notes\n\nFirst paragraph.\n';
+ const pending = 'A keystroke that never reached Y.Text.';
+
+ const seed = async (docName: string): Promise<Y.Doc> => {
+ const conn = await hp.openDirectConnection(docName);
+ const doc = (conn as unknown as { document: Y.Doc }).document;
+ writeFileSync(join(contentDir, `${docName}.md`), base);
+ durabilityState.setReconciledBase(docName, base);
+ doc.transact(() => {
+ doc.getText('source').insert(0, base);
+ updateYFragment(
+ doc,
+ doc.getXmlFragment('default'),
+ schema.nodeFromJSON(mdManager.parse(base)),
+ { mapping: new Map(), isOMark: new Map() },
+ );
+ }, 'seed');
+ doc.transact(() => {
+ updateYFragment(
+ doc,
+ doc.getXmlFragment('default'),
+ schema.nodeFromJSON(mdManager.parse(`${base}\n${pending}\n`)),
+ { mapping: new Map(), isOMark: new Map() },
+ );
+ }, 'wysiwyg');
+ writeFileSync(join(contentDir, `${docName}.md`), '# Notes\n\nEdited on disk.\n');
+ return doc;
+ };
+
+ try {
+ const on = lossCollector();
+ await seed('watcher-detect');
+ reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hp,
+ 'watcher-detect',
+ contentDir,
+ undefined,
+ on.reporter,
+ );
+ expect(on.trips.length).toBeGreaterThan(0);
+
+ const off = lossCollector();
+ await seed('watcher-suppress');
+ withMode('file-watcher', 'suppress', () => {
+ reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hp,
+ 'watcher-suppress',
+ contentDir,
+ undefined,
+ off.reporter,
+ );
+ });
+ expect(off.trips).toEqual([]);
+ } finally {
+ rmSync(contentDir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/packages/server/src/paired-write-enforcement.test.ts b/packages/server/src/paired-write-enforcement.test.ts
index ca683fec5..9d4d222ae 100644
--- a/packages/server/src/paired-write-enforcement.test.ts
+++ b/packages/server/src/paired-write-enforcement.test.ts
@@ -157,7 +157,12 @@ function loadServerSourceFiles(): ReadonlyArray<readonly [string, SourceFile]> {
const out: Array<readonly [string, SourceFile]> = [];
const glob = new Bun.Glob('**/*.ts');
for (const rel of glob.scanSync({ cwd: SERVER_SRC_DIR, absolute: false, onlyFiles: true })) {
- if (rel.endsWith('.test.ts') || rel.endsWith('.d.ts')) continue;
+ // Skip test code. `.test-helper.ts` is test-only scaffolding (never imported
+ // by production) that legitimately constructs non-paired origins to model
+ // external client edits at the drain rung; the paired-write contract this
+ // gate enforces is a production-code invariant.
+ if (rel.endsWith('.test.ts') || rel.endsWith('.test-helper.ts') || rel.endsWith('.d.ts'))
+ continue;
const abs = join(SERVER_SRC_DIR, rel);
const sf = project.addSourceFileAtPath(abs);
out.push([abs, sf] as const);
diff --git a/packages/server/src/persistence-defer-hold.test.ts b/packages/server/src/persistence-defer-hold.test.ts
new file mode 100644
index 000000000..3dba2b8be
--- /dev/null
+++ b/packages/server/src/persistence-defer-hold.test.ts
@@ -0,0 +1,543 @@
+/**
+ * The persistence pre-write divergence arms, on the REAL `setupServerObservers`
+ * drain plus the REAL persistence extension.
+ *
+ * The measured failure: after the derive-timing guard protects a WYSIWYG
+ * keystroke (fragment ahead of Y.Text), the store debounce fires and the
+ * pre-write sanity check rebuilds the fragment from Y.Text. The rebuild runs
+ * under `OBSERVER_SYNC_ORIGIN`, which both observers self-skip, so the keystroke
+ * leaves the live fragment with no checkpoint and no ring event — only the
+ * rate-limited hygiene counter moves. The `no store` arm below is the
+ * non-vacuity control: the same staging without a store keeps the keystroke, so
+ * a green hold arm cannot be an artifact of the staging.
+ *
+ * Staging is the same defer-then-trigger shape `derive-defer-floor.test.ts`
+ * uses, so a defer is genuinely in flight when the store runs.
+ *
+ * Rungs. The store fires two ways: through the real Hocuspocus `Debouncer` (the
+ * production path — the timer that fires on a user pause), and through a direct
+ * `extension.onStoreDocument` call (the hook that debouncer invokes). The
+ * debounce arm stubs only the `Document` affordances a bare `Y.Doc` lacks
+ * (`saveMutex`, `getConnectionsCount`), neither of which any arm exercises.
+ *
+ * The hold arm's shape is staged synthetically (a fragment line in neither
+ * Y.Text nor the attach-time witness) rather than through any construct whose
+ * serialization happens to be lossy: constructs get fixed upstream — the
+ * original probe here, `**[[a]]**` with marks dropped on a leaf wikilink, did —
+ * and a fixture premised on a defect dies with the defect. The construct stays
+ * as a round-trip pin in the opposite direction: converged docs fire neither
+ * arm.
+ */
+
+import { readFileSync } from 'node:fs';
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { Hocuspocus } from '@hocuspocus/server';
+import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
+import { updateYFragment } from '@tiptap/y-tiptap';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+ type LossCaptureEvent,
+ LossCaptureRing,
+ lossCaptureCurrentPath,
+ parseLossCaptureLines,
+} from './loss-capture.ts';
+import { mdManager, schema } from './md-manager.ts';
+import { getMetrics, resetMetrics } from './metrics.ts';
+import { createPersistenceExtension, type PersistenceOptions } from './persistence.ts';
+import {
+ createWiredPreDrainRig,
+ WIRED_PENDING_LINE,
+ type WiredPreDrainRig,
+} from './pre-drain-wired.test-helper.ts';
+import { OBSERVER_SYNC_ORIGIN } from './server-observers.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+/** A browser-shaped store origin — the writer a keystroke-driven store carries. */
+const BROWSER_ORIGIN = {
+ source: 'connection',
+ connection: { context: { principalId: 'principal-test' } },
+};
+
+/**
+ * The construct from the emphasis-touching-wikilink field report. Its fragment
+ * view used to be lossy against Y.Text (the bridge dropped marks on inline leaf
+ * nodes), which made it a live hold-arm trigger; the upstream bridge fix made
+ * it round-trip clean, so it now pins the OPPOSITE contract: a converged doc
+ * fires neither arm. Keep the fixture — it guards the round-trip both ways.
+ */
+const WIKILINK_EMPHASIS_SOURCE = '# Notes\n\n**[[a]]**\n';
+
+/**
+ * A stale-fragment divergence: the fragment holds a line Y.Text no longer does,
+ * and that line was in the last settlement — so it is NOT a keystroke the guard
+ * could be protecting, and the floor arm owns it.
+ */
+const STALE_FRAGMENT_MD = '## Guide\n\nStep one bod\n\nTail paragraph.\n';
+const STALE_YTEXT_MD = '## Guide\n\nStep one bod\n';
+const STALE_FRAGMENT_ONLY_LINE = 'Tail paragraph.';
+
+/**
+ * A pending-content divergence: the fragment holds a line that is in NEITHER
+ * Y.Text NOR the attach-time witness — the exact three-way shape of an
+ * un-propagated keystroke, staged synthetically so the arm does not depend on
+ * any construct's serialization being lossy (constructs get fixed; the shape
+ * is what the predicate tolerates).
+ */
+const PENDING_FRAGMENT_MD = '## Guide\n\nStep one bod\n\nA held novel line.\n\nTail paragraph.\n';
+const PENDING_YTEXT_MD = '## Guide\n\nStep one bod\n\nTail paragraph.\n';
+const PENDING_NOVEL_LINE = 'A held novel line.';
+
+interface StoreHarness {
+ readonly wired: WiredPreDrainRig;
+ readonly shadow: ShadowHandle;
+ readonly ring: LossCaptureRing;
+ readonly docName: string;
+ readonly projectRoot: string;
+ /** Stage a genuinely in-flight derive-timing defer; asserts the defer fired. */
+ stageDeferredKeystroke(): void;
+ /**
+ * Put both replicas into a fixed stale-fragment divergence under the
+ * observers' OWN sync origin, which both self-skip — so nothing reacts and
+ * the state is exactly what the next store sees. Idempotent by construction:
+ * re-staging reproduces the identical pre-rebuild payload, which is what a
+ * document whose fragment view is structurally lossy against its own bytes
+ * presents on every write-back.
+ */
+ stageStaleFragment(): void;
+ /**
+ * Same staging mechanics, but the fragment-only line is absent from the
+ * attach-time witness too — the pending-content three-way shape the hold
+ * arm tolerates.
+ */
+ stagePendingDivergence(): void;
+ /** Drive the production store hook directly. */
+ storeDirect(): Promise<void>;
+ /** Drive the store through the real Hocuspocus debouncer. */
+ storeDebounced(): Promise<void>;
+ /** Bytes currently on disk for the doc, or null when the file is absent. */
+ diskBytes(): string | null;
+ /** Every loss-ring event recorded so far. */
+ readRing(): Promise<LossCaptureEvent[]>;
+ /** Every `refs/checkpoints/main/*` sha. */
+ checkpointShas(): Promise<string[]>;
+ cleanup(): Promise<void>;
+}
+
+async function createStoreHarness(
+ docName: string,
+ overrides?: Partial<PersistenceOptions>,
+): Promise<StoreHarness> {
+ // Realpath first: on macOS the tmpdir is a symlink, and persistence derives
+ // its shadow tree prefix from `relative(projectDir, contentDir)` — two spellings
+ // of the same directory would resolve that to an escaping absolute path.
+ const tmpDir = await realpath(await mkdtemp(resolve(tmpdir(), 'ok-defer-hold-')));
+ const projectRoot = resolve(tmpDir, 'project');
+ const shadow = await initShadowRepo(projectRoot);
+ const ring = new LossCaptureRing({ projectDir: projectRoot, maxBytes: 1_000_000 });
+
+ let defers = 0;
+ const wired = await createWiredPreDrainRig({
+ docName,
+ setupOverrides: {
+ onDeriveTimingDefer: () => {
+ defers += 1;
+ },
+ },
+ });
+
+ const persistence = createPersistenceExtension({
+ contentDir: projectRoot,
+ projectDir: projectRoot,
+ gitEnabled: false,
+ shadowRef: { current: shadow },
+ getLossRing: () => ring,
+ ...overrides,
+ });
+
+ const hocuspocus = new Hocuspocus({
+ quiet: true,
+ debounce: 20,
+ maxDebounce: 10_000,
+ extensions: [persistence.extension],
+ });
+ const docShim = wired.doc as unknown as { saveMutex: unknown; getConnectionsCount: unknown };
+ docShim.saveMutex = {
+ runExclusive: async (fn: () => Promise<unknown>) => fn(),
+ isLocked: () => false,
+ };
+ // Non-zero keeps the instance's post-store unload sweep off a doc the observer
+ // rig owns; document lifecycle is not what these arms exercise.
+ docShim.getConnectionsCount = () => 1;
+
+ const diskBytes = (): string | null => {
+ try {
+ return readFileSync(resolve(projectRoot, `${docName}.md`), 'utf-8');
+ } catch {
+ return null;
+ }
+ };
+
+ const storePayload = {
+ document: wired.doc,
+ documentName: docName,
+ lastTransactionOrigin: BROWSER_ORIGIN,
+ lastContext: {},
+ };
+
+ return {
+ wired,
+ shadow,
+ ring,
+ docName,
+ projectRoot,
+ stageDeferredKeystroke: () => {
+ wired.stageUnpropagatedKeystroke();
+ const before = defers;
+ // A source-editor write inside the freshness-hot window is the drain the
+ // guard defers; `advanceFreshness: false` keeps the window hot.
+ wired.rig.externalYtextEdit(
+ 'source-write',
+ (yt) => yt.insert(yt.length, '\nAnother source line.\n'),
+ { advanceFreshness: false },
+ );
+ expect(defers).toBeGreaterThan(before);
+ expect(wired.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(wired.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ },
+ stageStaleFragment: () => {
+ const node = schema.nodeFromJSON(mdManager.parse(STALE_FRAGMENT_MD));
+ wired.doc.transact(() => {
+ updateYFragment(wired.doc, wired.doc.getXmlFragment('default'), node, {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ const yt = wired.doc.getText('source');
+ yt.delete(0, yt.length);
+ yt.insert(0, STALE_YTEXT_MD);
+ }, OBSERVER_SYNC_ORIGIN);
+ expect(wired.serializeFragment()).toContain(STALE_FRAGMENT_ONLY_LINE);
+ expect(wired.ytextString()).not.toContain(STALE_FRAGMENT_ONLY_LINE);
+ },
+ stagePendingDivergence: () => {
+ const node = schema.nodeFromJSON(mdManager.parse(PENDING_FRAGMENT_MD));
+ wired.doc.transact(() => {
+ updateYFragment(wired.doc, wired.doc.getXmlFragment('default'), node, {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ const yt = wired.doc.getText('source');
+ yt.delete(0, yt.length);
+ yt.insert(0, PENDING_YTEXT_MD);
+ }, OBSERVER_SYNC_ORIGIN);
+ expect(wired.serializeFragment()).toContain(PENDING_NOVEL_LINE);
+ expect(wired.ytextString()).not.toContain(PENDING_NOVEL_LINE);
+ },
+ storeDirect: async () => {
+ await persistence.extension.onStoreDocument?.(storePayload as never);
+ },
+ storeDebounced: async () => {
+ void hocuspocus.storeDocumentHooks(wired.doc as never, storePayload as never);
+ // The debouncer's timer fires the hook; the hook's own disk write settles
+ // after it. Wait for the durable effect, not just the arm's counter.
+ for (let i = 0; i < 200; i++) {
+ await new Promise((r) => setTimeout(r, 10));
+ const armed = getMetrics().persistenceDeferHold + getMetrics().persistenceReconcileLoss > 0;
+ if (armed && diskBytes() !== null) return;
+ }
+ },
+ diskBytes,
+ readRing: async () => {
+ await ring.drain();
+ try {
+ return parseLossCaptureLines(readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'));
+ } catch {
+ return [];
+ }
+ },
+ checkpointShas: async () => {
+ const out = await shadowGit(shadow).raw(
+ 'for-each-ref',
+ '--format=%(objectname)',
+ 'refs/checkpoints/main',
+ );
+ return out
+ .toString()
+ .split('\n')
+ .map((line) => line.trim())
+ .filter(Boolean);
+ },
+ cleanup: async () => {
+ await wired.cleanup();
+ await rm(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ },
+ };
+}
+
+/**
+ * Poll until `expected` floor mints have COMPLETED, or give up. Gated on the
+ * completion counter rather than the ref listing: git creates the ref before
+ * the write promise settles, so polling refs alone can observe a half-finished
+ * mint.
+ */
+async function awaitMints(h: StoreHarness, expected: number): Promise<string[]> {
+ for (let i = 0; i < 200; i++) {
+ if (getMetrics().persistenceReconcileLossCheckpointCreated >= expected) break;
+ await new Promise((r) => setTimeout(r, 10));
+ }
+ return h.checkpointShas();
+}
+
+describe('persistence pre-write divergence arms', () => {
+ beforeEach(() => {
+ resetMetrics();
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ resetMetrics();
+ });
+
+ test('no store: the deferred keystroke survives (non-vacuity control)', async () => {
+ const h = await createStoreHarness('hold-control');
+ try {
+ h.stageDeferredKeystroke();
+
+ // Nothing else runs. If this ever fails, every hold arm below is vacuous.
+ expect(h.wired.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(getMetrics().persistenceDeferHold).toBe(0);
+ expect(h.diskBytes()).toBeNull();
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('direct onStoreDocument: the deferred keystroke survives and Y.Text persists', async () => {
+ const h = await createStoreHarness('hold-direct');
+ try {
+ h.stageDeferredKeystroke();
+
+ await h.storeDirect();
+
+ expect(h.wired.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ // Y.Text is truth and goes to disk regardless — the hold defers the
+ // fragment's convergence, never the durability of the user's bytes.
+ expect(h.diskBytes()).toBe(h.wired.ytextString());
+ expect(getMetrics().persistenceDeferHold).toBe(1);
+ expect(getMetrics().persistenceReconcileLoss).toBe(0);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('debounced store: the deferred keystroke survives, breadcrumbed content-free', async () => {
+ const h = await createStoreHarness('hold-debounced');
+ try {
+ h.stageDeferredKeystroke();
+
+ await h.storeDebounced();
+
+ expect(h.wired.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(h.diskBytes()).toBe(h.wired.ytextString());
+ expect(getMetrics().persistenceDeferHold).toBe(1);
+
+ const holds = (await h.readRing()).filter((e) => e.event === 'persistence-hold');
+ expect(holds).toHaveLength(1);
+ const hold = holds[0];
+ expect(hold?.site).toBe('persistence-prewrite');
+ // The AT-RISK bytes, not the document's — a whole-document length would
+ // read as a multi-KB loss on a one-line hold. The set here is the
+ // re-indented component block the keystroke sits in, so it is at least
+ // that line and strictly less than the document.
+ expect(hold?.lostLen).toBeGreaterThanOrEqual(WIRED_PENDING_LINE.length);
+ expect(hold?.lostLen).toBeLessThan(h.wired.serializeFragment().length);
+ expect(JSON.stringify(hold)).not.toContain(WIRED_PENDING_LINE);
+ // A hold destroys nothing, so it mints nothing.
+ expect(await h.checkpointShas()).toHaveLength(0);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('converged doc: no divergence, so neither arm runs', async () => {
+ const h = await createStoreHarness('hold-converged');
+ try {
+ // The rig seeds and settles its base, so fragment and Y.Text agree.
+ await h.storeDirect();
+
+ expect(getMetrics().persistenceDeferHold).toBe(0);
+ expect(getMetrics().persistenceReconcileLoss).toBe(0);
+ expect(await h.checkpointShas()).toHaveLength(0);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('pending fragment-only content is held, not repaired, and never mints', async () => {
+ const h = await createStoreHarness('hold-pending');
+ try {
+ // A fragment line in neither Y.Text nor the witness is exactly what the
+ // defer guard protects; the store boundary must tolerate it the same way
+ // rather than churning a repair that destroys it.
+ h.stagePendingDivergence();
+
+ await h.storeDirect();
+ await h.storeDirect();
+ await h.storeDirect();
+
+ // Y.Text bytes land verbatim on every write-back...
+ expect(h.diskBytes()).toBe(PENDING_YTEXT_MD);
+ // ...the pending line stays live in the fragment...
+ expect(h.wired.serializeFragment()).toContain(PENDING_NOVEL_LINE);
+ // ...and the arm holds every time rather than repairing over it.
+ expect(getMetrics().persistenceDeferHold).toBe(3);
+ expect(getMetrics().persistenceReconcileLoss).toBe(0);
+ expect(await h.checkpointShas()).toHaveLength(0);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('the wikilink-emphasis construct round-trips clean: neither arm fires', async () => {
+ const h = await createStoreHarness('roundtrip-wikilink');
+ try {
+ // The field-reported construct that used to be the live hold trigger.
+ // The bridge now preserves marks on inline leaves, so the fragment view
+ // matches Y.Text and a store must be a plain converged write: no hold,
+ // no checkpoint, bytes verbatim. Guards the round-trip against
+ // re-regression from either side.
+ h.wired.rig.seedSource(WIKILINK_EMPHASIS_SOURCE);
+ expect(h.wired.serializeFragment()).toContain('**[[a]]**');
+
+ await h.storeDirect();
+
+ expect(h.diskBytes()).toContain('**[[a]]**');
+ expect(getMetrics().persistenceDeferHold).toBe(0);
+ expect(getMetrics().persistenceReconcileLoss).toBe(0);
+ expect(await h.checkpointShas()).toHaveLength(0);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('floor: a stale-fragment divergence checkpoints the fragment view, then repairs', async () => {
+ const h = await createStoreHarness('floor-stale');
+ try {
+ h.stageStaleFragment();
+
+ await h.storeDirect();
+
+ expect(getMetrics().persistenceDeferHold).toBe(0);
+ expect(getMetrics().persistenceReconcileLoss).toBe(1);
+ // The repair ran: the fragment converged to Y.Text.
+ expect(h.wired.serializeFragment()).not.toContain(STALE_FRAGMENT_ONLY_LINE);
+ expect(h.diskBytes()).toBe(h.wired.ytextString());
+
+ const [sha] = await awaitMints(h, 1);
+ expect(sha).toBeDefined();
+ expect(getMetrics().persistenceReconcileLossCheckpointCreated).toBe(1);
+
+ // The anchor holds the fragment view the rebuild destroyed, reachable as
+ // an ordinary restorable timeline row.
+ const blob = (await shadowGit(h.shadow).raw('show', `${sha}:${h.docName}`)).toString();
+ expect(blob).toContain(STALE_FRAGMENT_ONLY_LINE);
+ const hist = await getDocumentHistory(h.shadow, { docName: h.docName }, '');
+ const row = hist.entries.find((e) => e.sha === sha);
+ expect(row?.checkpoint?.kind).toBe('persistence-reconcile-loss');
+ expect(row?.checkpoint?.metadata).toEqual({ atRiskLines: 1, witnessAvailable: true });
+
+ const writes = (await h.readRing()).filter(
+ (e) => e.event === 'checkpoint-write' && e.site === 'persistence-prewrite',
+ );
+ expect(writes.some((e) => e.checkpointSha === sha)).toBe(true);
+ expect(writes.every((e) => e.lostLen === STALE_FRAGMENT_ONLY_LINE.length)).toBe(true);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('floor: an unchanged repeat divergence repairs again but mints no second anchor', async () => {
+ const h = await createStoreHarness('floor-dedup');
+ try {
+ h.stageStaleFragment();
+ await h.storeDirect();
+ const [firstSha] = await awaitMints(h, 1);
+ expect(firstSha).toBeDefined();
+
+ // The same divergence re-presents, exactly as a structurally re-derived
+ // one would on the next write-back.
+ h.stageStaleFragment();
+ await h.storeDirect();
+
+ // The repair arm ran both times — the fragment converged again...
+ expect(getMetrics().persistenceReconcileLoss).toBe(2);
+ expect(h.wired.serializeFragment()).not.toContain(STALE_FRAGMENT_ONLY_LINE);
+ // ...but only the first trip minted. Retention caps bound the ref count;
+ // they do not stop a spammer from evicting its own useful anchors.
+ expect(getMetrics().persistenceReconcileLossDeduped).toBe(1);
+ expect(getMetrics().persistenceReconcileLossCheckpointCreated).toBe(1);
+ // Negative bound: give a second mint every chance to appear, then assert
+ // the ref set never grew.
+ expect(await awaitMints(h, 2)).toEqual([firstSha]);
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('no witness: observers detached, so the arm falls back to repair with the floor wired', async () => {
+ const h = await createStoreHarness('floor-no-witness');
+ try {
+ h.stagePendingDivergence();
+ // Detaching drops the doc's published witness, so the tolerance cannot be
+ // evaluated at all. The floor goes under that fallback rather than letting
+ // the checker skip blind — even for a shape the hold would tolerate when
+ // the witness is available.
+ h.wired.rig.cleanup();
+
+ await h.storeDirect();
+
+ expect(getMetrics().persistenceDeferHold).toBe(0);
+ expect(getMetrics().persistenceReconcileLoss).toBe(1);
+ const [sha] = await awaitMints(h, 1);
+ expect(sha).toBeDefined();
+ const hist = await getDocumentHistory(h.shadow, { docName: h.docName }, '');
+ const row = hist.entries.find((e) => e.sha === sha);
+ expect(row?.checkpoint?.metadata).toEqual({ atRiskLines: 1, witnessAvailable: false });
+ } finally {
+ await h.cleanup();
+ }
+ });
+
+ test('serialize throw: no fragment view exists, so neither arm may fire', async () => {
+ // A manager whose serialize throws is the staged condition itself — the
+ // pre-write check then holds no fragment-side view to evaluate the
+ // tolerance against or to checkpoint. A skip here would silently swallow
+ // the serialize failure.
+ const throwingManager = new MarkdownManager({ extensions: sharedExtensions });
+ vi.spyOn(throwingManager, 'serialize').mockImplementation(() => {
+ throw new Error('schema rejection');
+ });
+ const h = await createStoreHarness('throw-arm', { mdManager: throwingManager });
+ try {
+ h.stageDeferredKeystroke();
+
+ await h.storeDirect();
+
+ expect(getMetrics().persistenceSanityCheckSerializeFailures).toBe(1);
+ expect(getMetrics().persistenceDeferHold).toBe(0);
+ expect(getMetrics().persistenceReconcileLoss).toBe(0);
+ expect(await h.checkpointShas()).toHaveLength(0);
+ // The pre-existing path is what runs: the fragment is rebuilt from Y.Text
+ // and the keystroke leaves it. That outcome is what the hold arms fix for
+ // an evaluable divergence; here it pins that the skip does NOT reach into
+ // a branch where the tolerance is unknowable.
+ expect(h.wired.serializeFragment()).not.toContain(WIRED_PENDING_LINE);
+ expect(h.diskBytes()).toBe(h.wired.ytextString());
+ } finally {
+ await h.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.ts
index d22ab2382..1a34d7b34 100644
--- a/packages/server/src/persistence.ts
+++ b/packages/server/src/persistence.ts
@@ -27,8 +27,10 @@ import {
DOCUMENT_OPEN_BYTE_LIMIT,
fnv1aDigest,
formatFileSize,
+ fragmentHoldsPendingContent,
normalizeBridge,
type Principal,
+ pendingContentLines,
prependFrontmatter,
stripFrontmatter,
} from '@inkeep/open-knowledge-core';
@@ -70,6 +72,11 @@ import { contentHash, registerWrite } from './file-watcher.ts';
import { tracedMkdir, tracedRename, tracedUnlinkSync, tracedWriteFile } from './fs-traced.ts';
import { errnoCode } from './http/handler-utils.ts';
import { getLogger } from './logger.ts';
+import {
+ LOSS_EVENT_CHECKPOINT_WRITE,
+ LOSS_EVENT_PERSISTENCE_HOLD,
+ type LossCaptureRing,
+} from './loss-capture.ts';
import {
loadManagedArtifactDoc,
type ManagedArtifactCtx,
@@ -86,8 +93,12 @@ import {
incrementDeferredStoreFailures,
incrementGitAutoSaveFailure,
incrementGitWriterCommitFailure,
+ incrementPersistenceDeferHold,
incrementPersistenceDiskWrite,
incrementPersistenceForceFlushDuringBurst,
+ incrementPersistenceReconcileLoss,
+ incrementPersistenceReconcileLossCheckpointCreated,
+ incrementPersistenceReconcileLossDeduped,
incrementPersistenceReconciliationFailures,
incrementPersistenceSanityCheckSerializeFailures,
incrementPersistenceSkipNonQuiescent,
@@ -96,7 +107,7 @@ import {
import { toPosix } from './path-utils.ts';
import { classifyDuplication } from './persistence-tripwire.ts';
import { backfillRenameLogCommitSha, getOrLoadRenameLogIndex } from './rename-log.ts';
-import { OBSERVER_SYNC_ORIGIN } from './server-observers.ts';
+import { getConvergedFragmentWitness, OBSERVER_SYNC_ORIGIN } from './server-observers.ts';
import type { ShadowRef, WriterIdentity } from './shadow-repo.ts';
import {
buildWipTree,
@@ -105,6 +116,7 @@ import {
FILE_SYSTEM_WRITER,
GIT_UPSTREAM_WRITER,
SERVICE_WRITER,
+ saveInMemoryCheckpoint,
shadowGit,
} from './shadow-repo.ts';
import { getMeter, setActiveSpanAttributes, withSpan } from './telemetry.ts';
@@ -386,6 +398,13 @@ export interface PersistenceOptions {
* without coupling the test contract to the function's stack frame).
*/
mdManager?: MarkdownManager;
+ /**
+ * Accessor for the content-free loss ring. Closure-deferred because the ring
+ * is constructed later in boot than the persistence extension; `undefined`
+ * when loss capture is disabled or in rigs that wire no diagnostics. The
+ * pre-write divergence arms record their hold / checkpoint breadcrumbs here.
+ */
+ getLossRing?: () => Pick<LossCaptureRing, 'record'> | undefined;
/**
* Probe into the removal cache (`RecentlyRemovedDocs`). Diagnostic only:
* when a store is about to write a doc the cache still records as
@@ -1087,6 +1106,130 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
}
}
+ /**
+ * The pre-write divergence arms' ring `site`, shared by the hold breadcrumb
+ * and the floor checkpoint so a bundle reader can pair them on one doc.
+ */
+ const PERSISTENCE_PREWRITE_SITE = 'persistence-prewrite';
+
+ /**
+ * Last floor-checkpoint payload minted per document. Some documents diverge
+ * at this boundary on EVERY write-back — a construct whose fragment view is
+ * lossy against its own Y.Text bytes re-trips the check for as long as the
+ * doc exists — and an un-deduped mint would let that one doc evict every
+ * other recovery anchor sharing its retention bucket. Retention caps bound
+ * the ref count but cannot stop a spammer from evicting its own useful
+ * anchor, so the dedup is the first line and the cap the second. Keyed by
+ * Y.Doc identity so the entry dies with the doc.
+ */
+ const lastFloorCheckpointPayload = new WeakMap<Y.Doc, string>();
+
+ /**
+ * Breadcrumb for a tolerated divergence: the whole fragment/Y.Text delta is
+ * content the derive-timing guard is holding, so the fragment is left intact
+ * and the keystroke survives. Content-free — a byte length of the at-risk
+ * lines, never the lines.
+ */
+ function recordDeferHold(documentName: string, pendingLines: readonly string[]): void {
+ incrementPersistenceDeferHold();
+ void options?.getLossRing?.()?.record({
+ event: LOSS_EVENT_PERSISTENCE_HOLD,
+ docName: documentName,
+ writerId: null,
+ direction: 'b',
+ site: PERSISTENCE_PREWRITE_SITE,
+ lostLen: pendingLines.reduce((n, line) => n + line.length, 0),
+ });
+ }
+
+ /**
+ * Checkpoint-before-repair for a divergence the derive-timing tolerance does
+ * NOT cover. `fragmentMarkdown` is the fragment-side view the imminent
+ * `reconcileFragmentNow` destroys, so it is the restore anchor; Y.Text goes
+ * to disk either way. Fire-and-forget, and the repair is never gated on it —
+ * the dedup suppresses the MINT, not the rebuild.
+ *
+ * `witnessAvailable: false` records a distinguishable trip class: observers
+ * detached, so the tolerance could not be evaluated at all and the arm fell
+ * back to rebuilding. Prior art (`reports/tolerated-divergence-hygiene-layers/REPORT.md`)
+ * puts the floor under exactly that fallback rather than skipping blind.
+ */
+ function checkpointBeforeReconcile(
+ document: Y.Doc,
+ documentName: string,
+ fragmentMarkdown: string,
+ ytextMarkdown: string,
+ witnessAvailable: boolean,
+ ): void {
+ incrementPersistenceReconcileLoss();
+ if (lastFloorCheckpointPayload.get(document) === fragmentMarkdown) {
+ incrementPersistenceReconcileLossDeduped();
+ 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.
+ lastFloorCheckpointPayload.set(document, fragmentMarkdown);
+ const atRisk = pendingContentLines(fragmentMarkdown, ytextMarkdown, '');
+ const lostLen = atRisk.reduce((n, line) => n + line.length, 0);
+ const ring = options?.getLossRing?.();
+ const shadow = shadowRef?.current;
+ if (!shadow) {
+ void ring?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName: documentName,
+ writerId: null,
+ direction: 'b',
+ site: PERSISTENCE_PREWRITE_SITE,
+ lostLen,
+ });
+ return;
+ }
+ const branch = getCurrentBranch?.() ?? 'main';
+ queueMicrotask(() => {
+ saveInMemoryCheckpoint(shadow, contentRoot, {
+ kind: 'persistence-reconcile-loss',
+ docName: documentName,
+ contents: fragmentMarkdown,
+ label: `Before persistence fragment rebuild @ ${new Date().toISOString()}`,
+ branch,
+ metadata: { atRiskLines: atRisk.length, witnessAvailable },
+ })
+ .then((sha) => {
+ incrementPersistenceReconcileLossCheckpointCreated();
+ void ring?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName: documentName,
+ writerId: null,
+ direction: 'b',
+ site: PERSISTENCE_PREWRITE_SITE,
+ lostLen,
+ checkpointSha: sha,
+ });
+ console.warn(
+ JSON.stringify({
+ event: 'persistence-reconcile-loss-checkpoint-created',
+ docName: documentName,
+ sha,
+ kind: 'persistence-reconcile-loss',
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ })
+ .catch((checkpointErr: unknown) => {
+ if (lastFloorCheckpointPayload.get(document) === fragmentMarkdown) {
+ lastFloorCheckpointPayload.delete(document);
+ }
+ const e =
+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
+ log.warn(
+ { documentName, err: e },
+ '[persistence] reconcile-loss checkpoint write failed',
+ );
+ });
+ });
+ }
+
// 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;
@@ -1275,9 +1418,16 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
// serialize failure as definite divergence, queue fragment
// reconciliation, and proceed to write Y.Text bytes verbatim.
let normalizeEqual: boolean;
+ // Hoisted out of the `try` because its ABSENCE is load-bearing. The
+ // divergence arms below both need the fragment-side view — one to
+ // evaluate the derive-timing tolerance against it, the other to
+ // checkpoint it — and a serialize throw leaves neither possible. Only
+ // `null` distinguishes "no divergence tolerance was evaluated because
+ // there was nothing to evaluate" from "the tolerance said no".
+ let fragmentMarkdown: string | null = null;
try {
const fragmentBody = mgr.serialize(json);
- const fragmentMarkdown = prependFrontmatter(frontmatter, fragmentBody);
+ fragmentMarkdown = prependFrontmatter(frontmatter, fragmentBody);
normalizeEqual = assertBridgeInvariant(markdown, fragmentMarkdown, {
site: 'persistence',
docName: documentName,
@@ -1316,17 +1466,64 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
{ err, documentName },
`[persistence] Sanity-check serialize failed for ${documentName}; proceeding with ytext bytes`,
);
+ // The assertion may have thrown AFTER the assignment above; a
+ // fragment view that could not be validated is not a view this
+ // function may act on.
+ fragmentMarkdown = null;
normalizeEqual = false;
}
if (!normalizeEqual) {
// Watchdog already emitted the rate-limited telemetry +
// incremented `bridgeInvariantViolations` (or its suppressed
// counterpart) — or, when serialize itself threw, the warn above
- // is the single signal. Reconcile the fragment synchronously so
- // it converges to ytext before the disk write below proceeds with
- // ytext bytes (Y.Text is the contract's source-of-truth per
- // precedent #38).
- reconcileFragmentNow(document, body, documentName);
+ // is the single signal.
+ //
+ // Three arms, discriminated by what is knowable at this instant:
+ //
+ // 1. The whole divergence is content the derive-timing guard is
+ // holding in the fragment (a WYSIWYG keystroke not yet in
+ // Y.Text). Rebuilding would destroy it with no checkpoint and no
+ // ring event, because both observers self-skip the
+ // OBSERVER_SYNC_ORIGIN write. HOLD the fragment instead: Y.Text
+ // still goes to disk below, so this defers the fragment's
+ // convergence, never the durability of the user's bytes. The
+ // predicate is the SAME pure call Observer B's guard makes, over
+ // the witness the observer publishes — a tolerated divergence in
+ // the shape prior art converges on, with no checker-side
+ // freshness or age bound (the one shipped wall-clock bound on
+ // this pattern was removed as unmaintainable). See
+ // `reports/tolerated-divergence-hygiene-layers/REPORT.md`.
+ // 2. Any other divergence, including one whose tolerance could not
+ // be evaluated because observers publish no witness: checkpoint
+ // the fragment view FIRST, then repair. Checkpoint-before-repair
+ // keeps the destroyed view restorable.
+ // 3. Serialize threw: no fragment view exists, so neither arm can
+ // run. Left exactly as it was — the repair, and the
+ // serialize-failure counter above as its only signal. A skip here
+ // would silently swallow a serialize failure.
+ const witness =
+ fragmentMarkdown === null ? undefined : getConvergedFragmentWitness(document);
+ if (
+ fragmentMarkdown !== null &&
+ witness !== undefined &&
+ fragmentHoldsPendingContent(fragmentMarkdown, markdown, witness)
+ ) {
+ recordDeferHold(documentName, pendingContentLines(fragmentMarkdown, markdown, witness));
+ } else {
+ if (fragmentMarkdown !== null) {
+ checkpointBeforeReconcile(
+ document,
+ documentName,
+ fragmentMarkdown,
+ markdown,
+ witness !== undefined,
+ );
+ }
+ // Reconcile the fragment synchronously so it converges to ytext
+ // before the disk write below proceeds with ytext bytes (Y.Text is
+ // the contract's source-of-truth per precedent #38).
+ reconcileFragmentNow(document, body, documentName);
+ }
}
// Skip the write when the serialized output matches the load-time
diff --git a/packages/server/src/pre-drain-converged-gate.test.ts b/packages/server/src/pre-drain-converged-gate.test.ts
new file mode 100644
index 000000000..3ff456491
--- /dev/null
+++ b/packages/server/src/pre-drain-converged-gate.test.ts
@@ -0,0 +1,99 @@
+/**
+ * The pre-drain flushes CONTENT, never nothing.
+ *
+ * `fragmentMutatedSinceConverge` says the fragment MOVED since the last
+ * convergence — not that anything is still un-propagated. A freshness-suppressed
+ * Observer-A drain that nonetheless propagated everything leaves that flag set
+ * over a fully-converged document. The splice model then returns the trailing
+ * region of two structurally-identical bodies, and applying it is a delete +
+ * insert of the bytes already there: byte-neutral, but real CRDT tombstone and
+ * struct churn on the user's live document, replicated to every peer, for no
+ * content gain.
+ *
+ * Byte equality cannot see that — the assertion has to be on the CRDT clock.
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import * as Y from 'yjs';
+import { createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+import { getPreDrainController } from './server-observers.ts';
+
+const BASE = '# Guide\n\nIntro paragraph.\n\nSecond paragraph.\n';
+
+/** The local client's Yjs clock — advances on every struct this doc creates. */
+function localClock(doc: Y.Doc): number {
+ return Y.decodeStateVector(Y.encodeStateVector(doc)).get(doc.clientID) ?? 0;
+}
+
+describe('pre-drain already-converged gate', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ test('a stale dirty flag over a converged doc skips instead of splicing identity bytes', () => {
+ const rig = createBridgeRaceRig({ docName: 'converged-gate.md' });
+ try {
+ rig.seedSource(BASE);
+ rig.settle(1);
+
+ // Freshness-hot window + a byte-neutral fragment mutation: Observer A runs
+ // freshness-SUPPRESSED, so it does not clear the convergence flag even
+ // though nothing is left un-propagated.
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing note.\n'));
+ rig.forceARound({ advanceFreshness: false });
+
+ const bytesBefore = rig.ytext.toString();
+ const clockBefore = localClock(rig.doc);
+
+ const verdict = getPreDrainController(rig.doc)?.preDrain({
+ kind: 'agent-write',
+ composedBody: `${bytesBefore}\nAgent appended paragraph.\n`,
+ writeKind: 'append',
+ });
+
+ // Nothing to flush: the drain's modelled rewrite replaces the region with
+ // the bytes already there.
+ expect(verdict?.preDrain).toBe(false);
+ expect(verdict?.reason).toBe('skip-already-converged');
+ // ...and no struct was created on the user's document.
+ expect(rig.ytext.toString()).toBe(bytesBefore);
+ expect(localClock(rig.doc)).toBe(clockBefore);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('a genuinely pending keystroke still flushes', () => {
+ const rig = createBridgeRaceRig({ docName: 'converged-gate-live.md' });
+ try {
+ const componentBase =
+ '## Guide\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n\nTail paragraph.\n';
+ rig.editFragment(componentBase);
+ rig.settle(1);
+
+ // The un-propagated-keystroke shape: the fragment advances past its
+ // stamped source while a recent external write keeps freshness hot.
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing note.\n'));
+ rig.echoFragmentEdit(rig.ytext.toString(), 'Step one bod', 'Step one body.', {
+ advanceFreshness: false,
+ });
+ expect(rig.ytext.toString()).not.toContain('Step one body.');
+
+ const verdict = getPreDrainController(rig.doc)?.preDrain({
+ kind: 'agent-write',
+ composedBody: `${rig.ytext.toString()}\nAgent appended paragraph.\n`,
+ writeKind: 'append',
+ });
+
+ // The gate must not swallow a real flush.
+ expect(verdict?.preDrain).toBe(true);
+ expect(rig.ytext.toString()).toContain('Step one body.');
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/pre-drain-corpus.test-helper.ts b/packages/server/src/pre-drain-corpus.test-helper.ts
new file mode 100644
index 000000000..8888371fc
--- /dev/null
+++ b/packages/server/src/pre-drain-corpus.test-helper.ts
@@ -0,0 +1,189 @@
+/**
+ * Corpus rig for the pre-drain discriminator: stage a same-block / cross-block
+ * concurrency scenario through the REAL agent-write and UndoManager paths, then
+ * run the read-only discriminator on the staged pre-propagation state.
+ *
+ * Fidelity: a real `AgentSessionManager` session over a real `Y.Doc` produces a
+ * real per-session `Y.UndoManager` and real StackItems; `applyAgentMarkdownWrite`
+ * is the production write spine (self-contained paired write — it derives the
+ * fragment itself, so no propagation observer is needed for coherence). The
+ * un-propagated window (fragment holds content Y.Text lacks) is held open simply
+ * by not attaching a propagation observer: the discriminator is read-only and
+ * needs only the staged pre-propagation inputs it would see in production right
+ * before the paired transact runs. It is imported by sibling `*.test.ts` files;
+ * it is not itself a test.
+ */
+
+import type { Document } from '@hocuspocus/server';
+import {
+ type MarkdownManager,
+ sharedExtensions,
+ stripFrontmatter,
+} from '@inkeep/open-knowledge-core';
+import { getSchema, type JSONContent } from '@tiptap/core';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import * as Y from 'yjs';
+import type { YjsStackItemShape } from './agent-activity.ts';
+import {
+ type AgentDirectConnection,
+ AgentSessionManager,
+ applyAgentMarkdownWrite,
+} from './agent-sessions.ts';
+import { mdManager as productionMdManager } from './md-manager.ts';
+import {
+ type AgentWritePosition,
+ type PreDrainVerdict,
+ planPreDrain,
+} from './pre-drain-discriminator.ts';
+
+const schema = getSchema(sharedExtensions);
+const EMPTY_UPDATE_META = () => ({ mapping: new Map(), isOMark: new Map() });
+
+// A non-paired, non-session origin for the staged WYSIWYG keystroke: not tracked
+// by the session UndoManager and not a paired-write origin, so it lands
+// fragment-only (a client edit the propagation observer has not yet drained).
+const USER_KEYSTROKE_ORIGIN = { context: { origin: 'corpus-user-keystroke' } };
+
+function createMockHocuspocus(ydoc: Y.Doc, docName: string) {
+ const doc = {
+ name: docName,
+ awareness: { setLocalState() {}, setLocalStateField() {} },
+ getText: (name: string) => ydoc.getText(name),
+ getMap: (name: string) => ydoc.getMap(name),
+ getXmlFragment: (name: string) => ydoc.getXmlFragment(name),
+ transact: (fn: () => void, origin?: unknown) => ydoc.transact(fn, origin),
+ on: ydoc.on.bind(ydoc),
+ off: ydoc.off.bind(ydoc),
+ } as unknown as Document;
+ const dc = {
+ document: doc,
+ disconnect: async () => {},
+ isDisconnected: () => false,
+ transact: () => {},
+ } as unknown as AgentDirectConnection;
+ return {
+ openDirectConnection: async (): Promise<AgentDirectConnection> => dc,
+ };
+}
+
+export interface DiscriminatorRig {
+ readonly doc: Y.Doc;
+ readonly mdManager: MarkdownManager;
+ /** Canonical markdown of the current XmlFragment (body only in the corpus). */
+ serializeFragment(): string;
+ /** Real agent write through `applyAgentMarkdownWrite` under the session origin. */
+ agentWrite(markdown: string, position: AgentWritePosition): void;
+ /** Stage a fragment-only WYSIWYG edit by mutating the current fragment md. */
+ stageKeystroke(mutate: (fragmentMd: string) => string): void;
+ /** Discriminate in front of an agent undo of the top StackItem. */
+ discriminateUndo(): PreDrainVerdict;
+ /** Raw undo-discrimination inputs, for span-level inspection. */
+ undoInputs(): {
+ body: string;
+ fmPrefixLen: number;
+ ytext: Y.Text;
+ stackItem: YjsStackItemShape;
+ fragmentPmJson: JSONContent;
+ };
+ /** Discriminate in front of a further agent write. */
+ discriminateAgentWrite(payload: string, position: AgentWritePosition): PreDrainVerdict;
+ cleanup(): Promise<void>;
+}
+
+/** Seed both CRDTs coherently, open a real session, and expose the rig. */
+export async function createDiscriminatorRig(baseMd: string): Promise<DiscriminatorRig> {
+ const docName = `corpus-${Math.round(performance.now())}-${baseMd.length}`;
+ const ydoc = new Y.Doc();
+ const frag = ydoc.getXmlFragment('default');
+ const ytext = ydoc.getText('source');
+ // Seed the canonical settled form (trailing newline included), the state a
+ // real doc rests in after its last drain — so the agent write's incremental
+ // diff matches production instead of re-authoring the final line over a
+ // missing trailing newline.
+ const seedMd =
+ baseMd === '' ? '' : productionMdManager.serialize(productionMdManager.parse(baseMd));
+ ydoc.transact(() => ytext.insert(0, seedMd), 'seed');
+ ydoc.transact(() => {
+ updateYFragment(
+ ydoc,
+ frag,
+ schema.nodeFromJSON(productionMdManager.parse(seedMd)),
+ EMPTY_UPDATE_META(),
+ );
+ }, 'seed');
+
+ const manager = new AgentSessionManager(createMockHocuspocus(ydoc, docName) as never);
+ const session = await manager.getSession(docName, 'agent-corpus');
+ const doc = session.dc.document;
+
+ const serializeFragment = (): string =>
+ productionMdManager.serialize(yXmlFragmentToProseMirrorRootNode(frag, schema).toJSON());
+
+ const bodyState = (): { body: string; fmPrefixLen: number } => {
+ const full = ytext.toString();
+ const { body } = stripFrontmatter(full);
+ return { body, fmPrefixLen: full.length - body.length };
+ };
+ const fragmentJson = () => yXmlFragmentToProseMirrorRootNode(frag, schema).toJSON();
+
+ const rig: DiscriminatorRig = {
+ doc: ydoc,
+ mdManager: productionMdManager,
+ serializeFragment,
+ agentWrite: (markdown, position) => {
+ doc.transact(() => {
+ applyAgentMarkdownWrite(doc, markdown, position);
+ }, session.origin);
+ },
+ stageKeystroke: (mutate) => {
+ const next = mutate(serializeFragment());
+ ydoc.transact(() => {
+ updateYFragment(
+ ydoc,
+ frag,
+ schema.nodeFromJSON(productionMdManager.parse(next)),
+ EMPTY_UPDATE_META(),
+ );
+ }, USER_KEYSTROKE_ORIGIN);
+ },
+ discriminateUndo: () => {
+ const { body, fmPrefixLen } = bodyState();
+ const stack = session.um.undoStack as unknown as YjsStackItemShape[];
+ const stackItem = stack[stack.length - 1];
+ return planPreDrain({
+ pendingDirty: true,
+ body,
+ fragmentPmJson: fragmentJson(),
+ witnessMatched: true,
+ fmPrefixLen,
+ op: { kind: 'agent-undo', ytext, stackItem },
+ mdManager: productionMdManager,
+ }).verdict;
+ },
+ undoInputs: () => {
+ const { body, fmPrefixLen } = bodyState();
+ const stack = session.um.undoStack as unknown as YjsStackItemShape[];
+ return {
+ body,
+ fmPrefixLen,
+ ytext,
+ stackItem: stack[stack.length - 1],
+ fragmentPmJson: fragmentJson(),
+ };
+ },
+ discriminateAgentWrite: (_payload, position) => {
+ const { body, fmPrefixLen } = bodyState();
+ return planPreDrain({
+ pendingDirty: true,
+ body,
+ fragmentPmJson: fragmentJson(),
+ witnessMatched: true,
+ fmPrefixLen,
+ op: { kind: 'agent-write', writeKind: position },
+ mdManager: productionMdManager,
+ }).verdict;
+ },
+ cleanup: () => manager.closeAll(),
+ };
+ return rig;
+}
diff --git a/packages/server/src/pre-drain-discriminator.test.ts b/packages/server/src/pre-drain-discriminator.test.ts
new file mode 100644
index 000000000..2e3609f4f
--- /dev/null
+++ b/packages/server/src/pre-drain-discriminator.test.ts
@@ -0,0 +1,487 @@
+/**
+ * Pre-drain discriminator — pure decision core, span extractors, and the
+ * same-block scenario corpus.
+ *
+ * The corpus stages each scenario through the real `AgentSessionManager` /
+ * `applyAgentMarkdownWrite` paths against a real UndoManager, then runs the
+ * read-only discriminator on the staged pre-propagation state. Its measured
+ * harm labels are the pinned ground truth: any scenario labelled harmful that
+ * the discriminator would admit to pre-drain fails the suite. The line-hunk
+ * localizer is refuted on the one non-contiguous shape it leaks (the splice
+ * model routes it to checkpoint; hunks admit it).
+ */
+import { diffLinesFast, type MarkdownManager } from '@inkeep/open-knowledge-core';
+import { describe, expect, it } from 'vitest';
+import { computeMapDrivenBodySplice } from './map-driven-splice.ts';
+import { mdManager } from './md-manager.ts';
+import { createDiscriminatorRig, type DiscriminatorRig } from './pre-drain-corpus.test-helper.ts';
+import {
+ type BodySpan,
+ classifyPreDrain,
+ extractComposeTargetSpan,
+ type PreDrainVerdict,
+ planPreDrain,
+} from './pre-drain-discriminator.ts';
+
+/** The drain's rewrite RANGE — the classifier's input, from the shared localizer. */
+function drainRewriteRange(
+ body: string,
+ fragmentPmJson: ReturnType<typeof mdManager.parse>,
+): BodySpan | null {
+ const splice = computeMapDrivenBodySplice(body, fragmentPmJson, mdManager);
+ return splice === null ? null : { start: splice.spliceStart, end: splice.spliceEnd };
+}
+
+/** A MarkdownManager stand-in that throws if the expensive localizer is reached. */
+const throwingMdManager = {
+ parseToMdast: () => {
+ throw new Error('localizer reached: parseToMdast should not run');
+ },
+ serialize: () => {
+ throw new Error('localizer reached: serialize should not run');
+ },
+} as unknown as MarkdownManager;
+
+const FIVE_PARA = [
+ 'para one alpha',
+ 'para two beta',
+ 'para three gamma',
+ 'para four delta',
+ 'para five epsilon',
+].join('\n\n');
+
+/** The canonical settled form an agent's full-body payload is composed against. */
+const canon = (md: string): string => mdManager.serialize(mdManager.parse(md));
+
+interface Scenario {
+ readonly id: string;
+ /** The spike's measured Outcome label. */
+ readonly harmful: boolean;
+ /** The spike's `splice+graze` classification (true = admitted to pre-drain). */
+ readonly expectedPreDrain: boolean;
+ readonly base: string;
+ /** Stage the scenario on the rig and return the discriminator verdict. */
+ readonly stage: (rig: DiscriminatorRig) => PreDrainVerdict;
+}
+
+const SCENARIOS: readonly Scenario[] = [
+ {
+ id: 'U1 pending new paragraph after an agent append',
+ harmful: false,
+ expectedPreDrain: true,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite('agent line', 'append');
+ rig.stageKeystroke((md) => `${md.trimEnd()}\n\nfresh keystroke`);
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U2 keystroke inside the agent-appended line',
+ harmful: true,
+ expectedPreDrain: false,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite('agent line', 'append');
+ rig.stageKeystroke((md) => md.replace('agent line', 'agent XXline'));
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U3 typing in the agent-patched paragraph',
+ harmful: true,
+ expectedPreDrain: false,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite(
+ canon(FIVE_PARA.replace('para two beta', 'para two beta agent-suffix')),
+ 'patch',
+ );
+ rig.stageKeystroke((md) =>
+ md.replace('para two beta agent-suffix', 'para two beta agent-suffix typed'),
+ );
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U4 pending edit two blocks away from the patch target',
+ harmful: false,
+ expectedPreDrain: true,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite(
+ canon(FIVE_PARA.replace('para three gamma', 'para three gamma EDIT')),
+ 'patch',
+ );
+ rig.stageKeystroke((md) => md.replace('para one alpha', 'para one alpha X'));
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U5 pending edit in the adjacent block',
+ harmful: false,
+ expectedPreDrain: true,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite(
+ canon(FIVE_PARA.replace('para three gamma', 'para three gamma EDIT')),
+ 'patch',
+ );
+ rig.stageKeystroke((md) => md.replace('para two beta', 'para two beta X'));
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U6 pending edit in the last paragraph, agent appended after',
+ harmful: false,
+ expectedPreDrain: true,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite('agent line', 'append');
+ rig.stageKeystroke((md) => md.replace('para five epsilon', 'para five epsilon X'));
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U7 non-contiguous pending (first + last), target the middle',
+ harmful: true,
+ expectedPreDrain: false,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite(
+ canon(FIVE_PARA.replace('para three gamma', 'para three gamma EDIT')),
+ 'patch',
+ );
+ rig.stageKeystroke((md) =>
+ md
+ .replace('para one alpha', 'para one alpha X')
+ .replace('para five epsilon', 'para five epsilon X'),
+ );
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U8a empty doc, keystroke inside the agent first block',
+ harmful: true,
+ expectedPreDrain: false,
+ base: '',
+ stage: (rig) => {
+ rig.agentWrite('first block', 'append');
+ rig.stageKeystroke((md) => md.replace('first block', 'first XXblock'));
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U8b empty doc, pending new paragraph after the agent first block',
+ harmful: false,
+ expectedPreDrain: true,
+ base: '',
+ stage: (rig) => {
+ rig.agentWrite('first block', 'append');
+ rig.stageKeystroke((md) => `${md.trimEnd()}\n\nfresh keystroke`);
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U9 target spans two blocks, pending in an adjacent block',
+ harmful: false,
+ expectedPreDrain: true,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite(
+ canon(
+ FIVE_PARA.replace(
+ 'para two beta\n\npara three gamma',
+ 'para two BETA\n\npara three GAMMA',
+ ),
+ ),
+ 'patch',
+ );
+ rig.stageKeystroke((md) => md.replace('para four delta', 'para four delta X'));
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'U10 pending pure-insert between distant blocks',
+ harmful: false,
+ expectedPreDrain: true,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite(
+ canon(FIVE_PARA.replace('para five epsilon', 'para five epsilon EDIT')),
+ 'patch',
+ );
+ rig.stageKeystroke((md) => md.replace('para one alpha', 'para one alpha\n\ninserted para'));
+ return rig.discriminateUndo();
+ },
+ },
+ {
+ id: 'E1 second agent append, pending appended paragraph',
+ harmful: false,
+ expectedPreDrain: true,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.agentWrite('agent line', 'append');
+ rig.stageKeystroke((md) => `${md.trimEnd()}\n\nfresh keystroke`);
+ return rig.discriminateAgentWrite('second agent line', 'append');
+ },
+ },
+ {
+ id: 'E2 agent patch of the paragraph the user is typing in',
+ harmful: false,
+ expectedPreDrain: false,
+ base: FIVE_PARA,
+ stage: (rig) => {
+ rig.stageKeystroke((md) => md.replace('para two beta', 'para two beta typed'));
+ return rig.discriminateAgentWrite(
+ canon(FIVE_PARA.replace('para two beta', 'para two beta AGENT')),
+ 'patch',
+ );
+ },
+ },
+];
+
+async function runScenario(scenario: Scenario): Promise<PreDrainVerdict> {
+ const rig = await createDiscriminatorRig(scenario.base);
+ try {
+ return scenario.stage(rig);
+ } finally {
+ await rig.cleanup();
+ }
+}
+
+describe('cost gate: cheap fail-closed guards short-circuit before the localizer', () => {
+ const baseInput = {
+ body: 'para one\n\npara two',
+ fragmentPmJson: {},
+ fmPrefixLen: 0,
+ mdManager: throwingMdManager,
+ op: { kind: 'agent-write', composedBody: 'x', writeKind: 'prepend' } as const,
+ };
+
+ it('skips a clean paired op without touching the localizer', () => {
+ const { verdict } = planPreDrain({
+ ...baseInput,
+ pendingDirty: false,
+ witnessMatched: true,
+ });
+ expect(verdict).toEqual({ preDrain: false, reason: 'skip-no-pending' });
+ });
+
+ it('fails closed on a witness mismatch without touching the localizer', () => {
+ const { verdict } = planPreDrain({
+ ...baseInput,
+ pendingDirty: true,
+ witnessMatched: false,
+ });
+ expect(verdict).toEqual({ preDrain: false, reason: 'checkpoint-witness-mismatch' });
+ });
+
+ it('fails closed on a missing target without touching the localizer', () => {
+ // A prepend has no measured target span → checkpoint before the parse.
+ const { verdict } = planPreDrain({
+ ...baseInput,
+ pendingDirty: true,
+ witnessMatched: true,
+ });
+ expect(verdict).toEqual({ preDrain: false, reason: 'checkpoint-no-target' });
+ });
+});
+
+describe('same-block discriminator corpus (splice+graze)', () => {
+ it.each(SCENARIOS)('$id → classified as measured', async (scenario) => {
+ const verdict = await runScenario(scenario);
+ expect(verdict.preDrain).toBe(scenario.expectedPreDrain);
+ });
+
+ it('zero-harmful-direction bar: no measured-harmful scenario is admitted to pre-drain', async () => {
+ const harmful = SCENARIOS.filter((s) => s.harmful);
+ for (const scenario of harmful) {
+ const verdict = await runScenario(scenario);
+ expect(
+ verdict.preDrain,
+ `harmful scenario admitted to pre-drain: ${scenario.id} (${verdict.reason})`,
+ ).toBe(false);
+ }
+ });
+});
+
+describe('classifyPreDrain — pure overlap core', () => {
+ const body = 'para one\n\npara two\n\npara three';
+
+ it('admits disjoint splice and target to pre-drain', () => {
+ const verdict = classifyPreDrain({ start: 0, end: 8 }, { start: 20, end: 30 }, body);
+ expect(verdict).toEqual({ preDrain: true, reason: 'pre-drain-disjoint' });
+ });
+
+ it('routes a substantive overlap to checkpoint', () => {
+ const verdict = classifyPreDrain({ start: 0, end: 12 }, { start: 8, end: 18 }, body);
+ expect(verdict).toEqual({ preDrain: false, reason: 'checkpoint-substantive-overlap' });
+ });
+
+ it('admits an all-whitespace intersection via the graze relaxation', () => {
+ // Body bytes 8..10 are the "\n\n" block separator — whitespace only.
+ const verdict = classifyPreDrain({ start: 0, end: 10 }, { start: 8, end: 18 }, body);
+ expect(verdict).toEqual({ preDrain: true, reason: 'pre-drain-whitespace-graze' });
+ });
+
+ it('fails closed on a null splice', () => {
+ expect(classifyPreDrain(null, { start: 0, end: 5 }, body)).toEqual({
+ preDrain: false,
+ reason: 'checkpoint-null-splice',
+ });
+ });
+
+ it('fails closed on a null target', () => {
+ expect(classifyPreDrain({ start: 0, end: 5 }, null, body)).toEqual({
+ preDrain: false,
+ reason: 'checkpoint-no-target',
+ });
+ });
+
+ it('checkpoints a zero-width target strictly inside the rewrite', () => {
+ const verdict = classifyPreDrain({ start: 0, end: 12 }, { start: 6, end: 6 }, body);
+ expect(verdict).toEqual({ preDrain: false, reason: 'checkpoint-substantive-overlap' });
+ });
+
+ it('admits a zero-width target on the rewrite boundary (not strictly inside)', () => {
+ const atStart = classifyPreDrain({ start: 6, end: 12 }, { start: 6, end: 6 }, body);
+ const atEnd = classifyPreDrain({ start: 0, end: 6 }, { start: 6, end: 6 }, body);
+ expect(atStart).toEqual({ preDrain: true, reason: 'pre-drain-disjoint' });
+ expect(atEnd).toEqual({ preDrain: true, reason: 'pre-drain-disjoint' });
+ });
+
+ it('admits a zero-width splice (pure insertion) against a positive target', () => {
+ const verdict = classifyPreDrain({ start: 10, end: 10 }, { start: 0, end: 20 }, body);
+ expect(verdict).toEqual({ preDrain: true, reason: 'pre-drain-disjoint' });
+ });
+});
+
+describe('the drain rewrite range localizes the flush to the changed block', () => {
+ it('localizes an appended block to its region, disjoint from an untouched prefix', () => {
+ const body = 'para one alpha\n\npara two beta';
+ const fragment = mdManager.parse(`${body}\n\npara three gamma`);
+ const splice = drainRewriteRange(body, fragment);
+ expect(splice).not.toBeNull();
+ // The rewrite starts at or after the end of "para two beta" — the appended
+ // block, never the untouched prefix.
+ expect((splice as BodySpan).start).toBeGreaterThanOrEqual(body.indexOf('para two'));
+ });
+
+ it('localizes an edited middle block away from the prefix', () => {
+ const body = 'para one alpha\n\npara two beta\n\npara three gamma';
+ const fragment = mdManager.parse(body.replace('para two beta', 'para two beta EDIT'));
+ const splice = drainRewriteRange(body, fragment);
+ expect(splice).not.toBeNull();
+ const s = splice as BodySpan;
+ // The rewrite covers the middle block, not "para one alpha".
+ expect(s.start).toBeGreaterThan(0);
+ expect(s.end).toBeLessThanOrEqual(body.length);
+ });
+});
+
+describe('extractComposeTargetSpan — agent-write target', () => {
+ const body = 'para one\n\npara two\n\npara three';
+
+ it('targets the trailing seam for an append', () => {
+ const withTrailing = `${body}\n`;
+ const span = extractComposeTargetSpan(withTrailing, 'append');
+ expect(span).toEqual({ start: body.length, end: withTrailing.length });
+ });
+
+ it('fails closed (null) for every non-append position', () => {
+ // `replace` / `patch` are full-body overwrites the plan declines before any
+ // target extraction; `prepend` is unmeasured. None of them may produce a
+ // span the classifier could reason a flush against.
+ expect(extractComposeTargetSpan(body, 'prepend')).toBeNull();
+ expect(extractComposeTargetSpan(body, 'replace')).toBeNull();
+ expect(extractComposeTargetSpan(body, 'patch')).toBeNull();
+ });
+});
+
+describe('full-body-overwrite positions are structurally inert', () => {
+ // A pure block insertion: the drain's splice collapses to the trailing region
+ // and its intersection with a whole-body target is whitespace-only — exactly
+ // the shape the classifier's graze relaxation admits. The position gate has to
+ // decline it BEFORE that arithmetic runs, or the overwrite silently reverts a
+ // keystroke the flush already moved into the write's own loss baseline.
+ const body = 'alpha one\n\nbeta two\n';
+ const pendingFragment = mdManager.parse(`${body}\ngamma three appended\n`);
+
+ for (const position of ['replace', 'patch'] as const) {
+ it(`declines a ${position} write outright`, () => {
+ const plan = planPreDrain({
+ pendingDirty: true,
+ body,
+ fragmentPmJson: pendingFragment,
+ witnessMatched: true,
+ fmPrefixLen: 0,
+ op: { kind: 'agent-write', writeKind: position },
+ mdManager,
+ });
+ expect(plan.verdict.preDrain).toBe(false);
+ expect(plan.verdict.reason).toBe('checkpoint-full-overwrite');
+ expect(plan.splice).toBeNull();
+ });
+ }
+
+ it('still admits the localized append it is meant to serve', () => {
+ const plan = planPreDrain({
+ pendingDirty: true,
+ body,
+ fragmentPmJson: pendingFragment,
+ witnessMatched: true,
+ fmPrefixLen: 0,
+ op: { kind: 'agent-write', writeKind: 'append' },
+ mdManager,
+ });
+ expect(plan.verdict.preDrain).toBe(true);
+ expect(plan.splice).not.toBeNull();
+ });
+});
+
+/**
+ * A test-local line-hunk localizer — the REFUTED substrate. It reports the
+ * removed hunks of the pending content as SEPARATE body ranges, then admits the
+ * flush when none overlaps the target. It exists only to pin the leak below; the
+ * production discriminator never uses it.
+ */
+function hunksOnlyAdmitsFlush(body: string, pendingBody: string, target: BodySpan): boolean {
+ let offset = 0;
+ const removed: BodySpan[] = [];
+ for (const change of diffLinesFast(body, pendingBody)) {
+ if (change.removed) {
+ removed.push({ start: offset, end: offset + change.value.length });
+ offset += change.value.length;
+ } else if (!change.added) {
+ offset += change.value.length;
+ }
+ }
+ const overlaps = (a: BodySpan, b: BodySpan): boolean =>
+ Math.max(a.start, b.start) < Math.min(a.end, b.end);
+ return !removed.some((h) => overlaps(h, target));
+}
+
+describe('hunks-only localizer is refuted (non-contiguous pending leaks)', () => {
+ it('the splice model checkpoints a target between two non-contiguous pending edits while hunks admit it', () => {
+ const body = 'alpha one\n\nbeta two\n\ngamma three\n\ndelta four\n\nepsilon five';
+ // Agent patched the middle block; the target is "gamma three".
+ const target: BodySpan = (() => {
+ const start = body.indexOf('gamma three');
+ return { start, end: start + 'gamma three'.length };
+ })();
+ // Pending edits in the FIRST and LAST blocks (non-contiguous), so the drain's
+ // block splice collapses over-wide across the whole doc.
+ const pendingBody = body
+ .replace('alpha one', 'alpha one EDIT')
+ .replace('epsilon five', 'epsilon five EDIT');
+ const pendingFragment = mdManager.parse(pendingBody);
+ const spliceRange = drainRewriteRange(body, pendingFragment);
+
+ // Splice model: the over-wide rewrite covers "gamma three" → checkpoint.
+ expect(classifyPreDrain(spliceRange, target, body).preDrain).toBe(false);
+ // Hunks-only: the two separate removed hunks miss "gamma three" → admits the
+ // flush — the measured harmful-direction leak the ban exists to prevent.
+ expect(hunksOnlyAdmitsFlush(body, pendingBody, target)).toBe(true);
+ });
+});
diff --git a/packages/server/src/pre-drain-discriminator.ts b/packages/server/src/pre-drain-discriminator.ts
new file mode 100644
index 000000000..335ad0659
--- /dev/null
+++ b/packages/server/src/pre-drain-discriminator.ts
@@ -0,0 +1,394 @@
+/**
+ * Pre-drain discriminator: decide, for a pending fragment-only edit sitting in
+ * front of a paired-intake derive (agent undo or agent write), whether it is
+ * SAFE to flush that edit through Observer A into Y.Text before the paired
+ * transact runs — or whether the flush would launder the operation's own
+ * structs and must be declined in favour of the checkpoint floor.
+ *
+ * The whole module is READ-ONLY: it computes a verdict, mutates nothing. The
+ * flush ("pre-drain") and the checkpoint are the caller's job.
+ *
+ * The decision rests on two spans, both in FM-stripped body byte coordinates:
+ *
+ * - the DRAIN REWRITE range — the contiguous body region Observer A would
+ * delete-and-re-author when it flushes the pending fragment content. This is
+ * exactly what `computeMapDrivenBodySplice` returns on `(currentBody,
+ * fragmentJson)`; the drain applies that same splice, so the modelled range
+ * IS the flush's real rewrite, not an approximation.
+ * - the OPERATION TARGET span — the body region the paired op will touch:
+ * for an undo, the byte ranges the top UndoManager StackItem's structs
+ * occupy in the current Y.Text; for an agent write, the seam / removed-hunk
+ * span its composed body implies.
+ *
+ * If the rewrite range and the target span are disjoint, the flush cannot touch
+ * the op's structs and pre-drain is safe. Any substantive intersection means
+ * the flush would delete-and-re-author bytes the op depends on (undo-defeat,
+ * duplication, seam corruption) — so the discriminator FAILS CLOSED: a null
+ * splice, a witness mismatch, a missing target, or a non-whitespace overlap all
+ * route to checkpoint, never to pre-drain. Over-wide is always the safe
+ * direction — more checkpointing, never more flushing.
+ *
+ * Localizer choice is load-bearing and non-substitutable. A line-hunk localizer
+ * (`diffLinesFast` over the pending content) reports the MINIMAL changed lines,
+ * not the drain's rewrite: when pending edits are non-contiguous the drain's
+ * block splice collapses over-wide across the untouched blocks between them and
+ * launders a target that sits in that gap, while the hunks — being separate —
+ * see no overlap and wrongly admit the flush. The splice model is the only
+ * localizer that sees what the drain will actually rewrite.
+ */
+
+import type { MarkdownManager } from '@inkeep/open-knowledge-core';
+import type { JSONContent } from '@tiptap/core';
+import type * as Y from 'yjs';
+import { ContentString } from 'yjs';
+import { walkYTextItems, type YjsStackItemShape } from './agent-activity.ts';
+import { computeMapDrivenBodySplice, type MapDrivenSplice } from './map-driven-splice.ts';
+
+/**
+ * A half-open byte range `[start, end)` in FM-stripped body coordinates.
+ * `start === end` is a zero-width point — an insertion anchor or a tombstone's
+ * collapse position, which carries no width but a location.
+ */
+export interface BodySpan {
+ readonly start: number;
+ readonly end: number;
+}
+
+export type AgentWritePosition = 'append' | 'prepend' | 'replace' | 'patch';
+
+/**
+ * Why the discriminator reached its decision. `preDrain` is derivable from the
+ * reason, but callers key their routing (flush / checkpoint / no-op) off
+ * `preDrain` and use the reason for the loss-ring's content-free correlation.
+ *
+ * The `skip-*` reasons mean there was nothing to flush (no checkpoint owed); the
+ * `checkpoint-*` reasons mean the flush was DECLINED and the paired write's
+ * checkpoint floor owns the content instead.
+ */
+type PreDrainReason =
+ | 'skip-disabled'
+ | 'skip-no-pending'
+ | 'skip-already-converged'
+ | 'checkpoint-full-overwrite'
+ | 'checkpoint-witness-mismatch'
+ | 'checkpoint-null-splice'
+ | 'checkpoint-no-target'
+ | 'checkpoint-substantive-overlap'
+ | 'pre-drain-disjoint'
+ | 'pre-drain-whitespace-graze';
+
+export interface PreDrainVerdict {
+ /** true → flush the pending fragment content before the paired transact. */
+ readonly preDrain: boolean;
+ readonly reason: PreDrainReason;
+}
+
+/**
+ * The core overlap decision, pure over two spans and the current body bytes.
+ * No Y.Doc, no parse, no compose — every op-specific input is already resolved
+ * to a span. This is where the fail-closed routing and the whitespace-graze
+ * relaxation live.
+ */
+export function classifyPreDrain(
+ spliceRange: BodySpan | null,
+ targetSpan: BodySpan | null,
+ body: string,
+): PreDrainVerdict {
+ if (spliceRange === null) return { preDrain: false, reason: 'checkpoint-null-splice' };
+ if (targetSpan === null) return { preDrain: false, reason: 'checkpoint-no-target' };
+
+ // A zero-width op target (an insertion anchor or a tombstone collapse point)
+ // is laundered only when it sits STRICTLY inside the rewrite range. A point
+ // exactly on a splice boundary is not inside it — the op's anchor survives an
+ // insertion at that boundary — so it is disjoint, not an overlap.
+ if (targetSpan.start === targetSpan.end) {
+ const p = targetSpan.start;
+ return spliceRange.start < p && p < spliceRange.end
+ ? { preDrain: false, reason: 'checkpoint-substantive-overlap' }
+ : { preDrain: true, reason: 'pre-drain-disjoint' };
+ }
+
+ const iStart = Math.max(spliceRange.start, targetSpan.start);
+ const iEnd = Math.min(spliceRange.end, targetSpan.end);
+ if (iStart >= iEnd) return { preDrain: true, reason: 'pre-drain-disjoint' };
+
+ // Positive-width intersection. Admit it to pre-drain only when its
+ // current-body bytes are entirely whitespace — the block-separator newlines
+ // at a boundary. A substantive struct the drain would launder necessarily
+ // contributes non-whitespace bytes to the intersection, so this graze can
+ // only ever admit separator laundering, whose worst case is a parse-invisible
+ // blank-line artifact.
+ return body.slice(iStart, iEnd).trim() === ''
+ ? { preDrain: true, reason: 'pre-drain-whitespace-graze' }
+ : { preDrain: false, reason: 'checkpoint-substantive-overlap' };
+}
+
+/**
+ * Whether a struct's clock range `[clock, clock + len)` overlaps any range the
+ * DeleteSet records for that client. Used for tombstones, whose byte position
+ * collapses to a single point regardless of how much of the struct the burst
+ * covered.
+ */
+function structOverlapsDeleteSet(
+ client: number,
+ clock: number,
+ len: number,
+ ds: YjsStackItemShape['insertions'],
+): boolean {
+ const ranges = ds.clients.get(client);
+ if (ranges === undefined) return false;
+ const end = clock + len;
+ for (const r of ranges) {
+ if (clock < r.clock + r.len && r.clock < end) return true;
+ }
+ return false;
+}
+
+/**
+ * The byte sub-ranges of a live struct (at byte `offset`, clock `[clock, clock +
+ * len)`) that the DeleteSet covers. yjs merges adjacent same-client structs even
+ * across a burst boundary, so a single live item can straddle burst and
+ * non-burst content; projecting per DeleteSet range — not per whole item — keeps
+ * the target tight to exactly the bytes the burst inserted, rather than widening
+ * it over the neighbour it merged with.
+ */
+function* burstByteSubranges(
+ client: number,
+ clock: number,
+ len: number,
+ offset: number,
+ ds: YjsStackItemShape['insertions'],
+): IterableIterator<readonly [number, number]> {
+ const ranges = ds.clients.get(client);
+ if (ranges === undefined) return;
+ const structEnd = clock + len;
+ for (const r of ranges) {
+ const oStart = Math.max(clock, r.clock);
+ const oEnd = Math.min(structEnd, r.clock + r.len);
+ if (oStart < oEnd) yield [offset + (oStart - clock), offset + (oEnd - clock)];
+ }
+}
+
+/**
+ * The undo target span: the bounding body range the top StackItem's structs
+ * occupy in the current Y.Text, projected to body coordinates.
+ *
+ * A single document-order walk of the Y.Text item chain accumulates the visible
+ * byte offset. A currently-visible struct in the StackItem's `insertions`
+ * (content the undo will delete) contributes the byte sub-ranges the burst
+ * actually covers (tight even when yjs has merged it with a neighbour); a
+ * tombstoned struct in the `deletions` (content the undo will re-insert)
+ * contributes a zero-width collapse point at its current offset. The union's
+ * `[min, max)` is the blast radius. Returns null when no struct maps — an empty
+ * stack or a frame that touched only the flash map — which routes to checkpoint.
+ *
+ * Membership is a pure clock-range test rather than yjs's `iterateDeletedStructs`
+ * (which the sibling `agent-activity.ts` uses): that primitive needs a live
+ * throwaway transaction, and the caller runs this immediately before the paired
+ * transact where a stray settlement dispatch could perturb the drain's witness
+ * state. The walk itself is the shared `walkYTextItems` donor.
+ */
+function extractUndoTargetSpan(
+ ytext: Y.Text,
+ stackItem: YjsStackItemShape,
+ fmPrefixLen: number,
+): BodySpan | null {
+ let offset = 0;
+ let minStart = Number.POSITIVE_INFINITY;
+ let maxEnd = Number.NEGATIVE_INFINITY;
+
+ for (const item of walkYTextItems(ytext)) {
+ if (!(item.content instanceof ContentString)) continue;
+ const { client, clock } = item.id;
+ const len = item.content.str.length;
+ if (!item.deleted) {
+ for (const [subStart, subEnd] of burstByteSubranges(
+ client,
+ clock,
+ len,
+ offset,
+ stackItem.insertions,
+ )) {
+ minStart = Math.min(minStart, subStart);
+ maxEnd = Math.max(maxEnd, subEnd);
+ }
+ offset += len;
+ } else if (structOverlapsDeleteSet(client, clock, len, stackItem.deletions)) {
+ minStart = Math.min(minStart, offset);
+ maxEnd = Math.max(maxEnd, offset);
+ }
+ }
+
+ if (minStart === Number.POSITIVE_INFINITY) return null;
+ return { start: Math.max(0, minStart - fmPrefixLen), end: Math.max(0, maxEnd - fmPrefixLen) };
+}
+
+/**
+ * Write positions whose compose is a FULL-BODY OVERWRITE. `composeAgentWrite`
+ * sets `newBody = payloadBody` for BOTH `replace` and `patch` — the agent's
+ * payload becomes the entire body — so a flushed keystroke cannot survive the
+ * write no matter where in the body it sat. Pre-drain is structurally inert for
+ * these: the paired write's checkpoint floor owns the pending content.
+ *
+ * This is a POSITION gate, deliberately not span arithmetic. Modelling
+ * `replace` as the span `[0, body.length)` looks equivalent but is not: the
+ * classifier's zero-width-splice and whitespace-graze relaxations both admit a
+ * flush against it (a pure block insertion produces exactly a zero-width /
+ * whitespace-only intersection at the trailing seam), and the overwrite then
+ * reverts the flushed bytes with the loss verdict already satisfied — the flush
+ * moved them into the pre-write Y.Text baseline, so the detector sees nothing
+ * at risk. Modelling `patch` as its diff'd changed region is worse still: the
+ * model and the compose disagree outright.
+ */
+const FULL_BODY_OVERWRITE_POSITIONS: ReadonlySet<AgentWritePosition> = new Set([
+ 'replace',
+ 'patch',
+]);
+
+/**
+ * The agent-write target span in body coordinates, for the positions whose
+ * compose is a localized edit.
+ *
+ * - append: the trailing seam `[trimEnd(body).length, body.length)` the append
+ * attaches to.
+ * - prepend: unmeasured; returns null so it fails closed to checkpoint.
+ *
+ * `replace` / `patch` never reach here — {@link FULL_BODY_OVERWRITE_POSITIONS}
+ * declines them before any target extraction.
+ */
+export function extractComposeTargetSpan(
+ body: string,
+ writeKind: AgentWritePosition,
+): BodySpan | null {
+ if (writeKind !== 'append') return null;
+ const trimmedLen = body.replace(/\s+$/, '').length;
+ return { start: trimmedLen, end: body.length };
+}
+
+/**
+ * The paired op the discriminator is deciding in front of. An undo carries the
+ * live Y.Text plus the top StackItem to map; an agent write carries its position
+ * kind, which is what determines both its target span and whether it is a
+ * full-body overwrite.
+ */
+type PreDrainOp =
+ | { readonly kind: 'agent-undo'; readonly ytext: Y.Text; readonly stackItem: YjsStackItemShape }
+ | { readonly kind: 'agent-write'; readonly writeKind: AgentWritePosition };
+
+export interface DiscriminatePreDrainInput {
+ /**
+ * The pending-dirty gate: false short-circuits to `skip-no-pending` before any
+ * parse, so a clean paired op pays no discriminator cost.
+ */
+ readonly pendingDirty: boolean;
+ /** Current FM-stripped Y.Text body. */
+ readonly body: string;
+ /** The pending fragment's PM JSON (holds the un-propagated content). */
+ readonly fragmentPmJson: JSONContent;
+ /**
+ * Whether the current Y.Text still equals Observer A's last-synced witness. A
+ * mismatch means the drain would take a non-splice path whose rewrite differs
+ * from the modelled splice, so the discriminator cannot reason about it and
+ * fails closed.
+ */
+ readonly witnessMatched: boolean;
+ /** `currentYText.length - body.length` — the FM prefix, for undo projection. */
+ readonly fmPrefixLen: number;
+ readonly op: PreDrainOp;
+ readonly mdManager: MarkdownManager;
+}
+
+/**
+ * The paired op a caller hands the pre-drain controller, in the form the caller
+ * naturally holds. Undo carries only the top StackItem (the controller supplies
+ * the live Y.Text from its own closure); a write carries its position kind. The
+ * controller resolves this into a full {@link PreDrainOp} before discriminating.
+ */
+export type PreDrainOpInput =
+ | { readonly kind: 'agent-undo'; readonly stackItem: YjsStackItemShape }
+ | { readonly kind: 'agent-write'; readonly writeKind: AgentWritePosition };
+
+/**
+ * A per-document pre-drain hook, built inside the observer closure so it owns
+ * the fragment/Y.Text/witness state and the cheap pending-dirty gate. A paired
+ * write's caller invokes `preDrain(op)` immediately before its own paired
+ * transact: when the discriminator proves the pending fragment content is
+ * non-overlapping with the op's target, the controller flushes that content
+ * into Y.Text (so the paired derive rebuilds over content Y.Text now holds and
+ * the keystroke survives); otherwise it declines and the paired write's existing
+ * checkpoint floor captures the content instead. Returns the verdict for the
+ * caller's content-free loss-ring correlation.
+ */
+export interface PreDrainController {
+ preDrain(op: PreDrainOpInput): PreDrainVerdict;
+}
+
+/**
+ * The decision AND the bytes that implement it. The controller needs both, and
+ * the ~15ms serialize+parse+splice must be paid at most once per dirty paired
+ * op — so the plan carries the splice the classification was computed from
+ * rather than making the caller recompute it.
+ *
+ * Discriminated on the top-level `preDrain` flag: it is `true` exactly when the
+ * splice is non-null (a flush is authorized) and `false` for every declining or
+ * skipping outcome (splice `null`). The illegal `preDrain: true` + `splice: null`
+ * state is unrepresentable, so a caller cannot flush on a plan that did not
+ * authorize it — the type, not a comment, enforces it, and the consumer narrows
+ * `splice` to non-null from `preDrain` alone.
+ */
+export type PreDrainPlan =
+ | { readonly preDrain: true; readonly verdict: PreDrainVerdict; readonly splice: MapDrivenSplice }
+ | { readonly preDrain: false; readonly verdict: PreDrainVerdict; readonly splice: null };
+
+/**
+ * Compose the gate, witness check, target extraction, localizer, and overlap
+ * classifier into one plan. The expensive localizer (three full-document
+ * passes) runs only after the cheap fail-closed guards pass and a target span
+ * exists — so the no-pending, witness-mismatch, and no-target cases never parse.
+ *
+ * This is THE pre-drain decision: the controller executes the plan, it does not
+ * re-derive one. A second implementation of this ordering would let the corpus
+ * bar and the shipped behaviour drift apart silently.
+ */
+export function planPreDrain(input: DiscriminatePreDrainInput): PreDrainPlan {
+ const decline = (reason: PreDrainReason): PreDrainPlan => ({
+ preDrain: false,
+ verdict: { preDrain: false, reason },
+ splice: null,
+ });
+
+ if (!input.pendingDirty) return decline('skip-no-pending');
+ if (!input.witnessMatched) return decline('checkpoint-witness-mismatch');
+ if (input.op.kind === 'agent-write' && FULL_BODY_OVERWRITE_POSITIONS.has(input.op.writeKind)) {
+ return decline('checkpoint-full-overwrite');
+ }
+
+ const targetSpan =
+ input.op.kind === 'agent-undo'
+ ? extractUndoTargetSpan(input.op.ytext, input.op.stackItem, input.fmPrefixLen)
+ : extractComposeTargetSpan(input.body, input.op.writeKind);
+ if (targetSpan === null) return decline('checkpoint-no-target');
+
+ const splice = computeMapDrivenBodySplice(input.body, input.fragmentPmJson, input.mdManager);
+ if (splice === null) return decline('checkpoint-null-splice');
+
+ // Already-converged gate. `pendingDirty` only says the fragment MOVED since
+ // the last convergence — not that anything is still un-propagated. A drain
+ // that propagated everything under freshness suppression leaves the flag set
+ // with nothing pending, and the splice model then returns the trailing region
+ // of two structurally-identical bodies: applying it is a delete+insert of the
+ // bytes already there, i.e. pure CRDT tombstone churn on the user's document
+ // for no content gain. A flush that rewrites nothing is not a flush.
+ if (splice.newSlice === input.body.slice(splice.spliceStart, splice.spliceEnd)) {
+ return decline('skip-already-converged');
+ }
+
+ const verdict = classifyPreDrain(
+ { start: splice.spliceStart, end: splice.spliceEnd },
+ targetSpan,
+ input.body,
+ );
+ return verdict.preDrain
+ ? { preDrain: true, verdict, splice }
+ : { preDrain: false, verdict, splice: null };
+}
diff --git a/packages/server/src/pre-drain-wired.test-helper.ts b/packages/server/src/pre-drain-wired.test-helper.ts
new file mode 100644
index 000000000..8991b4245
--- /dev/null
+++ b/packages/server/src/pre-drain-wired.test-helper.ts
@@ -0,0 +1,162 @@
+/**
+ * Wired pre-drain rig: the REAL `setupServerObservers` drain (so a doc's
+ * pre-drain controller is registered) PLUS a real `AgentSessionManager` session
+ * (so agent undo/write run through their production spines with a real
+ * per-session `Y.UndoManager` and real StackItems). This is the rung the H15
+ * paired-vector arms assert against — the discriminator's read-only corpus rig
+ * covers the classification, this covers the wiring: the flush actually lands in
+ * Y.Text before the paired transact, or the checkpoint floor captures the
+ * content when it can't.
+ *
+ * The un-propagated-keystroke window is staged with the shared bridge-race rig's
+ * freshness-suppressed echo (a component whose children advance past its stamped
+ * `sourceRaw`), so the pending content is genuinely un-propagated at the moment
+ * the paired op runs — the same shape `derive-timing-guard.test.ts` proves is a
+ * real drain stomp. Imported by sibling `*.test.ts` files; not itself a test.
+ */
+
+import type { Document } from '@hocuspocus/server';
+import type * as Y from 'yjs';
+import {
+ type AgentDirectConnection,
+ AgentSessionManager,
+ type AgentWriteLossDetect,
+ agentWritePreDrain,
+ applyAgentMarkdownWrite,
+ applyAgentUndo,
+} from './agent-sessions.ts';
+import type { BridgeDeriveLossReporter } from './bridge-loss-detector.ts';
+import {
+ type BridgeRaceRig,
+ type CreateRigOpts,
+ createBridgeRaceRig,
+} from './bridge-race-rig.test-helper.ts';
+
+/** A component doc whose child line can advance past its stamped source. */
+const WIRED_BASE =
+ '## Guide\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n\nTail paragraph.\n';
+export const WIRED_STALE_LINE = 'Step one bod';
+export const WIRED_PENDING_LINE = 'Step one body.';
+
+function createMockHocuspocus(ydoc: Y.Doc, docName: string) {
+ // In production the Hocuspocus `Document` IS the `Y.Doc` (Document extends
+ // Y.Doc), and setupServerObservers registers its pre-drain controller keyed by
+ // that exact object. Augment the real Y.Doc with the small Document surface the
+ // agent spine reads, rather than wrapping it — so `session.dc.document` has the
+ // SAME identity the controller was registered under (WeakMap lookup by object).
+ const doc = ydoc as unknown as Document & { name: string; awareness: unknown };
+ (doc as { name: string }).name = docName;
+ (doc as { awareness: unknown }).awareness = {
+ setLocalState() {},
+ setLocalStateField() {},
+ };
+ const dc = {
+ document: doc,
+ disconnect: async () => {},
+ isDisconnected: () => false,
+ transact: () => {},
+ } as unknown as AgentDirectConnection;
+ return {
+ openDirectConnection: async (): Promise<AgentDirectConnection> => dc,
+ };
+}
+
+export interface WiredPreDrainRig {
+ readonly rig: BridgeRaceRig;
+ readonly doc: Y.Doc;
+ /** The live per-session record (structural subset used by the tests). */
+ readonly session: {
+ dc: AgentDirectConnection;
+ origin: unknown;
+ um: Y.UndoManager;
+ docName: string;
+ agentId: string;
+ };
+ /** Canonical markdown of the current XmlFragment. */
+ serializeFragment(): string;
+ /** Current Y.Text('source') bytes. */
+ ytextString(): string;
+ /** Real agent write through `applyAgentMarkdownWrite` under the session origin. */
+ agentWrite(markdown: string, position: 'append' | 'prepend' | 'replace' | 'patch'): void;
+ /** The handler-level pre-drain + write, mirroring an agent-write HTTP handler. */
+ agentWriteWithPreDrain(
+ markdown: string,
+ position: 'append' | 'prepend' | 'replace' | 'patch',
+ ): void;
+ /** Real agent undo through `applyAgentUndo` (runs the wired pre-drain). */
+ agentUndo(scope?: 'last' | 'session' | 'count', count?: number): boolean;
+ /**
+ * Stage an un-propagated keystroke inside the component (fragment holds
+ * `WIRED_PENDING_LINE`, Y.Text still holds `WIRED_STALE_LINE`), with a recent
+ * external poke so the echo drain settles freshness-suppressed.
+ */
+ stageUnpropagatedKeystroke(): void;
+ cleanup(): Promise<void>;
+}
+
+export interface CreateWiredRigOpts extends CreateRigOpts {
+ /** Attach a paired-intake loss reporter (the checkpoint floor). */
+ reporter?: BridgeDeriveLossReporter;
+}
+
+/** Create a wired pre-drain rig over a real drain + a real agent session. */
+export async function createWiredPreDrainRig(
+ opts: CreateWiredRigOpts = {},
+): Promise<WiredPreDrainRig> {
+ const docName = opts.docName ?? 'wired-pre-drain.md';
+ const rig = createBridgeRaceRig({ ...opts, docName });
+ const manager = new AgentSessionManager(createMockHocuspocus(rig.doc, docName) as never);
+ if (opts.reporter) manager.attachBridgeLossReporter(opts.reporter);
+ const session = (await manager.getSession(docName, 'agent-1')) as unknown as {
+ dc: AgentDirectConnection;
+ origin: unknown;
+ um: Y.UndoManager;
+ docName: string;
+ agentId: string;
+ };
+ const document = session.dc.document;
+
+ // Seed the component base and converge it into Y.Text so the doc rests in the
+ // settled state a real doc holds before its first paired op.
+ rig.editFragment(WIRED_BASE);
+ rig.settle(1);
+
+ const lossDetect: AgentWriteLossDetect | undefined = opts.reporter
+ ? { reporter: opts.reporter, writerId: 'agent-1' }
+ : undefined;
+
+ return {
+ rig,
+ doc: rig.doc,
+ session,
+ serializeFragment: () => rig.serializeFragment(),
+ ytextString: () => rig.ytext.toString(),
+ agentWrite: (markdown, position) => {
+ rig.advancePastFreshness();
+ document.transact(() => {
+ applyAgentMarkdownWrite(document, markdown, position, undefined, undefined, lossDetect);
+ }, session.origin);
+ },
+ agentWriteWithPreDrain: (markdown, position) => {
+ rig.advancePastFreshness();
+ agentWritePreDrain(document, markdown, position);
+ document.transact(() => {
+ applyAgentMarkdownWrite(document, markdown, position, undefined, undefined, lossDetect);
+ }, session.origin);
+ },
+ agentUndo: (scope = 'last', count) => applyAgentUndo(session as never, scope, undefined, count),
+ stageUnpropagatedKeystroke: () => {
+ // A recent external Y.Text write resets the freshness-quiescence clock, so
+ // the echo drain serializes the stale component source and settles without
+ // propagating the advanced child — the un-propagated shape.
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing note.\n'));
+ rig.echoFragmentEdit(rig.ytext.toString(), WIRED_STALE_LINE, WIRED_PENDING_LINE, {
+ advanceFreshness: false,
+ });
+ },
+ cleanup: async () => {
+ await manager.closeAll();
+ rig.cleanup();
+ },
+ };
+}
diff --git a/packages/server/src/producer-origin-gate.test.ts b/packages/server/src/producer-origin-gate.test.ts
new file mode 100644
index 000000000..511068310
--- /dev/null
+++ b/packages/server/src/producer-origin-gate.test.ts
@@ -0,0 +1,370 @@
+/**
+ * Producer-origin enforcement: no document-body content transaction may run
+ * without a named frozen origin.
+ *
+ * Every write that mutates the document body — the `Y.Text('source')` bytes or
+ * the `Y.XmlFragment` — must carry a marked origin so the undo managers,
+ * paired-write suppression, and client-side provenance observers can classify
+ * it. A `doc.transact(fn)` with no origin (or `undefined`/`null`/an inline
+ * literal) is a silent write surface: it lands under the anonymous
+ * `openknowledge-service` identity and escapes every one of those contracts.
+ *
+ * This gate scans `packages/{app,server,core}/src` and FAILS the build when a
+ * body-content transaction — or a `chunkedYTextInsert` call, which transacts
+ * internally under a caller-supplied origin — omits a named frozen origin
+ * constant. It complements `paired-write-enforcement.test.ts`, which classifies
+ * transacts by origin NAME but skips any call with fewer than two arguments —
+ * exactly the missing-origin shape this gate exists to catch.
+ *
+ * Scope is the document BODY. Config/okignore docs obtain their handle via
+ * `getText(ytextKey)` (a variable key) and mutate raw `Y.Text` outside the
+ * markdown bridge, so they never match the literal-`'source'`/fragment/primitive
+ * classifier below — no site allow-list is needed to exclude them.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Node, Project, type SourceFile, SyntaxKind } from 'ts-morph';
+import { describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packagesDir = join(here, '..', '..');
+const SCAN_ROOTS = [
+ join(packagesDir, 'app', 'src'),
+ join(packagesDir, 'server', 'src'),
+ join(packagesDir, 'core', 'src'),
+];
+
+/**
+ * Body-write helper functions. A transact whose body calls one of these is
+ * writing document-body content. The first three are the sanctioned
+ * `bridge-intake.ts` primitives; the rest are their transitive callers and the
+ * low-level fragment/diff appliers the observer bridge runs.
+ */
+const BODY_WRITE_PRIMITIVES = new Set<string>([
+ 'composeAndWriteRawBody',
+ 'replaceRawBody',
+ 'deriveFragmentFromYtext',
+ 'applyAgentMarkdownWrite',
+ 'applyDiskContentToDoc',
+ 'applyDiskContent',
+ 'updateYFragment',
+ 'applyFastDiff',
+]);
+
+/** CRDT mutation methods that constitute an authored body edit. */
+const MUTATION_METHODS = new Set<string>(['insert', 'delete', 'applyDelta', 'format', 'push']);
+
+/** `chunkedYTextInsert` transacts internally under `options.origin`. */
+const ORIGIN_FORWARDING_FNS = new Set<string>(['chunkedYTextInsert']);
+
+interface Violation {
+ readonly file: string;
+ readonly line: number;
+ readonly detail: string;
+}
+
+// ─── AST helpers ─────────────────────────────────────────────
+
+/** Callee's trailing name: `x.foo` → `foo`, `foo` → `foo`, else null. */
+function calleeName(call: Node): string | null {
+ if (!Node.isCallExpression(call)) return null;
+ const callee = call.getExpression();
+ if (callee.isKind(SyntaxKind.Identifier)) return callee.getText();
+ if (callee.isKind(SyntaxKind.PropertyAccessExpression)) return callee.getName();
+ return null;
+}
+
+/** True when `expr` is `<x>.getText('source')`. */
+function isSourceTextAccessor(expr: Node): boolean {
+ if (!Node.isCallExpression(expr)) return false;
+ const callee = expr.getExpression();
+ if (!callee.isKind(SyntaxKind.PropertyAccessExpression) || callee.getName() !== 'getText')
+ return false;
+ const arg = expr.getArguments()[0];
+ return arg?.isKind(SyntaxKind.StringLiteral) === true && arg.getLiteralText() === 'source';
+}
+
+/** True when `expr` is `<x>.getXmlFragment(...)` or `<x>.get('default')`. */
+function isFragmentAccessor(expr: Node): boolean {
+ if (!Node.isCallExpression(expr)) return false;
+ const callee = expr.getExpression();
+ if (!callee.isKind(SyntaxKind.PropertyAccessExpression)) return false;
+ if (callee.getName() === 'getXmlFragment') return true;
+ if (callee.getName() === 'get') {
+ const arg = expr.getArguments()[0];
+ return arg?.isKind(SyntaxKind.StringLiteral) === true && arg.getLiteralText() === 'default';
+ }
+ return false;
+}
+
+/** Nearest function-like ancestor — the scope handle bindings live in. */
+function enclosingFunction(node: Node): Node | undefined {
+ return node.getFirstAncestor(
+ (a) =>
+ a.isKind(SyntaxKind.ArrowFunction) ||
+ a.isKind(SyntaxKind.FunctionExpression) ||
+ a.isKind(SyntaxKind.FunctionDeclaration) ||
+ a.isKind(SyntaxKind.MethodDeclaration),
+ );
+}
+
+/** Local variable names bound to a `'source'`-Y.Text or XmlFragment handle. */
+function bodyHandleNames(scope: Node): Set<string> {
+ const names = new Set<string>();
+ for (const decl of scope.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+ const init = decl.getInitializer();
+ if (init && (isSourceTextAccessor(init) || isFragmentAccessor(init))) {
+ const nameNode = decl.getNameNode();
+ if (nameNode.isKind(SyntaxKind.Identifier)) names.add(nameNode.getText());
+ }
+ }
+ return names;
+}
+
+/** True when `body` performs an authored mutation of the document body. */
+function bodyMutatesDocument(body: Node, handleNames: Set<string>): boolean {
+ let found = false;
+ body.forEachDescendant((node, traversal) => {
+ if (found) {
+ traversal.stop();
+ return;
+ }
+ if (!Node.isCallExpression(node)) return;
+ const callee = node.getExpression();
+ // A direct body-write primitive call.
+ const name = calleeName(node);
+ if (name && BODY_WRITE_PRIMITIVES.has(name)) {
+ found = true;
+ return;
+ }
+ // An authored mutation on a body handle: `<handle>.insert(...)`, either a
+ // named handle from the enclosing scope or an inline `.getText('source')`
+ // / `.getXmlFragment()` chain.
+ if (
+ callee.isKind(SyntaxKind.PropertyAccessExpression) &&
+ MUTATION_METHODS.has(callee.getName())
+ ) {
+ const recv = callee.getExpression();
+ if (recv.isKind(SyntaxKind.Identifier) && handleNames.has(recv.getText())) found = true;
+ else if (isSourceTextAccessor(recv) || isFragmentAccessor(recv)) found = true;
+ }
+ });
+ return found;
+}
+
+/**
+ * A named frozen origin is a bare identifier reference (`LINT_FIX_ORIGIN`) or a
+ * property access (`session.origin`) — never a missing arg, `undefined`,
+ * `null`, or an inline object literal.
+ */
+function isNamedFrozenOrigin(originArg: Node | undefined): boolean {
+ if (!originArg) return false;
+ if (originArg.isKind(SyntaxKind.Identifier)) return originArg.getText() !== 'undefined';
+ if (originArg.isKind(SyntaxKind.PropertyAccessExpression)) return true;
+ return false;
+}
+
+/** The callback + the origin arg immediately after it (form-agnostic: covers
+ * both `doc.transact(fn, origin)` and `Y.transact(doc, fn, origin, local)`). */
+function transactCallbackAndOrigin(call: Node): { body: Node; origin: Node | undefined } | null {
+ if (!Node.isCallExpression(call)) return null;
+ const args = call.getArguments();
+ const cbIndex = args.findIndex(
+ (a) => a.isKind(SyntaxKind.ArrowFunction) || a.isKind(SyntaxKind.FunctionExpression),
+ );
+ if (cbIndex === -1) return null;
+ const cb = args[cbIndex];
+ const body = Node.isArrowFunction(cb) || Node.isFunctionExpression(cb) ? cb.getBody() : undefined;
+ if (!body) return null;
+ return { body, origin: args[cbIndex + 1] };
+}
+
+/** The `origin` property value of a `chunkedYTextInsert(...)` options object. */
+function chunkedInsertOriginArg(call: Node): Node | undefined {
+ if (!Node.isCallExpression(call)) return undefined;
+ const options = call.getArguments()[4];
+ if (!options?.isKind(SyntaxKind.ObjectLiteralExpression)) return undefined;
+ const prop = options.getProperty('origin');
+ if (prop?.isKind(SyntaxKind.PropertyAssignment)) return prop.getInitializer();
+ if (prop?.isKind(SyntaxKind.ShorthandPropertyAssignment)) return prop.getNameNode();
+ return undefined;
+}
+
+// ─── Core analysis (pure — runs on real files AND fixtures) ───
+
+function analyzeSourceFile(rel: string, sf: SourceFile): Violation[] {
+ const violations: Violation[] = [];
+ for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+ const name = calleeName(call);
+
+ // (1) chunkedYTextInsert: transacts internally under options.origin.
+ if (name && ORIGIN_FORWARDING_FNS.has(name)) {
+ const originArg = chunkedInsertOriginArg(call);
+ if (!isNamedFrozenOrigin(originArg)) {
+ violations.push({
+ file: rel,
+ line: call.getStartLineNumber(),
+ detail: `${name}(...) omits a named frozen \`origin\` option`,
+ });
+ }
+ continue;
+ }
+
+ // (2) doc.transact(fn, origin) / Y.transact(doc, fn, origin, local).
+ const callee = call.getExpression();
+ if (!callee.isKind(SyntaxKind.PropertyAccessExpression) || callee.getName() !== 'transact')
+ continue;
+ const parts = transactCallbackAndOrigin(call);
+ if (!parts) continue;
+ const scope = enclosingFunction(call) ?? sf;
+ const handleNames = bodyHandleNames(scope);
+ if (!bodyMutatesDocument(parts.body, handleNames)) continue;
+ if (!isNamedFrozenOrigin(parts.origin)) {
+ violations.push({
+ file: rel,
+ line: call.getStartLineNumber(),
+ detail: 'body-content transact() without a named frozen origin',
+ });
+ }
+ }
+ return violations;
+}
+
+// ─── File discovery (pre-filtered for speed) ─────────────────
+
+function isScannableFile(name: string): boolean {
+ if (!name.endsWith('.ts') && !name.endsWith('.tsx')) return false;
+ if (name.endsWith('.d.ts')) return false;
+ if (name.includes('.test-helper.')) return false;
+ if (/\.(test|spec|e2e)\./.test(name)) return false;
+ return true;
+}
+
+function collectCandidateFiles(root: string): string[] {
+ const out: string[] = [];
+ const walk = (dir: string): void => {
+ let entries: string[];
+ try {
+ entries = readdirSync(dir);
+ } catch {
+ return;
+ }
+ for (const entry of entries) {
+ if (entry === 'node_modules' || entry === 'dist' || entry === '__mocks__') continue;
+ const abs = join(dir, entry);
+ const st = statSync(abs);
+ if (st.isDirectory()) {
+ walk(abs);
+ } else if (isScannableFile(entry)) {
+ const text = readFileSync(abs, 'utf8');
+ if (text.includes('.transact(') || text.includes('chunkedYTextInsert(')) out.push(abs);
+ }
+ }
+ };
+ walk(root);
+ return out;
+}
+
+function newProject(): Project {
+ return new Project({
+ skipFileDependencyResolution: true,
+ skipLoadingLibFiles: true,
+ skipAddingFilesFromTsConfig: true,
+ compilerOptions: { noLib: true, allowJs: false },
+ });
+}
+
+// ─── Tests ───────────────────────────────────────────────────
+
+describe('producer origin gate', () => {
+ it('every body-content transaction carries a named frozen origin', () => {
+ const project = newProject();
+ const files: Array<readonly [string, SourceFile]> = [];
+ for (const root of SCAN_ROOTS) {
+ for (const abs of collectCandidateFiles(root)) {
+ const rel = abs.slice(packagesDir.length + 1);
+ files.push([rel, project.addSourceFileAtPath(abs)] as const);
+ }
+ }
+ // Never-silently-pass: if the pre-filter found nothing, the gate is a no-op.
+ expect(files.length).toBeGreaterThan(0);
+
+ const violations = files.flatMap(([rel, sf]) => analyzeSourceFile(rel, sf));
+ if (violations.length > 0) {
+ const lines = violations.map((v) => ` ${v.file}:${v.line} — ${v.detail}`).join('\n');
+ throw new Error(
+ `Found ${violations.length} content transaction(s) without a named frozen origin:\n${lines}\n` +
+ `Give the write a named frozen origin constant (e.g. LINT_FIX_ORIGIN, session.origin).`,
+ );
+ }
+ });
+
+ it('catches a bare body-content transact (planted positive)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-bare-transact.ts',
+ `function paste(provider: any, doc: any) {
+ const ytext = provider.document.getText('source');
+ doc.transact(() => {
+ ytext.insert(0, 'x');
+ });
+ }`,
+ );
+ const violations = analyzeSourceFile('planted-bare-transact.ts', sf);
+ expect(violations).toHaveLength(1);
+ expect(violations[0]?.detail).toContain('named frozen origin');
+ });
+
+ it('catches an undefined / inline-literal origin (planted positives)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-bad-origin.ts',
+ `function w(provider: any, doc: any) {
+ const ytext = provider.document.getText('source');
+ doc.transact(() => { ytext.delete(0, 1); }, undefined);
+ doc.transact(() => { ytext.delete(0, 1); }, { source: 'local' });
+ doc.transact(() => { ytext.delete(0, 1); }, null);
+ }`,
+ );
+ expect(analyzeSourceFile('planted-bad-origin.ts', sf)).toHaveLength(3);
+ });
+
+ it('catches a chunkedYTextInsert call missing a named origin (planted positive)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'planted-chunked.ts',
+ `function paste(doc: any, ytext: any) {
+ chunkedYTextInsert(doc, ytext, 0, 'big', { resolveOffset: (n: number) => n });
+ }`,
+ );
+ const violations = analyzeSourceFile('planted-chunked.ts', sf);
+ expect(violations).toHaveLength(1);
+ expect(violations[0]?.detail).toContain('chunkedYTextInsert');
+ });
+
+ it('passes a named-origin body transact and a config-doc (variable-key) write (positive controls)', () => {
+ const project = newProject();
+ const sf = project.createSourceFile(
+ 'controls.ts',
+ `const LINT_FIX_ORIGIN = Object.freeze({ context: { origin: 'lint-fix' } });
+ function good(provider: any, doc: any) {
+ const ytext = provider.document.getText('source');
+ doc.transact(() => { ytext.insert(0, 'x'); }, LINT_FIX_ORIGIN);
+ }
+ function configDoc(ydoc: any, ytextKey: string) {
+ const ytext = ydoc.getText(ytextKey);
+ ydoc.transact(() => { ytext.insert(0, 'cfg'); });
+ }
+ function primitive(session: any) {
+ session.dc.document.transact(() => {
+ replaceRawBody(session, 'body');
+ }, session.origin);
+ }
+ function chunked(doc: any, ytext: any) {
+ chunkedYTextInsert(doc, ytext, 0, 'big', { origin: SOURCE_PASTE_ORIGIN });
+ }`,
+ );
+ expect(analyzeSourceFile('controls.ts', sf)).toHaveLength(0);
+ });
+});
diff --git a/packages/server/src/qa-degradation-matrix.test.ts b/packages/server/src/qa-degradation-matrix.test.ts
new file mode 100644
index 000000000..6cdcfc640
--- /dev/null
+++ b/packages/server/src/qa-degradation-matrix.test.ts
@@ -0,0 +1,360 @@
+/**
+ * Cross-mechanism degradation: with one guard switched off, do its siblings
+ * still SEE the loss it stopped preventing?
+ *
+ * The kill-switch suites pin each mechanism's own OFF-inertness — off means the
+ * mechanism does nothing. That is a different question from the one an operator
+ * asks when they disable a guard in the field: does the loss it was preventing
+ * become SILENT, or does a sibling still checkpoint and ring-log it?
+ *
+ * Each mechanism gets a PAIR of cells over one staging that genuinely reaches
+ * it: an ON cell showing the mechanism firing, and an OFF cell showing what an
+ * operator is left with. The pair is the binding proof — an OFF cell whose
+ * observations match its ON partner would be asserting nothing, so the staging
+ * has to put the mechanism on the drain path, not merely set its flag.
+ *
+ * The matrix answers two different ways, and that asymmetry is the finding:
+ * the paired agent-write vector degrades from PREVENTION to OBSERVATION (the
+ * paired-intake floor still catches the drop), while the non-paired
+ * Observer-B re-derive, the Observer-A apply arm, and the re-derive-loop
+ * backstop each degrade to SILENCE — no sibling watches those paths.
+ *
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import type * as Y from 'yjs';
+import { createBridgeDeriveLossReporter } from './bridge-loss-detector.ts';
+import { type BridgeRaceRig, createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+import type { LossCaptureEventInput } from './loss-capture.ts';
+import {
+ createWiredPreDrainRig,
+ WIRED_PENDING_LINE,
+ type WiredPreDrainRig,
+} from './pre-drain-wired.test-helper.ts';
+import type { SetupServerObserversOpts } from './server-observers.ts';
+
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+const PENDING_LINE = 'Step one body.';
+const STALE_LINE = 'Step one bod';
+
+/** Doc the Observer-A apply arm runs over; `APPLY_DROP_TARGET` is the drop. */
+const APPLY_BASE = '# Title\n\nLine one\n\nLine two\n';
+const APPLY_GROWN = '# Title\n\nLine one\n\nLine two\n\nLine three\n';
+const APPLY_DROP_TARGET = 'Line two';
+
+/**
+ * Two non-round-trip source forms that are normalize-EQUAL to their canonical
+ * (serialize strips the trailing whitespace, so neither reaches a raw-byte fixed
+ * point) yet byte-different from each other. Alternating them revisits a recent
+ * state every round without ever converging — a sustained corrective-write loop.
+ */
+const CYCLE_FORM_A = '# Cycle\n\nalpha side of the loop \n';
+const CYCLE_FORM_B = '# Cycle\n\nbravo side of the loop \n';
+const POST_LOOP_SOURCE_EDIT = 'a source edit after the loop';
+
+function stageUnpropagatedKeystroke(rig: BridgeRaceRig): void {
+ rig.editFragment(GEN1);
+ rig.settle(1);
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing.\n'));
+ rig.echoFragmentEdit(rig.ytext.toString(), STALE_LINE, PENDING_LINE, {
+ advanceFreshness: false,
+ });
+}
+
+function sourceWrite(rig: BridgeRaceRig, text: string): void {
+ rig.externalYtextEdit('source-write', (yt) => yt.insert(yt.length, `\n${text}\n`), {
+ advanceFreshness: false,
+ });
+}
+
+/** Build a rig with a recording loss ring plus the caller's overrides. */
+function rigWithRing(
+ docName: string,
+ overrides: Partial<SetupServerObserversOpts>,
+): { rig: BridgeRaceRig; recorded: LossCaptureEventInput[] } {
+ const recorded: LossCaptureEventInput[] = [];
+ const rig = createBridgeRaceRig({
+ docName,
+ setupOverrides: {
+ lossRing: {
+ record: async (input) => {
+ recorded.push(input);
+ },
+ },
+ ...overrides,
+ },
+ });
+ return { rig, recorded };
+}
+
+/**
+ * A one-shot Y.Text deletion for the apply-arm seam, plus a `fired` readback.
+ * The byte-preserving apply arms never drop content organically, so the drop
+ * has to be injected — and the readback is what proves the OFF cell reached the
+ * same apply arm the ON cell did, rather than going quiet for some other reason.
+ */
+function makeApplyDropInjector(target: string): {
+ inject: (yt: Y.Text) => void;
+ fired: () => boolean;
+} {
+ let fired = false;
+ return {
+ inject: (yt) => {
+ if (fired) return;
+ const idx = yt.toString().indexOf(target);
+ if (idx < 0) return;
+ yt.delete(idx, target.length);
+ fired = true;
+ },
+ fired: () => fired,
+ };
+}
+
+/** Drive the apply-arm drop: seed, settle, then grow the fragment. */
+function driveApplyArmDrop(rig: BridgeRaceRig): void {
+ rig.editFragment(APPLY_BASE);
+ rig.settle(1);
+ rig.editFragment(APPLY_GROWN);
+}
+
+/** Drive the non-converging re-derive loop well past the backstop's bound. */
+function driveOscillation(rig: BridgeRaceRig): void {
+ for (let i = 0; i < 24; i++) rig.seedSource(i % 2 === 0 ? CYCLE_FORM_A : CYCLE_FORM_B);
+}
+
+/**
+ * Wired pre-drain rig with the paired-intake checkpoint floor attached. The
+ * floor is the sibling under test here, so it runs its real detection; passing
+ * no shadow keeps it off git and routes its trip straight to the ring.
+ */
+async function wiredRigWithFloor(
+ docName: string,
+ overrides: Partial<SetupServerObserversOpts>,
+): Promise<{ rig: WiredPreDrainRig; recorded: LossCaptureEventInput[] }> {
+ const recorded: LossCaptureEventInput[] = [];
+ const reporter = createBridgeDeriveLossReporter({
+ shadow: () => undefined,
+ ring: {
+ record: async (input) => {
+ recorded.push(input);
+ },
+ },
+ getBranch: () => 'main',
+ contentRoot: '',
+ });
+ const rig = await createWiredPreDrainRig({ docName, reporter, setupOverrides: overrides });
+ return { rig, recorded };
+}
+
+beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+});
+afterEach(() => {
+ vi.useRealTimers();
+});
+
+describe('single-mechanism-OFF degradation', () => {
+ test('defer guard ON: the keystroke is PREVENTED from being lost and the ring says so', () => {
+ const { rig, recorded } = rigWithRing('degrade-guard-on', {});
+ try {
+ stageUnpropagatedKeystroke(rig);
+ sourceWrite(rig, 'Another source line.');
+
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+ expect(recorded.some((e) => e.event === 'guard-defer')).toBe(true);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ /**
+ * MEASURED, not desired. On a PAIRED vector (agent-write intake) switching the
+ * guard off degrades prevention into observation — the paired-intake detector
+ * still trips and checkpoints, which `bridge-loss-injection.test.ts` pins with
+ * `bridge.deferGuard.enabled: false` in its project config. This is the other
+ * half of that matrix, and it does not behave the same way: the stomp here
+ * rides a NON-paired Observer-B re-derive (a source-editor Y.Text write), and
+ * no sibling mechanism watches that path, so the loss is SILENT — no ring
+ * event, no checkpoint.
+ *
+ * Pinned so the asymmetry is visible: if a future change gives the non-paired
+ * path an observer, this expectation must be updated deliberately rather than
+ * the gap being rediscovered.
+ *
+ */
+ test('defer guard OFF: the stomp reproduces and, on the non-paired path, is NOT observed', () => {
+ const { rig, recorded } = rigWithRing('degrade-guard-off', { deferGuardEnabled: false });
+ try {
+ stageUnpropagatedKeystroke(rig);
+ sourceWrite(rig, 'Another source line.');
+
+ // The loss the guard was preventing now happens.
+ expect(rig.serializeFragment()).not.toContain(PENDING_LINE);
+ // The guard's own event is necessarily absent — it is switched off.
+ expect(recorded.some((e) => e.event === 'guard-defer')).toBe(false);
+ // And nothing else picks it up: the degradation is silent here.
+ expect(recorded).toEqual([]);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('loss detector ON: an Observer-A apply-arm drop trips it and the ring carries the shape', () => {
+ const injector = makeApplyDropInjector(APPLY_DROP_TARGET);
+ const { rig, recorded } = rigWithRing('degrade-detector-on', {
+ __testApplyLossInjector: injector.inject,
+ });
+ try {
+ driveApplyArmDrop(rig);
+
+ expect(injector.fired()).toBe(true);
+ const trip = recorded.find((e) => e.event === 'detector-trip');
+ expect(trip?.direction).toBe('a');
+ expect(trip?.site).toBe('observer-a-apply');
+ // A length and a digest — the ring never carries the dropped bytes.
+ expect(trip?.lostLen).toBe(APPLY_DROP_TARGET.length);
+ expect(JSON.stringify(trip)).not.toContain(APPLY_DROP_TARGET);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ /**
+ * The apply arm drops the same bytes either way — `fired` is the proof this
+ * cell reached the arm rather than going quiet upstream. With the detector
+ * off, no sibling covers the Observer-A apply path, so the drop is silent.
+ *
+ */
+ test('loss detector OFF: the same apply-arm drop happens and no sibling records it', () => {
+ const injector = makeApplyDropInjector(APPLY_DROP_TARGET);
+ const { rig, recorded } = rigWithRing('degrade-detector-off', {
+ lossDetectorEnabled: false,
+ __testApplyLossInjector: injector.inject,
+ });
+ try {
+ driveApplyArmDrop(rig);
+
+ expect(injector.fired()).toBe(true);
+ expect(recorded).toEqual([]);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('fixed-point backstop ON: a non-converging loop freezes the B re-derive and the ring says so', () => {
+ const { rig, recorded } = rigWithRing('degrade-backstop-on', {});
+ try {
+ driveOscillation(rig);
+ const frozenFragment = rig.serializeFragment();
+ rig.seedSource(`# Cycle\n\n${POST_LOOP_SOURCE_EDIT} \n`);
+
+ const trip = recorded.find((e) => e.event === 'backstop-trip');
+ expect(trip?.direction).toBe('b');
+ expect(trip?.site).toBe('rederive-backstop');
+ // B is frozen: the later source edit does not rebuild the fragment...
+ expect(rig.serializeFragment()).toBe(frozenFragment);
+ // ...while Y.Text stays authoritative and live.
+ expect(rig.ytext.toString()).toContain(POST_LOOP_SOURCE_EDIT);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('fixed-point backstop OFF: the same loop churns unbounded and no sibling records it', () => {
+ const { rig, recorded } = rigWithRing('degrade-backstop-off', {
+ fixedPointBackstopEnabled: false,
+ });
+ try {
+ driveOscillation(rig);
+ rig.seedSource(`# Cycle\n\n${POST_LOOP_SOURCE_EDIT} \n`);
+
+ // Never frozen — the loop the backstop would have bounded keeps
+ // re-deriving, and nothing anywhere reports that it ran away.
+ expect(rig.serializeFragment()).toContain(POST_LOOP_SOURCE_EDIT);
+ expect(recorded).toEqual([]);
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ /**
+ * The pre-drain flag is read only inside the controller's `preDrain`, which
+ * nothing but `agentWritePreDrain` reaches — so this pair runs the handler
+ * shape (pre-drain, then the paired transact) on the wired rig. `append` is
+ * used deliberately: `replace` / `patch` are full-body overwrites that decline
+ * on position, and a post-defer staging declines on the witness before the
+ * position gate, so either would leave the flag inert again.
+ *
+ */
+ test('pre-drain ON: the pending keystroke is flushed ahead of the paired write and survives', async () => {
+ const { rig, recorded } = await wiredRigWithFloor('degrade-predrain-on', {});
+ try {
+ rig.stageUnpropagatedKeystroke();
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(rig.ytextString()).not.toContain(WIRED_PENDING_LINE);
+
+ rig.agentWriteWithPreDrain('A fresh agent paragraph.', 'append');
+
+ // Prevented, not merely observed: the keystroke rode into Y.Text ahead of
+ // the paired derive, so the floor had nothing to catch.
+ expect(rig.ytextString()).toContain(WIRED_PENDING_LINE);
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+ expect(rig.ytextString()).toContain('A fresh agent paragraph.');
+ expect(recorded).toEqual([]);
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ /**
+ * The opposite answer from the defer-guard cell above, and the reason this
+ * matrix exists: the paired vector degrades from prevention to OBSERVATION.
+ * The keystroke is genuinely lost, but the paired-intake floor sees it go and
+ * mints a restorable record, so an operator running with pre-drain off is
+ * blind to nothing.
+ *
+ */
+ test('pre-drain OFF: the keystroke is dropped and the paired-intake floor observes it', async () => {
+ const { rig, recorded } = await wiredRigWithFloor('degrade-predrain-off', {
+ preDrainEnabled: false,
+ });
+ try {
+ rig.stageUnpropagatedKeystroke();
+ expect(rig.serializeFragment()).toContain(WIRED_PENDING_LINE);
+
+ rig.agentWriteWithPreDrain('A fresh agent paragraph.', 'append');
+
+ // The loss pre-drain was preventing now happens...
+ expect(rig.ytextString()).not.toContain(WIRED_PENDING_LINE);
+ expect(rig.serializeFragment()).not.toContain(WIRED_PENDING_LINE);
+ // ...and a sibling caught it, attributed to the writing agent.
+ const trip = recorded.find((e) => e.event === 'detector-trip');
+ expect(trip?.direction).toBe('b');
+ expect(trip?.site).toBe('agent-write-intake');
+ expect(trip?.writerId).toBe('agent-1');
+ expect(trip?.lostLen).toBeGreaterThan(0);
+ expect(JSON.stringify(trip)).not.toContain(WIRED_PENDING_LINE);
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ /**
+ * Ring absent is the one degradation that IS allowed to be silent — the
+ * mechanisms must still act.
+ *
+ */
+ test('loss capture OFF (no ring wired): the guard still acts, only the record is gone', () => {
+ const rig = createBridgeRaceRig({ docName: 'degrade-ring-off' });
+ try {
+ stageUnpropagatedKeystroke(rig);
+ sourceWrite(rig, 'Another source line.');
+
+ expect(rig.serializeFragment()).toContain(PENDING_LINE);
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/qa-duplication-lens.test.ts b/packages/server/src/qa-duplication-lens.test.ts
new file mode 100644
index 000000000..12a5047c1
--- /dev/null
+++ b/packages/server/src/qa-duplication-lens.test.ts
@@ -0,0 +1,236 @@
+/**
+ * Occurrence-count and raw-granularity oracles for the duplication classes the
+ * committed suites cannot see.
+ *
+ * Those suites assert with `toContain`, which stays green when a line is
+ * present TWICE — exactly the failure the defer guard, the re-derive backstop
+ * and the pre-drain flush exist to prevent. These arms drive the SAME
+ * production rigs and count instead, and compare RAW fragment structure rather
+ * than canonical serialization so a stale-but-unmutated freeze is
+ * distinguishable from a re-derived one.
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { type BridgeRaceRig, createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+import { getMetrics } from './metrics.ts';
+import {
+ createWiredPreDrainRig,
+ WIRED_PENDING_LINE,
+ WIRED_STALE_LINE,
+} from './pre-drain-wired.test-helper.ts';
+
+/** Count non-overlapping occurrences of `needle` in `hay`. */
+function count(hay: string, needle: string): number {
+ if (needle === '') return 0;
+ let n = 0;
+ let i = hay.indexOf(needle);
+ while (i !== -1) {
+ n++;
+ i = hay.indexOf(needle, i + needle.length);
+ }
+ return n;
+}
+
+// ---- force-resolve staging (mirrors derive-timing-exhaustion.test.ts) ----
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+const PENDING_LINE = 'Step one body.';
+const STALE_LINE = 'Step one bod';
+const MAX_DRAINS = 30;
+
+function stageUnpropagatedKeystroke(rig: BridgeRaceRig): void {
+ rig.editFragment(GEN1);
+ rig.settle(1);
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing.\n'));
+ rig.echoFragmentEdit(rig.ytext.toString(), STALE_LINE, PENDING_LINE, { advanceFreshness: false });
+}
+function sourceWrite(rig: BridgeRaceRig, text: string): void {
+ rig.externalYtextEdit('source-write', (yt) => yt.insert(yt.length, `\n${text}\n`), {
+ advanceFreshness: false,
+ });
+}
+
+describe('QA-004: D2 force-resolve produces NO duplicated span (occurrence-count oracle)', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => vi.useRealTimers());
+
+ test('PENDING_LINE occurrence count is never >=2 at ANY window; dropped-and-checkpointed at force-resolve, never doubled', () => {
+ const rig = createBridgeRaceRig({ docName: 'qa004-count.md' });
+ const before = getMetrics().deriveTimingDeferForceResolved;
+ try {
+ stageUnpropagatedKeystroke(rig);
+
+ let forced = false;
+ let maxFragCount = 0;
+ let maxYtextCount = 0;
+ for (let i = 0; i < MAX_DRAINS && !forced; i++) {
+ const frag = rig.serializeFragment();
+ const yt = rig.ytext.toString();
+ const fc = count(frag, PENDING_LINE);
+ const yc = count(yt, PENDING_LINE);
+ maxFragCount = Math.max(maxFragCount, fc);
+ maxYtextCount = Math.max(maxYtextCount, yc);
+ // P0 INVARIANT: the pending line is NEVER doubled anywhere.
+ expect(fc).toBeLessThanOrEqual(1);
+ expect(yc).toBeLessThanOrEqual(1);
+ // Base content (seed) must also never duplicate.
+ expect(count(frag, 'Intro paragraph.')).toBe(1);
+ sourceWrite(rig, `trailing-${i}`);
+ forced = getMetrics().deriveTimingDeferForceResolved > before;
+ }
+ expect(forced).toBe(true);
+
+ // Post force-resolve: dropped-and-checkpointed (count 0), NEVER 2.
+ const fragAfter = rig.serializeFragment();
+ const ytAfter = rig.ytext.toString();
+ expect(count(fragAfter, PENDING_LINE)).toBe(0);
+ expect(count(ytAfter, PENDING_LINE)).toBe(0);
+ // The base line survives exactly once (not lost, not doubled).
+ expect(count(fragAfter, 'Intro paragraph.')).toBe(1);
+ expect(getMetrics().deriveTimingDeferForceResolved).toBe(before + 1);
+
+ console.log(
+ `[QA-004] max fragCount=${maxFragCount} max ytextCount=${maxYtextCount} (both must be <=1); post-resolve fragCount=${count(fragAfter, PENDING_LINE)}`,
+ );
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
+
+describe('QA-005: D4 backstop freeze mutates NOTHING system-authored (raw-granularity oracle)', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => vi.useRealTimers());
+
+ const tableA = '| a | alpha |\n| - | - |\n| 1 | 2 | \n';
+ const tableB = '| a | bravo |\n| - | - |\n| 1 | 2 | \n';
+
+ test('across the freeze window with NO input, Y.Text raw bytes AND raw fragment structure are byte-identical (not just canonical md)', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'qa005-freeze-noinput.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ for (let i = 0; i < 24 && trips.length === 0; i++)
+ rig.seedSource(i % 2 === 0 ? tableA : tableB);
+ expect(trips.length).toBe(1); // backstop tripped -> B-direction frozen
+
+ // Raw-granularity snapshots (NOT canonical serializeFragment()).
+ const ytextRaw0 = rig.ytext.toString();
+ const fragRaw0 = rig.xmlFragment.toString();
+ const fragMd0 = rig.serializeFragment();
+
+ // No authored input: drive ambient byte-neutral A-rounds through the freeze.
+ for (let i = 0; i < 6; i++) {
+ rig.forceARound({ advanceFreshness: false });
+ expect(rig.ytext.toString()).toBe(ytextRaw0); // zero SYSTEM-authored Y.Text mutation
+ expect(rig.xmlFragment.toString()).toBe(fragRaw0); // raw fragment structure unmutated
+ expect(rig.serializeFragment()).toBe(fragMd0);
+ }
+ console.log('[QA-005] no-input freeze: ytext + RAW fragment byte-stable across 6 rounds');
+ } finally {
+ rig.cleanup();
+ }
+ });
+
+ test('typing during the freeze: the ONLY Y.Text delta is the authored keystrokes; raw fragment stays frozen (B not re-derived)', () => {
+ const trips: number[] = [];
+ const rig = createBridgeRaceRig({
+ docName: 'qa005-freeze-typing.md',
+ setupOverrides: { onReDeriveBackstop: (r) => trips.push(r) },
+ });
+ try {
+ for (let i = 0; i < 24 && trips.length === 0; i++)
+ rig.seedSource(i % 2 === 0 ? tableA : tableB);
+ expect(trips.length).toBe(1);
+
+ const ytextRaw0 = rig.ytext.toString();
+ const fragRaw0 = rig.xmlFragment.toString();
+
+ // Type an authored line via a source (Y.Text) edit during the freeze.
+ const AUTHORED = 'USER_TYPED_DURING_FREEZE';
+ rig.externalYtextEdit('type', (yt) => yt.insert(yt.length, `\n${AUTHORED}\n`), {
+ advanceFreshness: false,
+ });
+
+ const ytextRaw1 = rig.ytext.toString();
+ // Y.Text delta is EXACTLY the authored insert (subset-of-authored-inputs).
+ expect(ytextRaw1).toBe(`${ytextRaw0}\n${AUTHORED}\n`);
+ expect(count(ytextRaw1, AUTHORED)).toBe(1);
+ // Raw fragment unchanged: B is frozen, the source edit does NOT re-derive.
+ expect(rig.xmlFragment.toString()).toBe(fragRaw0);
+ console.log(
+ '[QA-005] typing-during-freeze: only authored delta in Y.Text; raw fragment frozen',
+ );
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
+
+describe('QA-006: D15 pre-drain applies the pending keystroke exactly ONCE (occurrence-count oracle)', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => vi.useRealTimers());
+
+ test('CROSS-BLOCK undo: keystroke count===1 in Y.Text AND fragment after the paired op AND after the next natural drain', async () => {
+ const rig = await createWiredPreDrainRig({ docName: 'qa006-undo.md' });
+ try {
+ rig.agentWrite('Agent appended line.', 'append');
+ rig.stageUnpropagatedKeystroke();
+ expect(count(rig.serializeFragment(), WIRED_PENDING_LINE)).toBe(1);
+ expect(count(rig.ytextString(), WIRED_PENDING_LINE)).toBe(0); // un-propagated pre-flush
+
+ const undone = rig.agentUndo('last');
+ expect(undone).toBe(true);
+
+ // Exactly-once after the paired op (never pre-drain flush + a doubled derive).
+ expect(count(rig.ytextString(), WIRED_PENDING_LINE)).toBe(1);
+ expect(count(rig.serializeFragment(), WIRED_PENDING_LINE)).toBe(1);
+ // Agent op exactly reverted.
+ expect(count(rig.ytextString(), 'Agent appended line.')).toBe(0);
+ expect(count(rig.serializeFragment(), 'Agent appended line.')).toBe(0);
+
+ // After a subsequent NATURAL drain: still exactly once (no re-application).
+ rig.agentWrite('Second agent line.', 'append');
+ expect(count(rig.ytextString(), WIRED_PENDING_LINE)).toBe(1);
+ expect(count(rig.serializeFragment(), WIRED_PENDING_LINE)).toBe(1);
+ // STALE_LINE prefix must not create a phantom second copy of pending.
+ expect(count(rig.ytextString(), WIRED_STALE_LINE)).toBe(1);
+ console.log('[QA-006] cross-block undo: keystroke count===1 post-op AND post-natural-drain');
+ } finally {
+ await rig.cleanup();
+ }
+ });
+
+ test('CROSS-BLOCK append: keystroke count===1 in Y.Text AND fragment after the paired op AND after a further drain', async () => {
+ const rig = await createWiredPreDrainRig({ docName: 'qa006-append.md' });
+ try {
+ rig.stageUnpropagatedKeystroke();
+ expect(count(rig.serializeFragment(), WIRED_PENDING_LINE)).toBe(1);
+
+ rig.agentWriteWithPreDrain('A fresh agent paragraph.', 'append');
+ expect(count(rig.ytextString(), WIRED_PENDING_LINE)).toBe(1);
+ expect(count(rig.serializeFragment(), WIRED_PENDING_LINE)).toBe(1);
+ expect(count(rig.ytextString(), 'A fresh agent paragraph.')).toBe(1);
+
+ // Further natural drain: no re-application (post-flush witness bookkeeping).
+ rig.agentWrite('Another paragraph.', 'append');
+ expect(count(rig.ytextString(), WIRED_PENDING_LINE)).toBe(1);
+ expect(count(rig.serializeFragment(), WIRED_PENDING_LINE)).toBe(1);
+ console.log(
+ '[QA-006] cross-block append: keystroke count===1 post-op AND post-further-drain',
+ );
+ } finally {
+ await rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/qa-gc-budget-isolation.test.ts b/packages/server/src/qa-gc-budget-isolation.test.ts
new file mode 100644
index 000000000..30c00506d
--- /dev/null
+++ b/packages/server/src/qa-gc-budget-isolation.test.ts
@@ -0,0 +1,128 @@
+/**
+ * Per-kind checkpoint retention isolation for the three newest surfaced kinds.
+ *
+ * `shadow-repo.test.ts` already proves the budget mechanism and the isolation
+ * claim for `bridge-merge-loss` vs `producer-guard-loss`. The three kinds added
+ * with the derive-timing guard, the paired-intake detector, and the re-derive
+ * backstop have no such arm, and `gcCheckpointRefs` reaches them through a
+ * hand-written `byKind` literal plus one `planDeletions` call per kind — a
+ * shape where a missing or mis-wired line silently routes a kind into a
+ * sibling's budget (or into no budget at all) with every existing test green.
+ *
+ * The failure this pins is user-visible: a mechanism that trips in a burst
+ * (repeated defer exhaustions) must not age out the recovery anchors a user
+ * still needs from a quieter mechanism.
+ *
+ */
+
+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';
+
+const BUDGET = 5;
+const OVER = BUDGET + 4;
+
+let tmpDir: string;
+let shadow: ShadowHandle;
+
+beforeEach(async () => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-gc-budget-'));
+ const 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 });
+});
+
+describe('checkpoint GC budgets for the derive-guard / detector / backstop kinds', () => {
+ test('a defer-exhaustion burst evicts only its own bucket and leaves every sibling anchor retained', async () => {
+ for (let i = 0; i < OVER; i++) {
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind: 'defer-exhaustion-loss',
+ docName: `noisy-${i}.md`,
+ contents: `pending line ${i}\n`,
+ label: `defer exhaustion ${i}`,
+ metadata: { deferCount: 9 },
+ });
+ }
+ // One anchor of every other surfaced kind, each inside its own budget.
+ const anchors = [
+ { kind: 'bridge-merge-loss', metadata: { lostSubstrings: ['anchor'] } },
+ { kind: 'producer-guard-loss', metadata: { construct: 'table' } },
+ { kind: 'observer-a-duplication', metadata: { duplicatedLineCount: 1 } },
+ { kind: 'external-change-rescue', metadata: { incomingDiskSha: 'deadbeef' } },
+ { kind: 'bridge-derive-loss', metadata: { lostSubstrings: ['anchor'] } },
+ { kind: 'bridge-backstop-trip', metadata: { rounds: 8 } },
+ ] as const;
+ for (const anchor of anchors) {
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ ...anchor,
+ docName: `anchor-${anchor.kind}.md`,
+ contents: `anchor body for ${anchor.kind}\n`,
+ label: `anchor ${anchor.kind}`,
+ });
+ }
+
+ const result = await gcCheckpointRefs(shadow, 'main', {
+ ...DEFAULT_CHECKPOINT_RETENTION,
+ maxDeferExhaustionLoss: BUDGET,
+ ttlMs: 0,
+ });
+
+ expect(result.scanned).toBe(OVER + anchors.length);
+ expect(result.deletedDeferExhaustionLoss).toBe(OVER - BUDGET);
+ // Every sibling budget is untouched — the burst cannot reach across.
+ expect(result.deletedBridgeMergeLoss).toBe(0);
+ expect(result.deletedProducerGuardLoss).toBe(0);
+ expect(result.deletedObserverADuplication).toBe(0);
+ expect(result.deletedExternalChangeRescue).toBe(0);
+ expect(result.deletedBridgeDeriveLoss).toBe(0);
+ expect(result.deletedBridgeBackstopTrip).toBe(0);
+ expect(result.deletedAutoConsolidation).toBe(0);
+ }, 60_000);
+
+ test('bridge-derive-loss and bridge-backstop-trip each carry their own budget', async () => {
+ for (let i = 0; i < OVER; i++) {
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind: 'bridge-derive-loss',
+ docName: `derive-${i}.md`,
+ contents: `derive body ${i}\n`,
+ label: `derive loss ${i}`,
+ metadata: { lostSubstrings: [`derive-${i}`] },
+ });
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind: 'bridge-backstop-trip',
+ docName: `backstop-${i}.md`,
+ contents: `backstop body ${i}\n`,
+ label: `backstop trip ${i}`,
+ metadata: { rounds: 8 },
+ });
+ }
+
+ const result = await gcCheckpointRefs(shadow, 'main', {
+ ...DEFAULT_CHECKPOINT_RETENTION,
+ maxBridgeDeriveLoss: BUDGET,
+ maxBridgeBackstopTrip: OVER,
+ ttlMs: 0,
+ });
+
+ // Only the kind whose budget was exceeded loses refs.
+ expect(result.deletedBridgeDeriveLoss).toBe(OVER - BUDGET);
+ expect(result.deletedBridgeBackstopTrip).toBe(0);
+ }, 60_000);
+});
diff --git a/packages/server/src/qa-sweep-lens.test.ts b/packages/server/src/qa-sweep-lens.test.ts
new file mode 100644
index 000000000..8b08076e7
--- /dev/null
+++ b/packages/server/src/qa-sweep-lens.test.ts
@@ -0,0 +1,237 @@
+/**
+ * Whole-document sweeps that the per-mechanism suites cannot express.
+ *
+ * Three questions, each answered against the final settled state rather than a
+ * single assertion inside one mechanism\'s arm: does the document contain any
+ * span neither the user nor the agent authored (the merge-resurrection class);
+ * do the churned interleavings converge to a byte fixed point with every
+ * mechanism enabled at once; and is checkpointed content ever re-inserted into
+ * the live document without an explicit restore.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import simpleGit from 'simple-git';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { type BridgeRaceRig, createBridgeRaceRig } from './bridge-race-rig.test-helper.ts';
+import { getMetrics } from './metrics.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+function count(hay: string, needle: string): number {
+ if (needle === '') return 0;
+ let n = 0;
+ let i = hay.indexOf(needle);
+ while (i !== -1) {
+ n++;
+ i = hay.indexOf(needle, i + needle.length);
+ }
+ return n;
+}
+
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+const PENDING_LINE = 'Step one body.';
+const STALE_LINE = 'Step one bod';
+const CONTENT_ROOT = 'content/docs';
+
+function stageUnpropagatedKeystroke(rig: BridgeRaceRig): void {
+ rig.editFragment(GEN1);
+ rig.settle(1);
+ rig.externalYtextEdit('poke', (yt) => yt.insert(yt.length, '\nTrailing.\n'));
+ rig.echoFragmentEdit(rig.ytext.toString(), STALE_LINE, PENDING_LINE, { advanceFreshness: false });
+}
+function sourceWrite(rig: BridgeRaceRig, text: string): void {
+ rig.externalYtextEdit('source-write', (yt) => yt.insert(yt.length, `\n${text}\n`), {
+ advanceFreshness: false,
+ });
+}
+
+describe('QA-007: abrupt-insertion sweep — no content exists that no one authored', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => vi.useRealTimers());
+
+ test('after a completed force-resolve mechanism run, every line in final Y.Text is present in the authored ledger; zero unauthored spans', () => {
+ const rig = createBridgeRaceRig({ docName: 'qa007-sweep.md' });
+ const before = getMetrics().deriveTimingDeferForceResolved;
+ // Authored-input ledger: every byte a user/agent/seed actually wrote.
+ const authored: string[] = [GEN1, '\nTrailing.\n', PENDING_LINE, STALE_LINE];
+ try {
+ stageUnpropagatedKeystroke(rig);
+ for (let i = 0; i < 30; i++) {
+ const t = `trailing-${i}`;
+ authored.push(`\n${t}\n`);
+ sourceWrite(rig, t);
+ if (getMetrics().deriveTimingDeferForceResolved > before) break;
+ }
+ // PRECONDITION — the mechanism this test is titled for actually ran. The
+ // loop exits by `break`, so without this the suite would pass having
+ // exhausted every iteration with the force-resolve never firing; the
+ // checkpoint-restore sweep below asserts the same counter for the same
+ // reason.
+ expect(getMetrics().deriveTimingDeferForceResolved).toBe(before + 1);
+
+ // Normalized authored union (documented canonicalization tolerance: the
+ // bridge collapses blank-line runs, e.g. '## H\nP' -> '## H\n\nP'; compare
+ // per-line trimmed against the concatenated union rather than blanket-fuzzy).
+ const union = authored.join('\n');
+ const finalYtext = rig.ytext.toString();
+ const finalFragMd = rig.serializeFragment();
+
+ const unauthored: string[] = [];
+ let linesScanned = 0;
+ for (const raw of [...finalYtext.split('\n'), ...finalFragMd.split('\n')]) {
+ const line = raw.trim();
+ if (line === '') continue;
+ linesScanned++;
+ if (!union.includes(line)) unauthored.push(line);
+ }
+ // NON-VACUITY — `unauthored` collects only non-blank lines, so a wiped
+ // document yields [] and satisfies the sweep. Total content loss is not a
+ // pass: the scan must have had real lines to judge, on BOTH surfaces.
+ expect(finalYtext.trim().length).toBeGreaterThan(0);
+ expect(finalFragMd.trim().length).toBeGreaterThan(0);
+ expect(linesScanned).toBeGreaterThanOrEqual(2 * authored.length);
+
+ expect(unauthored).toEqual([]); // Path-B resurrection class = a line in NEITHER set
+ // Occurrence-count oracle, both bounds. `toBeLessThanOrEqual(1)` is
+ // satisfied by 0 — i.e. by the content having been deleted outright — so
+ // the surviving-exactly-once form is the one that discriminates a
+ // duplication from a loss.
+ expect(count(finalYtext, 'Intro paragraph.')).toBe(1);
+ expect(count(finalYtext, 'Trailing.')).toBe(1);
+ expect(count(finalFragMd, 'Intro paragraph.')).toBe(1);
+ console.log(`[QA-007] final lines all authored; unauthored spans=${unauthored.length}`);
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
+
+describe('QA-008: x211 churned composition — all mechanisms ON simultaneously', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ });
+ afterEach(() => vi.useRealTimers());
+
+ test('churned-fragment interleavings converge to a byte fixed point with occurrence counts === authored and NO backstop false-trip (defaults: defer+detector+backstop+pre-drain all ON)', () => {
+ let backstopTrips = 0;
+ const rig = createBridgeRaceRig({
+ docName: 'qa008-composition.md',
+ // NO overrides that disable mechanisms -> all default-ON (deferGuard,
+ // lossDetector, fixedPointBackstop, preDrain).
+ setupOverrides: { onReDeriveBackstop: () => backstopTrips++ },
+ });
+ const backstopBefore = getMetrics().reDeriveBackstopTripped;
+ try {
+ // A churned table respell that is k=1 stable (canonical pipe-dash) — a
+ // LEGITIMATE duplication-recovery shape, not an oscillation. Drive many
+ // churned interleavings; the stack must converge.
+ for (let i = 0; i < 20; i++) {
+ rig.churnedFragmentEdit(`| a | b${i} |\n|---|---|\n| 1 | 2 |\n`);
+ }
+ // Settle to a byte fixed point.
+ const settled = rig.settle(4);
+ const lastByteChanged = settled.slice(-2).some((e) => e.byteChanged);
+
+ // Byte fixed point reached: the final forced rounds emit no byte change.
+ expect(lastByteChanged).toBe(false);
+ // Legitimate churn/recovery must NOT be frozen by the backstop.
+ expect(backstopTrips).toBe(0);
+ expect(getMetrics().reDeriveBackstopTripped).toBe(backstopBefore);
+
+ // Occurrence counts === authored: exactly one table row `b19` survives,
+ // no doubled table subtree.
+ const yt = rig.ytext.toString();
+ expect(count(yt, '| a | b19 |')).toBe(1);
+ expect(count(yt, '| 1 | 2 |')).toBe(1);
+ // Bridge coherence: re-derived fragment agrees (a doubled fragment would
+ // re-trip on the next drain).
+ const frag = rig.serializeFragment();
+ expect(count(frag, 'b19')).toBe(1);
+ console.log(
+ `[QA-008] churned composition converged; backstopTrips=${backstopTrips}; b19 count=${count(yt, '| a | b19 |')}`,
+ );
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
+
+describe('QA-009: restore is NEVER automatic — checkpoint content stays out of the live doc', () => {
+ let tmpDir: string;
+ beforeEach(async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(1_000_000);
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-qa009-'));
+ });
+ afterEach(async () => {
+ vi.useRealTimers();
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ async function setupShadow(): Promise<ShadowHandle> {
+ const projectRoot = resolve(tmpDir, 'project');
+ const contentDir = resolve(projectRoot, CONTENT_ROOT);
+ mkdirSync(contentDir, { recursive: true });
+ const git = simpleGit(projectRoot);
+ await git.init();
+ await git.raw('config', 'user.name', 'Test');
+ await git.raw('config', 'user.email', '[email protected]');
+ writeFileSync(resolve(contentDir, 'qa009.md'), '# Seed\n');
+ await git.add('.');
+ await git.commit('Initial commit');
+ return initShadowRepo(projectRoot);
+ }
+
+ test('a force-resolve checkpoint is restore-reachable via history, but its content is NEVER auto-re-inserted into the live Y.Text/fragment (no user rollback)', async () => {
+ const shadow = await setupShadow();
+ const rig = createBridgeRaceRig({
+ docName: 'qa009',
+ setupOverrides: {
+ shadow: () => shadow,
+ getBranch: () => 'main',
+ contentRoot: CONTENT_ROOT,
+ },
+ });
+ const before = getMetrics().deriveTimingDeferForceResolved;
+ try {
+ stageUnpropagatedKeystroke(rig);
+ for (let i = 0; i < 30; i++) {
+ sourceWrite(rig, `t-${i}`);
+ if (getMetrics().deriveTimingDeferForceResolved > before) break;
+ }
+ expect(getMetrics().deriveTimingDeferForceResolved).toBe(before + 1);
+
+ // The checkpointed content left the LIVE doc and was NOT silently
+ // re-inserted: recovery is restore-only, never automatic.
+ expect(count(rig.serializeFragment(), PENDING_LINE)).toBe(0);
+ expect(count(rig.ytext.toString(), PENDING_LINE)).toBe(0);
+
+ // The content is reachable ONLY through the timeline (checkpoint refs),
+ // never the Y.Doc: a defer-exhaustion-loss row carrying the pending line.
+ await vi.waitFor(async () => {
+ const hist = await getDocumentHistory(shadow, { docName: 'qa009' }, CONTENT_ROOT);
+ const cp = hist.entries.find((e) => e.checkpoint?.kind === 'defer-exhaustion-loss');
+ expect(cp?.sha).toMatch(/^[0-9a-f]{40}$/);
+ const blob = (
+ await shadowGit(shadow).raw('show', `${cp?.sha}:${CONTENT_ROOT}/qa009`)
+ ).toString();
+ expect(blob).toContain(PENDING_LINE); // restore-reachable payload
+ });
+
+ // No further drain re-inserts it: keep running the loop, live doc stays clean.
+ rig.settle(6);
+ expect(count(rig.serializeFragment(), PENDING_LINE)).toBe(0);
+ expect(count(rig.ytext.toString(), PENDING_LINE)).toBe(0);
+ console.log('[QA-009] checkpoint restore-reachable; live doc never auto-gains it');
+ } finally {
+ rig.cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/qa-watcher-intake-lens.test.ts b/packages/server/src/qa-watcher-intake-lens.test.ts
new file mode 100644
index 000000000..41044b433
--- /dev/null
+++ b/packages/server/src/qa-watcher-intake-lens.test.ts
@@ -0,0 +1,204 @@
+/**
+ * Behavioral adjudication of the disk-intake loss detector.
+ *
+ * `bridge-loss-suppression.test.ts` is a static registry sweep: it proves every
+ * paired origin carries a detect/suppress classification, not that the
+ * classification produces the right RUNTIME behavior. Nothing anywhere drives
+ * `applyExternalChange` with a dirty fragment, so the required dirty-open-doc
+ * positive (`site: 'file-watcher-intake'`) is asserted at no rung — the
+ * detector-trip constant is referenced only by direct `reporter(...)` calls in
+ * the detector's own unit test, never through the intake path that ships it.
+ *
+ * This also settles the branch-switch question. A branch switch resets each
+ * open doc through the SAME call this exercises — `applyToDoc` in
+ * `server-factory.ts` is a thin wrapper over `applyExternalChange` under
+ * `FILE_WATCHER_ORIGIN`, which the registry classifies `detect` — so the
+ * clean/dirty split measured here is the branch-switch behavior too: a clean
+ * open doc cannot false-positive, and a dirty one trips because the user's
+ * un-propagated editor content really is about to be rebuilt away.
+ *
+ */
+
+import { Hocuspocus } from '@hocuspocus/server';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import * as Y from 'yjs';
+import type { DeriveLossObservation } from './bridge-loss-detector.ts';
+import {
+ DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE,
+ detectPairedIntakeLoss,
+} from './bridge-loss-detector.ts';
+import { DocumentDurabilityState } from './document-durability-state.ts';
+import { applyExternalChange } from './external-change.ts';
+import { mdManager } from './md-manager.ts';
+
+const BASE = '# Notes\n\nsettled body line\n';
+const NEXT_FROM_DISK = '# Notes\n\nsettled body line\n\ndisk-authored line\n';
+const PENDING = 'un-propagated keystroke line';
+
+interface Trip {
+ docName: string;
+ obs: DeriveLossObservation;
+ writerId?: string | null;
+ site?: string;
+}
+
+let hp: Hocuspocus;
+let durabilityState: DocumentDurabilityState;
+let trips: Trip[];
+
+beforeEach(() => {
+ hp = new Hocuspocus({ quiet: true });
+ durabilityState = new DocumentDurabilityState();
+ trips = [];
+});
+afterEach(() => {
+ trips = [];
+});
+
+const reporter = (
+ docName: string,
+ obs: DeriveLossObservation,
+ writerId?: string | null,
+ site?: string,
+) => {
+ trips.push({ docName, obs, writerId, site });
+};
+
+/** Lines the detector judges lost for a recorded trip. */
+function lostLines(trip: Trip): string[] {
+ return detectPairedIntakeLoss(trip.obs);
+}
+
+async function openDoc(docName: string): Promise<Y.Doc> {
+ const conn = await hp.openDirectConnection(docName);
+ const doc = (conn as unknown as { document: Y.Doc }).document;
+ if (!doc) throw new Error('DirectConnection has no document');
+ // Establish a settled bridge state through the shipped intake path.
+ applyExternalChange(durabilityState, hp, docName, BASE);
+ return doc;
+}
+
+/** Append a paragraph to the fragment WITHOUT touching Y.Text — a dirty doc. */
+function stagePendingFragmentLine(doc: Y.Doc, text: string): void {
+ const frag = doc.getXmlFragment('default');
+ const para = new Y.XmlElement('paragraph');
+ para.insert(0, [new Y.XmlText(text)]);
+ frag.insert(frag.length, [para]);
+}
+
+describe('disk intake through applyExternalChange (the branch-switch reset path)', () => {
+ test('a CLEAN open doc converges with no detector trip (no false positive)', async () => {
+ const docName = 'watcher-clean';
+ const doc = await openDoc(docName);
+ trips.length = 0;
+
+ applyExternalChange(
+ durabilityState,
+ hp,
+ docName,
+ NEXT_FROM_DISK,
+ undefined,
+ undefined,
+ reporter,
+ );
+
+ expect(doc.getText('source').toString()).toContain('disk-authored line');
+ // PRECONDITION — the detector actually RAN on this intake. Without it, "no
+ // trip carried lost lines" is satisfied by the reporter never being wired
+ // at all, so deleting the `detect` construction in `applyExternalChange`
+ // would leave this arm green.
+ expect(trips.length).toBeGreaterThanOrEqual(1);
+ expect(trips.every((t) => t.site === DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE)).toBe(true);
+ const withLoss = trips.filter((t) => lostLines(t).length > 0);
+ expect(withLoss).toEqual([]);
+ });
+
+ test('a DIRTY open doc trips site=file-watcher-intake naming the un-propagated line', async () => {
+ const docName = 'watcher-dirty';
+ const doc = await openDoc(docName);
+ stagePendingFragmentLine(doc, PENDING);
+ // Precondition: the fragment really does hold content Y.Text does not.
+ expect(doc.getText('source').toString()).not.toContain(PENDING);
+ trips.length = 0;
+
+ applyExternalChange(
+ durabilityState,
+ hp,
+ docName,
+ NEXT_FROM_DISK,
+ undefined,
+ undefined,
+ reporter,
+ );
+
+ const losses = trips.filter((t) => lostLines(t).length > 0);
+ expect(losses.length).toBeGreaterThanOrEqual(1);
+ const trip = losses[0];
+ expect(trip?.site).toBe(DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE);
+ expect(trip?.docName).toBe(docName);
+ expect(lostLines(trip as Trip)).toContain(PENDING);
+ // The disk write still lands — detection observes the loss, it does not veto.
+ expect(doc.getText('source').toString()).toContain('disk-authored line');
+ });
+
+ test('with no reporter wired the intake stays serialize-free and silent', async () => {
+ // `expect(trips).toEqual([])` alone is true by construction — nothing can
+ // push to `trips` when no reporter is handed in. The claim with teeth is the
+ // SERIALIZE-FREE half: the detector's four canonicalizing serializes
+ // (pendingBody, rebuiltBody, ytextDerivedBody, baselineBody) must be paid
+ // only when a detector is wired. Measure the same staging both ways.
+ const spy = vi.spyOn(mdManager, 'serialize');
+ try {
+ const unwiredDoc = await openDoc('watcher-no-reporter');
+ stagePendingFragmentLine(unwiredDoc, PENDING);
+ trips.length = 0;
+ spy.mockClear();
+ applyExternalChange(durabilityState, hp, 'watcher-no-reporter', NEXT_FROM_DISK);
+ const unwiredSerializes = spy.mock.calls.length;
+
+ const wiredDoc = await openDoc('watcher-with-reporter');
+ stagePendingFragmentLine(wiredDoc, PENDING);
+ trips.length = 0;
+ spy.mockClear();
+ applyExternalChange(
+ durabilityState,
+ hp,
+ 'watcher-with-reporter',
+ NEXT_FROM_DISK,
+ undefined,
+ undefined,
+ reporter,
+ );
+ const wiredSerializes = spy.mock.calls.length;
+
+ // Off costs nothing extra; on pays for the canonicalization it needs.
+ expect(unwiredSerializes).toBe(0);
+ expect(wiredSerializes).toBeGreaterThan(unwiredSerializes);
+ // ...and the differential really is the detector: the wired run tripped.
+ expect(trips.length).toBeGreaterThanOrEqual(1);
+ // Both land the disk write regardless of whether anyone is watching.
+ expect(unwiredDoc.getText('source').toString()).toContain('disk-authored line');
+ expect(wiredDoc.getText('source').toString()).toContain('disk-authored line');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ /**
+ * A byte-identical re-apply — the shape a branch switch produces when the doc
+ * is the same on both branches — must not manufacture a loss verdict.
+ *
+ */
+ test('a byte-identical re-apply over a clean doc reports no loss', async () => {
+ const docName = 'watcher-identical';
+ await openDoc(docName);
+ trips.length = 0;
+
+ applyExternalChange(durabilityState, hp, docName, BASE, undefined, undefined, reporter);
+
+ // Same precondition as the clean arm: the detector ran and returned a
+ // no-loss verdict, rather than never having been consulted.
+ expect(trips.length).toBeGreaterThanOrEqual(1);
+ expect(trips.filter((t) => lostLines(t).length > 0)).toEqual([]);
+ });
+});
diff --git a/packages/server/src/reconcile-intake-loss.test.ts b/packages/server/src/reconcile-intake-loss.test.ts
new file mode 100644
index 000000000..9929e97f5
--- /dev/null
+++ b/packages/server/src/reconcile-intake-loss.test.ts
@@ -0,0 +1,167 @@
+/**
+ * The L1 reconcile-before-agent-write is an INSTRUMENTED paired intake.
+ *
+ * `reconcileDiskBeforeAgentWrite` runs ahead of every agent content write and
+ * ingests a divergent out-of-band disk edit through `applyExternalChange` under
+ * `FILE_WATCHER_ORIGIN` — a real paired derive that rebuilds the fragment over
+ * whatever the open doc held. When that doc is DIRTY (its fragment carries a
+ * WYSIWYG keystroke Y.Text never absorbed), the rebuild discards it. That is
+ * exactly the "dirty-open-doc watcher positive" the file-watcher origin is
+ * classified `detect` for, on the hottest intake path in the server — so the
+ * reconcile must forward the derive-loss reporter, not drop it.
+ */
+
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Hocuspocus } from '@hocuspocus/server';
+import { sharedExtensions } from '@inkeep/open-knowledge-core';
+import { getSchema } from '@tiptap/core';
+import { updateYFragment } from '@tiptap/y-tiptap';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import type * as Y from 'yjs';
+import {
+ type BridgeDeriveLossReporter,
+ DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE,
+ type DeriveLossObservation,
+ detectPairedIntakeLoss,
+} from './bridge-loss-detector.ts';
+import { DocumentDurabilityState } from './document-durability-state.ts';
+import { reconcileDiskBeforeAgentWrite } from './external-change.ts';
+import { mdManager } from './md-manager.ts';
+
+const schema = getSchema(sharedExtensions);
+
+const BASE = '# Notes\n\nFirst paragraph.\n';
+const DISK_EDIT = '# Notes\n\nFirst paragraph, edited on disk.\n';
+const PENDING_LINE = 'A keystroke that never reached Y.Text.';
+
+interface Trip {
+ docName: string;
+ obs: DeriveLossObservation;
+ writerId?: string | null;
+ site?: string;
+}
+
+describe('reconcileDiskBeforeAgentWrite paired-intake instrumentation', () => {
+ let hp: Hocuspocus;
+ let durabilityState: DocumentDurabilityState;
+ let contentDir: string;
+
+ beforeEach(() => {
+ hp = new Hocuspocus({ quiet: true });
+ durabilityState = new DocumentDurabilityState();
+ // realpath: macOS tmpdir is a symlink, and the reconcile's own
+ // symlink-escape guard compares the realpath'd file against contentDir.
+ contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-reconcile-intake-')));
+ });
+ afterEach(() => {
+ rmSync(contentDir, { recursive: true, force: true });
+ });
+
+ test('a divergent disk edit ingested over a dirty open doc reports the derive loss', async () => {
+ const docName = 'dirty-reconcile';
+ const conn = await hp.openDirectConnection(docName);
+ const doc = (conn as unknown as { document: Y.Doc }).document;
+ try {
+ // The doc rests at BASE on disk and in the CRDT.
+ writeFileSync(join(contentDir, `${docName}.md`), BASE);
+ durabilityState.setReconciledBase(docName, BASE);
+ doc.transact(() => {
+ doc.getText('source').insert(0, BASE);
+ updateYFragment(
+ doc,
+ doc.getXmlFragment('default'),
+ schema.nodeFromJSON(mdManager.parse(BASE)),
+ { mapping: new Map(), isOMark: new Map() },
+ );
+ }, 'test-seed');
+
+ // A WYSIWYG keystroke lands in the FRAGMENT only — Y.Text never absorbed
+ // it (the un-propagated window the whole guard family exists for).
+ doc.transact(() => {
+ updateYFragment(
+ doc,
+ doc.getXmlFragment('default'),
+ schema.nodeFromJSON(mdManager.parse(`${BASE}\n${PENDING_LINE}\n`)),
+ { mapping: new Map(), isOMark: new Map() },
+ );
+ }, 'test-wysiwyg');
+ expect(doc.getText('source').toString()).not.toContain(PENDING_LINE);
+
+ // Meanwhile the file changed out of band.
+ writeFileSync(join(contentDir, `${docName}.md`), DISK_EDIT);
+
+ const trips: Trip[] = [];
+ const reporter: BridgeDeriveLossReporter = (name, obs, writerId, site) => {
+ trips.push({ docName: name, obs, writerId, site });
+ };
+
+ const result = reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hp,
+ docName,
+ contentDir,
+ undefined,
+ reporter,
+ );
+
+ // The ingest happened and the rebuild discarded the pending keystroke.
+ expect(result.reconciled).toBe(true);
+ expect(doc.getText('source').toString()).toContain('edited on disk');
+
+ // ...and the loss was OBSERVED: the reporter fired for this doc under the
+ // file-watcher-intake site, with a verdict that names the lost content.
+ expect(trips.length).toBe(1);
+ const trip = trips[0];
+ expect(trip?.docName).toBe(docName);
+ expect(trip?.site).toBe(DERIVE_LOSS_SITE_FILE_WATCHER_INTAKE);
+ expect(trip?.obs.pendingBody).toContain(PENDING_LINE);
+ const dropped = trip ? detectPairedIntakeLoss(trip.obs) : [];
+ expect(dropped.join('\n')).toContain(PENDING_LINE);
+ // The restore payload reconstructs the document that held it.
+ expect(trip?.obs.restorePayload).toContain(PENDING_LINE);
+ } finally {
+ await conn.disconnect();
+ }
+ });
+
+ test('a clean open doc reconciles without a spurious trip', async () => {
+ const docName = 'clean-reconcile';
+ const conn = await hp.openDirectConnection(docName);
+ const doc = (conn as unknown as { document: Y.Doc }).document;
+ try {
+ writeFileSync(join(contentDir, `${docName}.md`), BASE);
+ durabilityState.setReconciledBase(docName, BASE);
+ doc.transact(() => {
+ doc.getText('source').insert(0, BASE);
+ updateYFragment(
+ doc,
+ doc.getXmlFragment('default'),
+ schema.nodeFromJSON(mdManager.parse(BASE)),
+ { mapping: new Map(), isOMark: new Map() },
+ );
+ }, 'test-seed');
+ writeFileSync(join(contentDir, `${docName}.md`), DISK_EDIT);
+
+ const trips: Trip[] = [];
+ const result = reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hp,
+ docName,
+ contentDir,
+ undefined,
+ (name, obs, writerId, site) => trips.push({ docName: name, obs, writerId, site }),
+ );
+
+ expect(result.reconciled).toBe(true);
+ // The reporter may observe, but the verdict must be empty — a disk edit
+ // replacing PROPAGATED content is not a loss.
+ for (const trip of trips) {
+ expect(detectPairedIntakeLoss(trip.obs)).toEqual([]);
+ }
+ } finally {
+ await conn.disconnect();
+ }
+ });
+});
diff --git a/packages/server/src/rename-log.test.ts b/packages/server/src/rename-log.test.ts
index 055dd82fa..e51bec9e6 100644
--- a/packages/server/src/rename-log.test.ts
+++ b/packages/server/src/rename-log.test.ts
@@ -695,14 +695,9 @@ describe('rename-log read primitives (shadow-repo backed)', () => {
test('resolveDocPathAtCommit — unrenamed doc, current path exists at sha → returns current path', async () => {
const sha = await commit('# A\n', 'a.md', 'WIP: a');
const index = createEmptyIndex();
- const path = await resolveDocPathAtCommit(
- shadow,
- 'a',
- sha,
- 'main',
- index,
- (n) => `content/${n}.md`,
- );
+ const path = await resolveDocPathAtCommit(shadow, 'a', sha, 'main', index, (n) => [
+ `content/${n}.md`,
+ ]);
expect(path).toBe('content/a.md');
});
@@ -710,14 +705,9 @@ describe('rename-log read primitives (shadow-repo backed)', () => {
const index = createEmptyIndex();
// 40-char hex SHA that is highly unlikely to exist
const fakeSha = 'deadbeef'.repeat(5);
- const path = await resolveDocPathAtCommit(
- shadow,
- 'a',
- fakeSha,
- 'main',
- index,
- (n) => `content/${n}.md`,
- );
+ const path = await resolveDocPathAtCommit(shadow, 'a', fakeSha, 'main', index, (n) => [
+ `content/${n}.md`,
+ ]);
expect(path).toBeNull();
});
@@ -741,14 +731,9 @@ describe('rename-log read primitives (shadow-repo backed)', () => {
);
// Should resolve commitA (a pre-rename SHA) to its historical path.
- const path = await resolveDocPathAtCommit(
- shadow,
- 'b',
- commitA,
- 'main',
- index,
- (n) => `content/${n}.md`,
- );
+ const path = await resolveDocPathAtCommit(shadow, 'b', commitA, 'main', index, (n) => [
+ `content/${n}.md`,
+ ]);
expect(path).toBe('content/a.md');
});
@@ -782,14 +767,9 @@ describe('rename-log read primitives (shadow-repo backed)', () => {
// because seeds(R) excludes K2 (post-R checkpoint) and newACommit is
// a parentless post-saveVersion commit on cycle 3's WIP ref.
// → returns null
- const path = await resolveDocPathAtCommit(
- shadow,
- 'b',
- newACommit,
- 'main',
- index,
- (n) => `content/${n}.md`,
- );
+ const path = await resolveDocPathAtCommit(shadow, 'b', newACommit, 'main', index, (n) => [
+ `content/${n}.md`,
+ ]);
expect(path).toBeNull();
});
diff --git a/packages/server/src/rename-log.ts b/packages/server/src/rename-log.ts
index d40bf55c3..2003e7500 100644
--- a/packages/server/src/rename-log.ts
+++ b/packages/server/src/rename-log.ts
@@ -887,12 +887,17 @@ export function batchCheckExistence(
const lines = stdout.split('\n').filter((l) => l.length > 0);
// Each input line `<sha>:<path>` produces one output line:
// missing: `<sha>:<path> missing`
- // present: `<sha>:<path> <hash> <type> <size>`
- // Output order matches input order (per git docs). Map line→bool.
+ // present: `<oid> <type> <size>`
+ // Output order matches input order (per git docs). Count only `blob`
+ // presence: a doc-content probe that resolves to a `tree` is a directory
+ // sharing the doc's name, not the document — treating it as present would
+ // let the extension-less restore probe (and history-row filter) match a
+ // folder and then `git show` its listing as content.
const result: boolean[] = probes.map((_, i) => {
const line = lines[i];
if (!line) return false;
- return !line.endsWith(' missing');
+ const parts = line.split(' ');
+ return parts.length === 3 && parts[1] === 'blob';
});
settle(result);
});
@@ -1448,12 +1453,18 @@ function lookupBranchInMap(map: Map<string, Set<string>>, sha: string): string {
* Resolve the historical path of `currentDocName` at `commitSha`, scoped by
* the cycle bound for each predecessor.
*
+ * `pathCandidatesFor` yields the ordered tree-path candidates for a name: a
+ * doc's blob can live at the extension-full disk path (full-tree checkpoints,
+ * WIP snapshots) or at the extension-less docName path (the single-blob trees
+ * `saveInMemoryCheckpoint` writes). Higher-priority candidates come first, and
+ * the first candidate that resolves to a blob (across all chain steps, in
+ * newest→oldest order) wins.
+ *
* Reachability work is parallelized across predecessors and all surviving
* `(sha, path)` probes are amortized into a single `git cat-file
* --batch-check` stream — matches the batched design intent in
- * `filterEntriesByChain`. First match in newest→oldest order wins. Returns
- * `null` when no historical path matches — caller decides whether to 404
- * or fall through.
+ * `filterEntriesByChain`. Returns `null` when no candidate matches — caller
+ * decides whether to 404 or fall through.
*/
export async function resolveDocPathAtCommit(
shadow: ShadowHandle,
@@ -1461,7 +1472,7 @@ export async function resolveDocPathAtCommit(
commitSha: string,
branch: string,
index: RenameLogIndex,
- pathFor: (docName: string) => string,
+ pathCandidatesFor: (docName: string) => readonly string[],
cache?: AncestorShaSetCache,
seedsCache?: SeedsCache,
): Promise<string | null> {
@@ -1479,13 +1490,18 @@ export async function resolveDocPathAtCommit(
);
// Phase 2: build the probe list in newest→oldest priority order, dropping
- // predecessor steps whose cycle bound rejects the target sha.
+ // predecessor steps whose cycle bound rejects the target sha. Each step
+ // contributes its candidates in priority order (extension-full before
+ // extension-less), so a full-tree checkpoint matches its disk path before
+ // an extension-less twin is ever considered.
const probes: Array<{ sha: string; path: string }> = [];
for (let i = chain.length - 1; i >= 0; i--) {
const step = chain[i];
const ancestors = predecessorAncestors[i];
if (ancestors !== null && !ancestors.has(commitSha)) continue;
- probes.push({ sha: commitSha, path: pathFor(step.path) });
+ for (const path of pathCandidatesFor(step.path)) {
+ probes.push({ sha: commitSha, path });
+ }
}
if (probes.length === 0) return null;
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index c393bcfac..307bdf2a2 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -62,6 +62,10 @@ import { HocuspocusAuthRejection, parseHocuspocusAuthToken } from './auth-token-
import { BacklinkIndex } from './backlink-index.ts';
import { shellEscape } from './bash/shell-escape.ts';
import { bootElapsedMs, recordBootPhase, setBootField } from './boot-timings.ts';
+import {
+ type BridgeDeriveLossReporter,
+ createBridgeDeriveLossReporter,
+} from './bridge-loss-detector.ts';
import {
CC1Broadcaster,
isConfigDoc,
@@ -125,6 +129,7 @@ import { errnoCode } from './http/handler-utils.ts';
import { createLiveDerivedIndexExtension } from './live-derived-index.ts';
import { getLogger } from './logger.ts';
import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';
+import { LossCaptureRing } from './loss-capture.ts';
import {
createMaintenanceCoordinator,
type MaintenanceCoordinator,
@@ -967,8 +972,14 @@ export function createServer(options: ServerOptions): ServerInstance {
let shadowRef: ShadowRef;
let maintenanceCoordinator: MaintenanceCoordinator | undefined;
let persistence: ReturnType<typeof createPersistenceExtension>;
+ // Constructed later in init (after the bridge-guard config read) but reached
+ // by closure from the persistence options built before it.
+ let lossRing: LossCaptureRing | undefined;
let hocuspocus: Hocuspocus;
let sessionManager: AgentSessionManager;
+ // Set at boot when the loss detector is enabled; shared by the agent-session
+ // manager (agent-undo) and the file-watcher intake path (dirty-open-doc).
+ let bridgeLossReporter: BridgeDeriveLossReporter | undefined;
let cc1Broadcaster: CC1Broadcaster | null = null;
let agentFocusBroadcaster: AgentFocusBroadcaster | null = null;
let agentPresenceBroadcaster: AgentPresenceBroadcaster | null = null;
@@ -1329,6 +1340,9 @@ export function createServer(options: ServerOptions): ServerInstance {
// otherwise register as a benign self-write and be invisible).
isRecentlyRemoved: (docName) => recentlyRemovedDocs.has(docName),
mdManager: options.mdManager,
+ // Closure-deferred like the CC1 callbacks above: the ring is constructed
+ // further down in init, after the bridge-guard config is read.
+ getLossRing: () => lossRing,
};
persistence = createPersistenceExtension({ ...persistenceOpts, durabilityState });
@@ -1848,6 +1862,10 @@ export function createServer(options: ServerOptions): ServerInstance {
authStreamHeartbeatMs,
projectDir,
resolveEmbed,
+ // Deferred read: the reporter is constructed later in init (after the loss
+ // ring) than this extension, and stays undefined when the lossDetector
+ // kill-switch is off.
+ getBridgeLossReporter: () => bridgeLossReporter,
getPrincipal: () => loadedPrincipal,
acpRegistry,
loadAcpCustomAgents: () => loadCustomAgents(lockDir, getLogger('acp-registry')),
@@ -1876,6 +1894,43 @@ export function createServer(options: ServerOptions): ServerInstance {
});
hocuspocus.configuration.extensions.push(apiExtension);
+ // Bridge loss-hardening wiring: resolve the defer-guard kill-switch
+ // and construct the content-free loss ring once at boot. Reading the
+ // committed project config fails OPEN to the schema defaults, so a corrupt
+ // config can never silently disable the loss-prevention guard. A change to
+ // either knob takes effect on the next restart — acceptable for a
+ // support-visible field escape and a diagnostics ring.
+ const bridgeGuardConfig = readConfigSafely({
+ absPath: resolveConfigPath('project', projectDir),
+ sideline: false,
+ warn: (message) =>
+ log.warn({ message }, '[config] could not read project config for bridge guards'),
+ });
+ const deferGuardEnabled = bridgeGuardConfig.value.bridge.deferGuard.enabled;
+ const fixedPointBackstopEnabled = bridgeGuardConfig.value.bridge.fixedPoint.enabled;
+ const preDrainEnabled = bridgeGuardConfig.value.bridge.preDrain.enabled;
+ lossRing = bridgeGuardConfig.value.lossCapture.enabled
+ ? new LossCaptureRing({
+ projectDir,
+ maxBytes: bridgeGuardConfig.value.lossCapture.maxBytes,
+ })
+ : undefined;
+
+ // The Observer-B derive-loss detector for the paired agent-undo path.
+ // Built here (after the loss ring) and attached to the session manager
+ // constructed earlier in init — no session exists yet, so every real
+ // session picks it up. Disabled → no reporter, and the undo derive stays
+ // serialize-free.
+ if (bridgeGuardConfig.value.bridge.lossDetector.enabled) {
+ bridgeLossReporter = createBridgeDeriveLossReporter({
+ shadow: () => shadowRef.current,
+ ring: lossRing,
+ getBranch: () => headWatcher?.getLastKnownBranch() ?? 'main',
+ contentRoot: contentRoot ?? '',
+ });
+ sessionManager.attachBridgeLossReporter(bridgeLossReporter);
+ }
+
hocuspocus.configuration.extensions.push(
createServerObserverExtension({
mdManager,
@@ -1885,6 +1940,11 @@ export function createServer(options: ServerOptions): ServerInstance {
getCurrentBranch: () => headWatcher?.getLastKnownBranch() ?? null,
resolveEmbed,
resolveSize,
+ deferGuardEnabled,
+ lossDetectorEnabled: bridgeGuardConfig.value.bridge.lossDetector.enabled,
+ fixedPointBackstopEnabled,
+ preDrainEnabled,
+ lossRing,
}),
);
@@ -1986,7 +2046,15 @@ export function createServer(options: ServerOptions): ServerInstance {
/** Apply markdown content to Y.Doc — delegates to the shared throwing helper. */
const applyToDoc = (docName: string, content: string): void =>
- applyExternalChange(durabilityState, hocuspocus, docName, content, resolveEmbed, resolveSize);
+ applyExternalChange(
+ durabilityState,
+ hocuspocus,
+ docName,
+ content,
+ resolveEmbed,
+ resolveSize,
+ bridgeLossReporter,
+ );
/**
* Clear the conflict status set by `case 'conflict'` once a subsequent
diff --git a/packages/server/src/server-observer-extension.ts b/packages/server/src/server-observer-extension.ts
index 0fbe064af..ae3264b63 100644
--- a/packages/server/src/server-observer-extension.ts
+++ b/packages/server/src/server-observer-extension.ts
@@ -14,6 +14,7 @@ import type { Schema } from '@tiptap/pm/model';
import type * as Y from 'yjs';
import { isConfigDoc, isMermaidDoc, isSystemDoc } from './cc1-broadcast.ts';
import { getLogger } from './logger.ts';
+import type { LossCaptureRing } from './loss-capture.ts';
import { incrementServerObserverError } from './metrics.ts';
import { setupServerObservers } from './server-observers.ts';
import type { ShadowRef } from './shadow-repo.ts';
@@ -52,6 +53,38 @@ export interface ServerObserverExtensionOptions {
* `WikiEmbedFile.translateProps` then renders without a size span.
*/
resolveSize?: (basename: string, sourcePath: string) => number | null;
+ /**
+ * Derive-timing defer guard kill-switch, resolved from `.ok/config.yml`
+ * (`bridge.deferGuard.enabled`, default ON). Threaded per-document into
+ * `setupServerObservers`.
+ */
+ deferGuardEnabled?: boolean;
+ /**
+ * Bridge content-loss detector kill-switch, resolved from `.ok/config.yml`
+ * (`bridge.lossDetector.enabled`, default ON). Threaded per-document into
+ * `setupServerObservers` for the Observer-A apply post-condition.
+ */
+ lossDetectorEnabled?: boolean;
+ /**
+ * Re-derive-loop fixed-point backstop kill-switch, resolved from
+ * `.ok/config.yml` (`bridge.fixedPoint.enabled`, default ON). Threaded
+ * per-document into `setupServerObservers`.
+ */
+ fixedPointBackstopEnabled?: boolean;
+ /**
+ * Pre-drain discriminator kill-switch, resolved from `.ok/config.yml`
+ * (`bridge.preDrain.enabled`, default ON). Threaded per-document into
+ * `setupServerObservers`; the doc's pre-drain controller stays registered
+ * either way, but flushes only when enabled.
+ */
+ preDrainEnabled?: boolean;
+ /**
+ * Content-free loss-capture ring, constructed once at boot (gated on
+ * `lossCapture.enabled`). Each derive-timing defer records a `guard-defer`
+ * event, each detector trip a `detector-trip` event, and each backstop trip a
+ * `backstop-trip` event through it. Omit when no ring is wired (unit harness).
+ */
+ lossRing?: LossCaptureRing;
}
/**
@@ -93,6 +126,11 @@ export function createServerObserverExtension(opts: ServerObserverExtensionOptio
contentRoot: opts.contentRoot,
resolveEmbed: opts.resolveEmbed,
resolveSize: opts.resolveSize,
+ deferGuardEnabled: opts.deferGuardEnabled,
+ lossDetectorEnabled: opts.lossDetectorEnabled,
+ fixedPointBackstopEnabled: opts.fixedPointBackstopEnabled,
+ preDrainEnabled: opts.preDrainEnabled,
+ lossRing: opts.lossRing,
});
cleanups.set(documentName, unsubscribe);
return true;
diff --git a/packages/server/src/server-observers.ts b/packages/server/src/server-observers.ts
index 10001217b..c9edcd892 100644
--- a/packages/server/src/server-observers.ts
+++ b/packages/server/src/server-observers.ts
@@ -35,10 +35,13 @@ import {
BridgeMergeContentLossError,
comparePmStructural,
DUPLICATION_GATE_MIN_LINE_LENGTH,
+ fnv1aDigest,
+ fragmentHoldsPendingContent,
isParseEquivalentBridge,
mergeThreeWay,
normalizeBridge,
overMultipliedBodyLines,
+ pendingContentLines,
prependFrontmatter,
projectMergeBoundarySpace,
reattachLeadingDocBoundary,
@@ -50,6 +53,7 @@ import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-ti
// Value import (not `import type`): `carrierKind` uses `instanceof Y.XmlElement`
// to read a top-level child's node shape for the duplication gate.
import * as Y from 'yjs';
+import { detectApplyArmDrop } from './bridge-loss-detector.ts';
import { attachQuiescenceTracker } from './bridge-quiescence.ts';
import {
assertBridgeInvariant,
@@ -61,14 +65,24 @@ import {
import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';
import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
import { getLogger } from './logger.ts';
+import {
+ LOSS_EVENT_BACKSTOP_TRIP,
+ LOSS_EVENT_CHECKPOINT_WRITE,
+ LOSS_EVENT_DETECTOR_TRIP,
+ LOSS_EVENT_GUARD_DEFER,
+ type LossCaptureRing,
+} from './loss-capture.ts';
import { computeMapDrivenBodySplice } from './map-driven-splice.ts';
import {
incrementBridgeMergeCheckpointCreated,
incrementBridgeMergeContentGrowth,
incrementBridgeMergeContentLoss,
incrementBridgeSplitBrainRederives,
+ incrementDeriveTimingDeferForceResolved,
incrementMapDrivenSpliceApplied,
incrementMapDrivenSpliceFallback,
+ incrementObserverAApplyLoss,
+ incrementObserverAApplyLossCheckpointCreated,
incrementObserverADuplicationCheckpointCreated,
incrementObserverADuplicationRederives,
incrementObserverAPathBFires,
@@ -76,9 +90,16 @@ import {
incrementProducerGuardCheckpointCreated,
incrementProducerGuardFires,
incrementProducerGuardFiresSuppressed,
+ incrementReDeriveBackstopTripped,
incrementServerObserverError,
incrementServerObserverFire,
} from './metrics.ts';
+import {
+ type PreDrainController,
+ type PreDrainOpInput,
+ type PreDrainVerdict,
+ planPreDrain,
+} from './pre-drain-discriminator.ts';
import { registerBridgeDirtyProbe } from './server-workload-telemetry.ts';
import { type ShadowHandle, saveInMemoryCheckpoint } from './shadow-repo.ts';
import { setActiveSpanAttributes, withSpanSync } from './telemetry.ts';
@@ -233,6 +254,28 @@ export class ProducerGuardViolationError extends Error {
*/
const PRODUCER_GUARD_DANGER_TYPES = new Set(['jsxComponent', 'table', 'tableCell', 'tableHeader']);
+/**
+ * Consecutive derive-timing defers a document may accumulate before the guard
+ * stops deferring and force-resolves the re-derive loudly. Drain-count based, so
+ * it stays honest under the no-wall-clock rule (precedent #13(b)): the bound is
+ * "how many re-derive drains have been withheld," never elapsed time. Same value
+ * as the persistence layer's `QUIESCENCE_MAX_DEFER` — under sustained typing a
+ * doc that keeps a keystroke un-propagated is the same shape both layers bound.
+ */
+const MAX_DERIVE_TIMING_DEFERS = 8;
+
+/**
+ * Backstop cap for the Y.Text→XmlFragment re-derive loop (the loud
+ * tripwire). A run of this many consecutive re-derive drains that never reaches
+ * a raw-byte fixed point (the two representations keep diverging) freezes the
+ * B-direction re-derive loop. Drain-count based (never wall-clock,
+ * precedent #13(b)). Set well above the worst measured legitimate run — a single
+ * byte-emitting round per settlement episode — so a legitimate flow can never
+ * trip it; the residual it guards is the un-probed echo/normalize-UNEQUAL
+ * corrective-loop domain, where a trip is a true positive.
+ */
+const MAX_REDERIVE_ROUNDS = 8;
+
function fragmentContainsDangerSpace(node: PmStructuralNode): boolean {
if (node.type && PRODUCER_GUARD_DANGER_TYPES.has(node.type)) return true;
if (node.content) {
@@ -336,6 +379,51 @@ function applyMapDrivenSplice(ytext: Y.Text, splice: YTextMapDrivenSplice): void
if (splice.newSlice.length > 0) ytext.insert(splice.spliceStart, splice.newSlice);
}
+/**
+ * Per-document pre-drain controllers, keyed by the live Y.Doc so a paired
+ * write's caller (agent-undo in `agent-sessions.ts`, agent-write handlers) can
+ * reach the doc's observer-owned controller without threading a registry
+ * through the boot wiring. Keyed by doc object identity: two servers in one
+ * process hold distinct Y.Docs, so entries never collide. Set when the observer
+ * attaches, deleted on detach.
+ */
+const preDrainControllers = new WeakMap<Y.Doc, PreDrainController>();
+
+/**
+ * The pre-drain controller for a document, or undefined when observers aren't
+ * attached (system/config/mermaid docs, unloaded docs). A caller with no
+ * controller simply skips pre-drain — the paired write's checkpoint floor still
+ * captures any un-propagated content.
+ */
+export function getPreDrainController(doc: Y.Doc): PreDrainController | undefined {
+ return preDrainControllers.get(doc);
+}
+
+/**
+ * Per-document publisher for the last-converged fragment serialization — the
+ * witness leg of `fragmentHoldsPendingContent`. Stored as a GETTER, never as a
+ * captured string: the witness advances on every settlement, so a value read at
+ * attach time would freeze at the doc's first convergence and make every later
+ * consumer wrong in the unsafe direction. Same lifecycle as
+ * `preDrainControllers` — set on attach, deleted on detach, keyed by doc object
+ * identity.
+ */
+const convergedFragmentWitnesses = new WeakMap<Y.Doc, () => string>();
+
+/**
+ * The last-converged fragment serialization for a document, or `undefined` when
+ * observers aren't attached (system/config docs, unloaded docs, unit rigs).
+ *
+ * This is a witness VALUE, not a "currently deferring" flag — the distinction
+ * the prior-art survey in `reports/tolerated-divergence-hygiene-layers/REPORT.md`
+ * identifies as what keeps a consumer conservative rather than blind when the
+ * datum lags. A consumer with no witness cannot evaluate the derive-timing
+ * tolerance at all and must fall back to its own un-toleranced behavior.
+ */
+export function getConvergedFragmentWitness(doc: Y.Doc): string | undefined {
+ return convergedFragmentWitnesses.get(doc)?.();
+}
+
// Bridge utilities (applyIncrementalDiff, applyFastDiff, mergeThreeWay,
// diffLinesFast, getFrontmatter, normalizeBridge) are imported from
// `@inkeep/open-knowledge-core` so they live in one place shared with the
@@ -446,6 +534,71 @@ export interface SetupServerObserversOpts {
* re-projection.
*/
mergeThreeWay?: typeof mergeThreeWay;
+ /**
+ * Derive-timing defer guard. When a drain-shaped Observer B re-derive would
+ * stomp un-propagated WYSIWYG content the fragment holds but Y.Text lacks, the
+ * guard defers the re-derive so the keystroke survives. Default ON; pass
+ * `false` to make the guard inert (the stomp reproduces) — the config
+ * kill-switch resolves to this at boot.
+ */
+ deferGuardEnabled?: boolean;
+ /**
+ * Bridge content-loss detector. When enabled, the Observer-A apply arms
+ * (map-driven splice + incremental diff) run a content-preservation
+ * post-condition: content the fragment held that the applied Y.Text dropped
+ * (beyond normalization tolerance) writes a recovery checkpoint + a
+ * content-free `detector-trip` event. Detection only — never blocks the
+ * write. Default ON; the config kill-switch resolves to this at boot.
+ */
+ lossDetectorEnabled?: boolean;
+ /**
+ * Re-derive-loop fixed-point backstop. When enabled, the Y.Text→XmlFragment
+ * re-derive cycle terminates on a raw-byte fixed point; a run of re-derive
+ * drains that never reaches one hits a drain-count backstop, freezing the
+ * B-direction re-derive loop LOUDLY (checkpoint + `backstop-trip` ring event).
+ * Default ON; the config kill-switch resolves to this at boot. Pass `false`
+ * to make the backstop inert (a runaway loop churns unbounded).
+ */
+ fixedPointBackstopEnabled?: boolean;
+ /**
+ * Pre-drain discriminator kill-switch. When enabled (default), a paired
+ * write's caller can flush a discriminator-proven non-overlapping pending
+ * keystroke into Y.Text before its paired transact so the keystroke survives
+ * rather than needing the checkpoint floor. The config kill-switch resolves to
+ * this at boot; pass `false` to make `preDrain` inert (the pending content is
+ * left for the paired write's checkpoint floor to capture instead).
+ */
+ preDrainEnabled?: boolean;
+ /**
+ * Loss-capture ring for content-free observability. When present, each
+ * derive-timing defer records a distinguishable `guard-defer` event, each
+ * detector trip a `detector-trip` event, and each backstop trip a
+ * `backstop-trip` event. Omit in unit rigs that only assert the drain
+ * behavior. Structural (`record` only) so a suite can pass a capturing fake.
+ */
+ lossRing?: Pick<LossCaptureRing, 'record'>;
+ /**
+ * Test-only seam: invoked at each derive-timing defer with the current
+ * settlement witnesses, so suites can count defers and assert witness
+ * atomicity (a deferring drain must not move either witness) without reaching
+ * into closure state. Omitted in production.
+ */
+ onDeriveTimingDefer?: (snapshot: { canonicalWitness: string; rawWitness: string }) => void;
+ /**
+ * Test-only seam: invoked when the re-derive-loop backstop trips, with the
+ * count of consecutive non-converging drains that preceded the freeze, so a
+ * suite can assert the trip without reaching into closure state. Omitted in
+ * production.
+ */
+ onReDeriveBackstop?: (rounds: number) => void;
+ /**
+ * Test-only seam: invoked inside the Observer-A apply transact after the arm
+ * writes, so a suite can mutate the just-applied Y.Text to model an apply-arm
+ * content drop (which the byte-preserving arms never do organically) and
+ * exercise the apply post-condition on the production drain. Omitted in
+ * production.
+ */
+ __testApplyLossInjector?: (ytext: Y.Text) => void;
}
/**
@@ -456,8 +609,16 @@ export interface SetupServerObserversOpts {
* in-sync case. Single-sourced so both Observer A detection sites (identity
* gate + post-merge baseline check) apply the identical predicate.
*/
-function settlesSplitBrain(settledText: string, md: string, normMdPre?: string): boolean {
- return settledText !== md && normalizeBridge(settledText) !== (normMdPre ?? normalizeBridge(md));
+function settlesSplitBrain(
+ settledText: string,
+ md: string,
+ normMdPre?: string,
+ normSettledPre?: string,
+): boolean {
+ return (
+ settledText !== md &&
+ (normSettledPre ?? normalizeBridge(settledText)) !== (normMdPre ?? normalizeBridge(md))
+ );
}
/** Node-shape discriminant for a top-level fragment child. */
@@ -706,6 +867,11 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
* attrs only: doc.name + enum site.
*/
const recordSplitBrainRederive = (site: BridgeSplitBrainSite): void => {
+ // Every split-brain re-derive site is corrective reconciliation work that
+ // did NOT converge — the fragment does not derive from Y.Text and a
+ // same-drain Observer B re-derive is enqueued. Mark the drain so the
+ // backstop can count it toward the re-derive-loop bound.
+ drainDidCorrectiveWork = true;
// No-throw is structural, not incidental: every call site runs inside
// runObserverASyncImpl's try, after the state-critical witness writes and
// the `textDirty = true` B-enqueue. A throw escaping here would route
@@ -728,6 +894,26 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
}
};
+ /**
+ * Record a derive-timing defer to the loss ring — content-free (a byte
+ * length, never the bytes). Fire-and-forget: the ring's own `record` logs and
+ * swallows any write failure, so a diagnostics hiccup can never feed back into
+ * the observer write spine. No per-drain console log: a sustained defer burst
+ * would otherwise spam stdout, so the bounded, rotating ring is the sink.
+ */
+ const recordGuardDefer = (pendingLines: readonly string[]): void => {
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_GUARD_DEFER,
+ docName: opts.docName ?? '',
+ writerId: null,
+ direction: 'b',
+ // The ring's `lostLen` is the AT-RISK content's byte length, not the
+ // document's. The whole-document length would read as a multi-KB loss on
+ // every one-character defer.
+ lostLen: pendingLines.reduce((n, line) => n + line.length, 0),
+ });
+ };
+
/**
* Silent recovery-anchor checkpoint for a duplication-gate recovery. Mirrors
* the producer-guard checkpoint shape: fire-and-forget, bounded-cardinality
@@ -774,6 +960,293 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
});
};
+ /**
+ * Content-preservation post-condition for the byte-preserving Observer-A
+ * apply arms (map-driven splice + incremental diff). The mergeThreeWay arm
+ * carries its own `assertContentPreservation`, so it is excluded at the call
+ * site. Detection only: the drain still persists the applied bytes; on a
+ * genuine drop the pre-loss fragment state (`intendedMd`) is checkpointed so
+ * it stays restorable, and a content-free `detector-trip` ring event fires.
+ *
+ * `normIntended` is the already-computed `normalizeBridge(md)` — the
+ * comparison runs in normalized space so a raw-vs-canonical form difference a
+ * byte-preserving splice legitimately leaves in Y.Text (`__foo__` vs
+ * `**foo**`) is never read as a loss. A byte-identical apply and a
+ * normalize-equal apply both short-circuit before the (rare) segment diff.
+ */
+ const detectObserverAApplyLoss = (
+ intendedMd: string,
+ normIntended: string,
+ appliedYText: string,
+ normApplied: string,
+ ): void => {
+ if (opts.lossDetectorEnabled === false) return;
+ const dropped = detectApplyArmDrop(intendedMd, normIntended, appliedYText, normApplied);
+ if (dropped.length === 0) return;
+ // Event counter first, synchronously: a trip with no shadow wired — or one
+ // whose checkpoint write later fails — must still be visible on
+ // /api/metrics/reconciliation. `observerAApplyLoss` minus its
+ // `...CheckpointCreated` sibling is exactly the anchor-loss count.
+ incrementObserverAApplyLoss();
+ const lostLen = dropped.reduce((n, s) => n + s.length, 0);
+ const digest = fnv1aDigest(dropped.join('\n'));
+ const shadow = opts.shadow?.();
+ if (!shadow || !opts.docName) {
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_DETECTOR_TRIP,
+ docName: opts.docName ?? '',
+ writerId: null,
+ direction: 'a',
+ site: 'observer-a-apply',
+ lostLen,
+ digest,
+ });
+ return;
+ }
+ const branch = opts.getBranch?.() ?? 'main';
+ const contentRoot = opts.contentRoot ?? '';
+ const docName = opts.docName;
+ queueMicrotask(() => {
+ saveInMemoryCheckpoint(shadow, contentRoot, {
+ kind: 'observer-a-apply-loss',
+ docName,
+ contents: intendedMd,
+ label: `Before Observer-A apply content-loss @ ${new Date().toISOString()}`,
+ branch,
+ metadata: { lostSubstrings: dropped },
+ })
+ .then((sha) => {
+ incrementObserverAApplyLossCheckpointCreated();
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_DETECTOR_TRIP,
+ docName,
+ writerId: null,
+ direction: 'a',
+ site: 'observer-a-apply',
+ lostLen,
+ digest,
+ checkpointSha: sha,
+ });
+ console.warn(
+ JSON.stringify({
+ event: 'observer-a-apply-loss-checkpoint-created',
+ docName,
+ sha,
+ kind: 'observer-a-apply-loss',
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ })
+ .catch((checkpointErr: unknown) => {
+ const e =
+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
+ log.warn({ docName, err: e }, '[Server Observer A] Apply-loss checkpoint write failed');
+ checkpointLog.warn(
+ { err: e, 'doc.name': docName, branch, kind: 'observer-a-apply-loss' },
+ 'checkpoint write failed',
+ );
+ // The checkpoint failed, but the detector still tripped — emit the
+ // sha-less ring event (mirroring the no-shadow branch) so the fire is
+ // represented in the ring even without a restore anchor. `record()`
+ // never throws or rejects synchronously, so it can't mask the error.
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_DETECTOR_TRIP,
+ docName,
+ writerId: null,
+ direction: 'a',
+ site: 'observer-a-apply',
+ lostLen,
+ digest,
+ });
+ });
+ });
+ };
+
+ /**
+ * Loud force-resolve when the derive-timing defer bound is exhausted. The
+ * re-derive is about to proceed and drop the un-propagated content from the
+ * live fragment, so `preResolveFragmentMd` (which still holds it) is
+ * checkpointed as a restore anchor and a distinguishable ring event carries
+ * that checkpoint's sha — never a silent clamp. Fire-and-forget: the
+ * sha-bearing ring event is written from inside the checkpoint's `then`, and
+ * on a checkpoint-write failure a sha-less ring event fires from the `catch`
+ * instead, so the fire is always represented in the ring; the metrics counter
+ * increments synchronously (the guard force-resolved regardless of whether the
+ * shadow write later succeeds). When
+ * no shadow/docName is wired (unit rigs exercising only the bridge mechanics)
+ * the checkpoint is skipped but the ring event + counter still fire.
+ */
+ const forceResolveExhaustedDefer = (
+ preResolveFragmentMd: string,
+ deferCount: number,
+ /** The at-risk lines the force-resolve is about to drop from the fragment. */
+ pendingLines: readonly string[],
+ ): void => {
+ incrementDeriveTimingDeferForceResolved();
+ // At-risk bytes, not document bytes — see `recordGuardDefer`.
+ const lostLen = pendingLines.reduce((n, line) => n + line.length, 0);
+ const shadow = opts.shadow?.();
+ const docName = opts.docName;
+ if (!shadow || !docName) {
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName: docName ?? '',
+ writerId: null,
+ direction: 'b',
+ site: 'derive-timing-exhaustion',
+ lostLen,
+ });
+ return;
+ }
+ const branch = opts.getBranch?.() ?? 'main';
+ const contentRoot = opts.contentRoot ?? '';
+ queueMicrotask(() => {
+ saveInMemoryCheckpoint(shadow, contentRoot, {
+ kind: 'defer-exhaustion-loss',
+ docName,
+ contents: preResolveFragmentMd,
+ label: `Before derive-defer force-resolve @ ${new Date().toISOString()}`,
+ branch,
+ metadata: { deferCount },
+ })
+ .then((sha) => {
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName,
+ writerId: null,
+ direction: 'b',
+ site: 'derive-timing-exhaustion',
+ lostLen,
+ checkpointSha: sha,
+ });
+ console.warn(
+ JSON.stringify({
+ event: 'derive-defer-exhaustion-checkpoint-created',
+ docName,
+ sha,
+ kind: 'defer-exhaustion-loss',
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ })
+ .catch((checkpointErr: unknown) => {
+ const e =
+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
+ log.warn(
+ { docName, err: e },
+ '[Server Observer B] Derive-defer exhaustion checkpoint write failed',
+ );
+ checkpointLog.warn(
+ { err: e, 'doc.name': docName, branch, kind: 'defer-exhaustion-loss' },
+ 'checkpoint write failed',
+ );
+ // The checkpoint failed, but the force-resolve still fired — emit the
+ // sha-less ring event (mirroring the no-shadow branch) so the fire is
+ // represented in the ring even without a restore anchor.
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_CHECKPOINT_WRITE,
+ docName,
+ writerId: null,
+ direction: 'b',
+ site: 'derive-timing-exhaustion',
+ lostLen,
+ });
+ });
+ });
+ };
+
+ /**
+ * Loud trip of the re-derive-loop backstop. The B-direction re-derive is
+ * frozen (`bDirectionFrozen`) to stop a run of drains that never reach a
+ * raw-byte fixed point. The current Y.Text — the authoritative bytes at freeze
+ * time — is checkpointed so that state stays restorable through the timeline
+ * floor, and a distinguishable `backstop-trip` ring event carries the
+ * checkpoint's sha. The A-direction (user edits) and persistence stay live;
+ * the freeze exits when a later drain reaches a raw-byte fixed point. Never a
+ * silent truncate-and-continue. Fire-and-forget: the metrics counter and the
+ * test seam fire synchronously; the sha-bearing ring event rides the
+ * checkpoint's `then`, and a sha-less one rides the `catch` on a
+ * checkpoint-write failure so the freeze is always represented in the ring.
+ * When no shadow/docName is wired (unit rigs) the checkpoint is skipped but
+ * the ring event + counter still fire.
+ */
+ const tripReDeriveBackstop = (rounds: number): void => {
+ bDirectionFrozen = true;
+ incrementReDeriveBackstopTripped();
+ opts.onReDeriveBackstop?.(rounds);
+ const frozenYText = ytext.toString();
+ const shadow = opts.shadow?.();
+ const docName = opts.docName;
+ // No `lostLen`: the freeze loses nothing. Y.Text stays authoritative and
+ // live, the checkpoint anchors it, and only the B-direction re-derive stops.
+ // Reporting the frozen document's length here would read as a whole-document
+ // loss in the ring.
+ if (!shadow || !docName) {
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_BACKSTOP_TRIP,
+ docName: docName ?? '',
+ writerId: null,
+ direction: 'b',
+ site: 'rederive-backstop',
+ });
+ return;
+ }
+ const branch = opts.getBranch?.() ?? 'main';
+ const contentRoot = opts.contentRoot ?? '';
+ queueMicrotask(() => {
+ saveInMemoryCheckpoint(shadow, contentRoot, {
+ kind: 'bridge-backstop-trip',
+ docName,
+ contents: frozenYText,
+ label: `Before re-derive backstop freeze @ ${new Date().toISOString()}`,
+ branch,
+ metadata: { rounds },
+ })
+ .then((sha) => {
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_BACKSTOP_TRIP,
+ docName,
+ writerId: null,
+ direction: 'b',
+ site: 'rederive-backstop',
+ checkpointSha: sha,
+ });
+ console.warn(
+ JSON.stringify({
+ event: 'bridge-rederive-backstop-checkpoint-created',
+ docName,
+ sha,
+ kind: 'bridge-backstop-trip',
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ })
+ .catch((checkpointErr: unknown) => {
+ const e =
+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
+ log.warn(
+ { docName, err: e },
+ '[Server Observer B] Re-derive backstop checkpoint write failed',
+ );
+ checkpointLog.warn(
+ { err: e, 'doc.name': docName, branch, kind: 'bridge-backstop-trip' },
+ 'checkpoint write failed',
+ );
+ // The checkpoint failed, but the backstop still tripped and froze the
+ // B-direction re-derive — emit the sha-less ring event (mirroring the
+ // no-shadow branch) so the freeze is visible in the ring even without
+ // a restore anchor. Without it the freeze reads like "ring disabled".
+ void opts.lossRing?.record({
+ event: LOSS_EVENT_BACKSTOP_TRIP,
+ docName,
+ writerId: null,
+ direction: 'b',
+ site: 'rederive-backstop',
+ });
+ });
+ });
+ };
+
// ─── Observer A: XmlFragment → Y.Text ─────────────────────
// Two witnesses, one lifecycle. A single baseline variable here previously
// conflated two incompatible surface contracts: gate 1 needs the canonical
@@ -806,6 +1279,71 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// cannot certify that de-anchoring the emission is safe.
let lastExternalYtextChangeMs = 0;
+ // Derive-timing defer guard state. `lastConvergedFragmentMd` is the
+ // freshness-derived serialization of the fragment at the last point where the
+ // fragment and Y.Text were known to agree — the witness the intra-line
+ // predicate compares against, so a freshness respell that is stable across
+ // re-derives (present in both the current serialization and this witness)
+ // cannot read as pending content, while genuine un-propagated children can.
+ // It is deliberately NOT refreshed on a freshness-suppressed Observer A
+ // settlement: that is exactly the drain that leaves the fragment ahead of its
+ // stamped sourceRaw, so refreshing here would blind the guard to the pending
+ // keystroke the whole mechanism exists to preserve.
+ const deferGuardEnabled = opts.deferGuardEnabled !== false;
+ let lastConvergedFragmentMd = '';
+ // Cheap gate: the O(N) fresh-serialize the predicate needs runs only when the
+ // fragment has moved since the last convergence. A source-only edit never
+ // trips this, so the guard adds nothing to the common Observer-B re-derive.
+ let fragmentMutatedSinceConverge = false;
+ // Unbroken run of derive-timing defers. Reset to 0 at every convergence (a
+ // real settlement propagated the pending content or the two representations
+ // agreed); climbs only while the same keystroke stays un-propagated across
+ // successive re-derive drains. Reaching `MAX_DERIVE_TIMING_DEFERS` trips the
+ // loud force-resolve.
+ let consecutiveDeriveTimingDefers = 0;
+ // One-shot: the duplication gate confirmed a race-duplicated span (provenance
+ // walk) and enqueued a same-drain Observer B re-derive to rebuild the
+ // single-copy fragment from Y.Text truth. That re-derive must NOT be deferred:
+ // the doubled fragment holds a line more times than Y.Text, which looks like
+ // pending content to the defer predicate, but the excess is a CRDT-merge
+ // artifact the gate already adjudicated for discard — not an un-propagated
+ // WYSIWYG keystroke. Set in Observer A, consumed by the very next Observer B
+ // in the same synchronous dispatch (no keystroke can interleave), so deferring
+ // it would strand the doubled fragment permanently.
+ let pendingDuplicationRecovery = false;
+
+ // Re-derive-loop fixed-point backstop. The re-derive cycle terminates
+ // on a RAW-BYTE fixed point: a drain whose settled Y.Text raw-equals the
+ // fragment's canonical serialization. A doc that never reaches one but keeps
+ // advancing to NEW states is making forward progress (a large residual-bearing
+ // edit stream, a slow paste) — not a loop. A doc that never reaches one and
+ // REVISITS a recently-settled state is oscillating: the re-derive keeps
+ // re-emitting bytes it already emitted without converging. `oscillationRun`
+ // counts consecutive corrective drains whose settled Y.Text revisited the
+ // recent ring; a run reaching `MAX_REDERIVE_ROUNDS` freezes the B-direction
+ // re-derive loop LOUDLY (checkpoint + ring event) rather than churning
+ // unbounded. Revisit is compared on RAW-BYTE digests, never `normalizeBridge`
+ // tolerance — an oscillation between two tolerated spellings (byte-different,
+ // normalize-equal) still trips, which a normalize-tolerant check would mask.
+ const fixedPointBackstopEnabled = opts.fixedPointBackstopEnabled !== false;
+ const preDrainEnabled = opts.preDrainEnabled !== false;
+ // Bounded ring of recent non-converged settled-Y.Text digests. Sized to the
+ // trip bound so a cycle of any period up to the bound is a detectable revisit.
+ const REDERIVE_DIGEST_RING = MAX_REDERIVE_ROUNDS;
+ const recentSettledDigests: string[] = [];
+ let oscillationRun = 0;
+ let bDirectionFrozen = false;
+ // Per-drain backstop signals, set by Observer A/B during the drain and read by
+ // the settlement dispatcher for a REAL (non-self-origin) drain only. The
+ // nested `afterAllTransactions` a self-origin observer write triggers reports
+ // 'none' and never touches these, so the outer drain's signals survive the
+ // re-entrant dispatch. `drainDeferred` makes a derive-timing-deferred drain a
+ // non-event (neither increment nor reset), protecting the fixed point from
+ // defer-masking.
+ let drainDidCorrectiveWork = false;
+ let drainReachedRawFixedPoint = false;
+ let drainDeferred = false;
+
/**
* STOP: the Path A/B router strict-compares this witness against
* `ytext.toString()`, and `mergeThreeWay`'s diverged-branch base must be a
@@ -831,6 +1369,15 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
lastSyncedCanonicalMd = canonicalMd;
refreshYTextWitness();
canonicalWitnessCoherent = canonicalMd !== '';
+ // Raw-byte fixed-point signal for the re-derive backstop: the raw witness
+ // was just snapshotted from `ytext.toString()`, so `lastSyncedYTextBytes ===
+ // canonicalMd` means the authoritative Y.Text bytes equal the fragment's
+ // canonical serialization exactly — a true fixed point. A normalize-equal
+ // but byte-different settlement (a resting residual) does NOT set it, so it
+ // never resets an active loop counter (the raw-vs-normalize guard).
+ if (fixedPointBackstopEnabled && canonicalMd !== '' && lastSyncedYTextBytes === canonicalMd) {
+ drainReachedRawFixedPoint = true;
+ }
};
/**
@@ -955,8 +1502,14 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
* runs only after byte + normalize inequality — the drains that would
* otherwise settle split-brain and pay a full Observer B re-derive.
*/
- const settlesSplitBrainChecked = (settledText: string, md: string, normMdPre?: string): boolean =>
- settlesSplitBrain(settledText, md, normMdPre) && !isRestingParseEquivalent(settledText, md);
+ const settlesSplitBrainChecked = (
+ settledText: string,
+ md: string,
+ normMdPre?: string,
+ normSettledPre?: string,
+ ): boolean =>
+ settlesSplitBrain(settledText, md, normMdPre, normSettledPre) &&
+ !isRestingParseEquivalent(settledText, md);
/** Initialize Observer A baseline from current XmlFragment state. */
try {
@@ -980,6 +1533,9 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
} else {
recordDivergedAttachBaselines(canonicalInit);
}
+ // Seed the derive-timing convergence witness with the attach-time fragment
+ // serialization so the first re-derive has a real baseline to compare against.
+ lastConvergedFragmentMd = canonicalInit;
} catch (err) {
incrementServerObserverError('a');
log.warn(
@@ -1225,6 +1781,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
) {
recordDivergedAttachBaselines(md);
textDirty = true;
+ pendingDuplicationRecovery = true;
recordSplitBrainRederive('duplication-guard');
incrementObserverADuplicationRederives();
saveDuplicationCheckpoint(md, overMultiplied.length);
@@ -1232,6 +1789,19 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
return;
}
+ // Derive-timing convergence witness: on a freshness-safe drain `md`
+ // IS the fresh serialization of the current fragment (freshness derived,
+ // not the stale sourceRaw), and Observer A is handling that content, so
+ // this is the fragment's last-known real state. Capturing it here — and
+ // NOT on a freshness-suppressed drain — is what lets the defer predicate
+ // tell a pending keystroke (children beyond this witness) from a stable
+ // freshness respell (present in both current serialize and this witness).
+ if (freshnessSafe) {
+ lastConvergedFragmentMd = md;
+ fragmentMutatedSinceConverge = false;
+ consecutiveDeriveTimingDefers = 0;
+ }
+
// Gate 1 (fragment-unchanged): the fragment's canonical serialization is
// identical to the recorded canonical witness. Two concerns split here.
//
@@ -1476,6 +2046,13 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
pathBState.mergedText = asComputed;
}
}
+ // Test-only apply-loss injector. The byte-preserving apply arms cannot
+ // drop content organically (only a future apply bug would), so this
+ // seam lets a suite mutate the just-written Y.Text to model that bug and
+ // exercise the apply post-condition on the production drain. Absent in
+ // production; runs inside the sync transact so the drop is a real
+ // Y.Text mutation the post-condition reads back.
+ opts.__testApplyLossInjector?.(ytext);
}, OBSERVER_SYNC_ORIGIN);
// Splice-path health counter — the fallback side increments inside
@@ -1483,6 +2060,18 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// tracks how often the byte-preserving default actually serves drains.
if (mapDrivenSplice) incrementMapDrivenSpliceApplied();
+ // Content-preservation post-condition for the byte-preserving apply arms
+ // only — the mergeThreeWay branch (Path B + residual merge) carries its
+ // own assertContentPreservation, so re-checking it here would double-count.
+ // The post-apply Y.Text and its normalized form are read ONCE and shared
+ // by the apply post-condition and the settlement check below: both are
+ // O(doc bytes) and both ran on identical inputs, on the per-keystroke path.
+ const appliedYText = ytext.toString();
+ const normApplied = normalizeBridge(appliedYText);
+ if (mapDrivenSplice || (ytextInSync && !residualMergeEligible)) {
+ detectObserverAApplyLoss(md, normMd, appliedYText, normApplied);
+ }
+
// Telemetry: emit one structured event per Path B fire so
// operators can track the slow-path cost. Bounded cardinality —
// attrs are booleans + a numeric byte-delta, no doc content. This
@@ -1563,7 +2152,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// diverged-attach witness shape here would wrongly re-derive every
// residual doc on every WYSIWYG edit (regressing the residual-merge
// steady state); the bytes are already safe either way.
- if (settlesSplitBrainChecked(ytext.toString(), md, normMd)) {
+ if (settlesSplitBrainChecked(appliedYText, md, normMd, normApplied)) {
textDirty = true;
recordSplitBrainRederive('post-merge');
}
@@ -1717,6 +2306,9 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
}
xmlDirty = true;
+ // A non-paired fragment change may carry un-propagated content; arm the
+ // cheap gate so the next Observer B re-derive pays the predicate serialize.
+ fragmentMutatedSinceConverge = true;
};
// ─── Initial sync: populate Y.Text from XmlFragment if empty ──
@@ -1781,17 +2373,114 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
recordFrontmatterEditSurface('source-mode');
priorFmForTelemetry = frontmatter;
}
+ // Raw-byte fixed point: the doc is not merely normalize-equal — the
+ // authoritative Y.Text is byte-identical to the fragment's canonical
+ // serialization. That is the termination signal that resets (and
+ // unfreezes) the re-derive backstop, and it is the SAME comparand
+ // `recordSettledBaselines` uses, deliberately.
+ //
+ // The raw witness is NOT a usable comparand here. When Observer A ran
+ // earlier in this same drain it refreshed that witness from this very
+ // `ytext`, so `lastSyncedYTextBytes === md` would be a tautology: an
+ // A-then-B drain that settled split-brain (or merged to a
+ // residual-bearing state) would declare a fixed point it never reached,
+ // resetting the oscillation run and releasing a live backstop freeze on
+ // a non-converged drain. The canonical witness carries the fragment's
+ // serialization, which A does NOT re-derive from Y.Text, so comparing
+ // against it tests convergence rather than self.
+ if (fixedPointBackstopEnabled && canonicalWitnessCoherent && lastSyncedCanonicalMd === md) {
+ drainReachedRawFixedPoint = true;
+ }
return;
}
+ // Backstop freeze: the re-derive loop hit its drain-count bound. Skip the
+ // re-derive entirely to stop the runaway loop — the B-direction only. The
+ // A-direction (user WYSIWYG edits → Y.Text) and persistence stay live, so
+ // typed content still persists; the freeze exits when a later drain
+ // reaches a raw-byte fixed point (unfrozen by the settlement dispatcher) or
+ // the doc reopens. Placed after the early-exit so a doc that settles while
+ // frozen still unfreezes through it.
+ if (bDirectionFrozen) {
+ setActiveSpanAttributes({ 'observer.b.path': 'backstop-frozen' });
+ return;
+ }
+
+ // Derive-timing defer guard. Before rebuilding the fragment from
+ // Y.Text, check whether the fragment holds un-propagated WYSIWYG content
+ // this re-derive would silently discard. Gated on a fragment mutation
+ // since the last convergence (a source-only re-derive never pays the
+ // serialize) and on the guard being enabled. The predicate is
+ // witness-aware and three-way: a line defers ONLY when the fragment
+ // serialization has it while BOTH Y.Text and the last-converged fragment
+ // lack it — so a stable freshness respell (present in both the current
+ // serialize and the witness) and a Y.Text-only residual (fragment holds
+ // LESS, not more) never defer.
+ if (pendingDuplicationRecovery) {
+ // A confirmed race-duplication recovery enqueued this re-derive; the
+ // doubled fragment's excess is a discard-worthy CRDT artifact, not
+ // pending content. Consume the one-shot and fall through so the fragment
+ // rebuilds single-copy from Y.Text — deferring here would leave it
+ // permanently doubled while Y.Text stays correct.
+ pendingDuplicationRecovery = false;
+ } else if (deferGuardEnabled && fragmentMutatedSinceConverge) {
+ const freshFragmentBody = mdManager.serialize(
+ yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON(),
+ );
+ const freshFragmentMd = prependFrontmatter(frontmatter, freshFragmentBody);
+ if (fragmentHoldsPendingContent(freshFragmentMd, md, lastConvergedFragmentMd)) {
+ if (consecutiveDeriveTimingDefers >= MAX_DERIVE_TIMING_DEFERS) {
+ // Exhaustion. The keystroke has stayed un-propagated across the full
+ // drain-count bound (sustained typing keeps freshness hot so
+ // Observer A never gets a quiet drain to propagate it). Stop
+ // deferring and force-resolve LOUDLY: checkpoint the pre-resolve
+ // fragment serialization so the content stays restorable, emit a
+ // ring event carrying that checkpoint's sha, reset the counter, and
+ // fall through to the re-derive below. Never a silent clamp — the
+ // content leaves the live fragment but the timeline floor keeps it
+ // reachable.
+ forceResolveExhaustedDefer(
+ freshFragmentMd,
+ consecutiveDeriveTimingDefers,
+ pendingContentLines(freshFragmentMd, md, lastConvergedFragmentMd),
+ );
+ consecutiveDeriveTimingDefers = 0;
+ setActiveSpanAttributes({ 'observer.b.path': 'derive-timing-force-resolve' });
+ } else {
+ // Defer: leave the fragment intact so the keystroke survives, re-arm
+ // both observers so the pending content propagates through Observer A
+ // on a subsequent freshness-safe drain and B re-derives cleanly after,
+ // and DO NOT move the witnesses — this is not a settlement.
+ consecutiveDeriveTimingDefers += 1;
+ xmlDirty = true;
+ textDirty = true;
+ recordGuardDefer(pendingContentLines(freshFragmentMd, md, lastConvergedFragmentMd));
+ opts.onDeriveTimingDefer?.({
+ canonicalWitness: lastSyncedCanonicalMd,
+ rawWitness: lastSyncedYTextBytes,
+ });
+ // A deferred drain is a backstop non-event: the fragment holds
+ // un-propagated content by design, so it is neither corrective
+ // convergence work nor a fixed point. Marking it keeps a defer run
+ // from masking (or falsely feeding) the re-derive-loop counter.
+ drainDeferred = true;
+ setActiveSpanAttributes({ 'observer.b.path': 'derive-timing-defer' });
+ return;
+ }
+ }
+ }
+
// Bridge always-live: parseWithFallback never throws — it always
// produces a valid JSONContent tree, falling back to rawMdxFallback
// for unparseable spans. `observerParseOpts` threads `resolveEmbed` +
// `sourcePath` so `![[photo.png]]` mdast nodes resolve to disk paths
// before PM dispatch. Under server-authoritative architecture
- // (precedent #14), this observer is the sole writer for XmlFragment —
- // the "always-live" contract here means no client sees frozen WYSIWYG
- // when another peer is mid-typing a broken MDX tag.
+ // (precedent #14), this observer is the sole SERVER-SIDE writer for
+ // XmlFragment — the client editor still writes its own fragment replica
+ // (y-tiptap's prosemirror binding), reconciled over the wire under
+ // Y.Text-is-truth; "sole writer" is scoped to the server process, not the
+ // whole system. The "always-live" contract here means no client sees
+ // frozen WYSIWYG when another peer is mid-typing a broken MDX tag.
const parsedJson = mdManager.parseWithFallback(body, observerParseOpts);
const pmNode = opts.schema.nodeFromJSON(parsedJson);
@@ -1801,6 +2490,12 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
updateYFragment(doc, xmlFragment, pmNode, meta);
}, OBSERVER_SYNC_ORIGIN);
+ // The re-derive is corrective reconciliation work; whether it reached a
+ // raw-byte fixed point is decided by the post-sync convergence check
+ // below (`recordSettledBaselines` sets `drainReachedRawFixedPoint` when
+ // the settled Y.Text raw-equals the canonical serialization).
+ if (fixedPointBackstopEnabled) drainDidCorrectiveWork = true;
+
if (priorFmForTelemetry !== frontmatter) {
recordFrontmatterEditSurface('source-mode');
priorFmForTelemetry = frontmatter;
@@ -1844,6 +2539,13 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// canonical value there would misroute the next fragment change to
// Path B on any in-tolerance residual doc.
recordSettledBaselines(canonicalYText);
+ // Derive-timing convergence witness: B just rebuilt the fragment
+ // from Y.Text, so `canonicalYText` IS the fresh serialization of the
+ // current fragment and the two representations agree — the last-known
+ // real fragment state the defer predicate compares against.
+ lastConvergedFragmentMd = canonicalYText;
+ fragmentMutatedSinceConverge = false;
+ consecutiveDeriveTimingDefers = 0;
} catch (reserializeErr) {
// Watchdog violations re-throw past every soft-recovery catch up to
// whatever drove the original transaction. In test mode the test
@@ -1986,6 +2688,14 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
return;
}
+ // Reset the per-drain backstop signals for this REAL drain. The two
+ // 'none' returns above (no dirty flags, or self-origin only — the
+ // nested dispatch a self-origin observer write triggers) fall out
+ // before here, so those never clear the signals the outer drain sets.
+ drainDidCorrectiveWork = false;
+ drainReachedRawFixedPoint = false;
+ drainDeferred = false;
+
// Observer A FIRST: when both flags are set — either a single
// non-paired transaction mutated both CRDTs (rare), or A's
// settlement check (`settlesSplitBrain`) enqueued a same-drain B
@@ -2014,6 +2724,34 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
opts.onDispatch?.('b');
runObserverBSync();
}
+
+ // Re-derive-loop backstop bookkeeping for this real drain. A
+ // deferred drain is a non-event. A drain that reached a raw-byte fixed
+ // point resets and unfreezes (and clears the ring — a new episode). A
+ // corrective drain that did NOT converge is an oscillation signal only
+ // when its settled Y.Text REVISITS the recent ring; a genuinely new
+ // state is forward progress and resets the run. A revisit run reaching
+ // the bound freezes the B-direction loop loudly.
+ if (fixedPointBackstopEnabled && !drainDeferred) {
+ if (drainReachedRawFixedPoint) {
+ oscillationRun = 0;
+ recentSettledDigests.length = 0;
+ bDirectionFrozen = false;
+ } else if (drainDidCorrectiveWork) {
+ const digest = fnv1aDigest(ytext.toString());
+ if (recentSettledDigests.includes(digest)) {
+ oscillationRun += 1;
+ if (oscillationRun >= MAX_REDERIVE_ROUNDS && !bDirectionFrozen) {
+ tripReDeriveBackstop(oscillationRun);
+ }
+ } else {
+ oscillationRun = 0;
+ }
+ recentSettledDigests.push(digest);
+ if (recentSettledDigests.length > REDERIVE_DIGEST_RING) recentSettledDigests.shift();
+ }
+ }
+
// Stamp the final dispatch decision on the span. 'a-then-b'
// is reported when both ran in the same drain (rare but
// semantically distinct from sequential 'a' or 'b').
@@ -2038,10 +2776,95 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// and exposes `isDocQuiescent(doc)` for the persistence quiescence gate.
const detachQuiescence = attachQuiescenceTracker(doc);
+ // ─── Pre-drain controller ──────────────────────────────────
+ // Flush a discriminator-proven non-overlapping pending keystroke into Y.Text
+ // BEFORE a paired write's transact so the keystroke survives the paired
+ // derive (rather than needing the checkpoint floor). Lives here because it
+ // owns the fragment/Y.Text/witness state and the cheap pending gate; the
+ // flush write uses `OBSERVER_SYNC_ORIGIN` (the same self-origin Observer A's
+ // Path-A splice uses) so the flushed structs are NOT captured into the
+ // paired op's UndoManager frame.
+ const preDrainController: PreDrainController = {
+ preDrain(op: PreDrainOpInput): PreDrainVerdict {
+ // Kill-switch: leave the content pending so the paired write's checkpoint
+ // floor captures it (behaviorally inert, floor path unchanged).
+ if (!preDrainEnabled) return { preDrain: false, reason: 'skip-disabled' };
+ // Cheap gate: nothing has entered the fragment since the last converged
+ // settlement, so there is no un-propagated content to flush. A clean
+ // paired op pays only this boolean — never the O(N) serialize below.
+ if (!fragmentMutatedSinceConverge) return { preDrain: false, reason: 'skip-no-pending' };
+
+ try {
+ const json = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
+ const fullMd = ytext.toString();
+ const { body } = stripFrontmatter(fullMd);
+ const fmPrefixLen = fullMd.length - body.length;
+
+ // The whole decision — gate, witness check, target extraction,
+ // localizer, already-converged check, overlap classification — lives in
+ // `planPreDrain`. This controller supplies the doc-side state and
+ // EXECUTES the plan; it does not re-derive one, so the corpus bar and
+ // the shipped behaviour cannot drift apart.
+ const { preDrain, verdict, splice } = planPreDrain({
+ pendingDirty: true,
+ body,
+ fragmentPmJson: json,
+ // The splice model is only a faithful model of the drain's rewrite
+ // when Y.Text still equals the raw witness — otherwise the drain takes
+ // a non-splice path whose rewrite differs. Fail closed to the floor.
+ witnessMatched: fullMd === lastSyncedYTextBytes,
+ fmPrefixLen,
+ op:
+ op.kind === 'agent-undo'
+ ? { kind: 'agent-undo', ytext, stackItem: op.stackItem }
+ : { kind: 'agent-write', writeKind: op.writeKind },
+ mdManager,
+ });
+ // `splice` narrows to non-null from `preDrain` alone — the plan's
+ // discriminated union makes the old `|| splice === null` arm dead.
+ if (!preDrain) return verdict;
+
+ // Flush: apply the drain's splice to Y.Text under the observer
+ // self-origin, then record the settlement — post-flush Y.Text equals the
+ // fragment's canonical serialization, a true fixed point, so the
+ // witnesses and the defer/backstop bookkeeping stay coherent for the
+ // paired op that follows and any later drain.
+ const bodyOffset = fullMd.length - body.length;
+ doc.transact(() => {
+ applyMapDrivenSplice(ytext, {
+ spliceStart: bodyOffset + splice.spliceStart,
+ spliceEnd: bodyOffset + splice.spliceEnd,
+ newSlice: splice.newSlice,
+ });
+ }, OBSERVER_SYNC_ORIGIN);
+ const canonicalMd = prependFrontmatter(readCurrentFm(), mdManager.serialize(json));
+ recordSettledBaselines(canonicalMd);
+ lastConvergedFragmentMd = canonicalMd;
+ fragmentMutatedSinceConverge = false;
+ consecutiveDeriveTimingDefers = 0;
+ return verdict;
+ } catch (err) {
+ // A pre-drain is a best-effort survival optimization: a serialize/parse
+ // throw on malformed fragment content must never break the paired op —
+ // fall closed to the checkpoint floor.
+ incrementServerObserverError('a');
+ log.warn(
+ { err: err instanceof Error ? err : new Error(String(err)), docName: opts.docName },
+ '[Server pre-drain] Discrimination threw — routing to the checkpoint floor',
+ );
+ return { preDrain: false, reason: 'checkpoint-witness-mismatch' };
+ }
+ },
+ };
+ preDrainControllers.set(doc, preDrainController);
+ convergedFragmentWitnesses.set(doc, () => lastConvergedFragmentMd);
+
// ─── Cleanup ───────────────────────────────────────────────
return () => {
unregisterDirtyProbe();
detachQuiescence();
+ preDrainControllers.delete(doc);
+ convergedFragmentWitnesses.delete(doc);
doc.off('afterAllTransactions', afterAll);
xmlFragment.unobserveDeep(observerA);
ytext.unobserve(observerB);
diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.ts
index a4a2a12fb..45a3d3f54 100644
--- a/packages/server/src/shadow-repo.test.ts
+++ b/packages/server/src/shadow-repo.test.ts
@@ -4,6 +4,8 @@ import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import {
+ CHECKPOINT_KINDS,
+ type CheckpointKind,
formatCheckpointBodyLine,
parseCheckpoint,
parseOkActor,
@@ -983,9 +985,13 @@ describe('saveInMemoryCheckpoint (bridge-correctness SPEC §6 R7a)', () => {
});
test('round-trips a bridge-merge-loss checkpoint — ref exists, parseCheckpoint recovers metadata', async () => {
+ // Production callers pass the extension-LESS Hocuspocus docName (what flows
+ // through the CRDT layer), so the blob lands at the extension-less tree path
+ // `content/docs/intro` — not `content/docs/intro.md`. The restore floor
+ // resolves that shape.
const params: InMemoryCheckpointParams = {
kind: 'bridge-merge-loss',
- docName: 'intro.md',
+ docName: 'intro',
contents: '# Pre-merge baseline\n',
label: 'Before concurrent merge @ 2026-04-17T08:00:00Z',
branch: 'main',
@@ -1007,14 +1013,15 @@ describe('saveInMemoryCheckpoint (bridge-correctness SPEC §6 R7a)', () => {
if (parsed?.kind !== 'bridge-merge-loss') throw new Error('expected bridge-merge-loss kind');
expect(parsed.metadata.lostSubstrings).toEqual(['user keystroke', 'another lost phrase']);
- // Contents blob is stored at content/docs/intro.md
+ // Contents blob is stored at the extension-less path content/docs/intro
const tree = (await sg.raw('ls-tree', '-r', sha)).trim();
- expect(tree).toContain('content/docs/intro.md');
+ expect(tree).toContain('content/docs/intro');
+ expect(tree).not.toContain('content/docs/intro.md');
// docName + size are inlined in
// the metadata so the rescue read path doesn't need ls-tree per commit.
if (parsed.kind !== 'bridge-merge-loss') throw new Error('narrow');
- expect(parsed.docName).toBe('intro.md');
+ expect(parsed.docName).toBe('intro');
expect(parsed.size).toBe(Buffer.byteLength('# Pre-merge baseline\n', 'utf-8'));
});
@@ -1465,6 +1472,156 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
expect(result.deletedAutoConsolidation).toBe(0);
});
+
+ const seedKind = async (kind: CheckpointKind, tag = ''): Promise<void> => {
+ switch (kind) {
+ case 'bridge-merge-loss':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'a.md',
+ contents: `a${tag}\n`,
+ label: 'l',
+ metadata: { lostSubstrings: ['x'] },
+ });
+ return;
+ case 'producer-guard-loss':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'b.md',
+ contents: `b${tag}\n`,
+ label: 'l',
+ metadata: { construct: 'tableCell' },
+ });
+ return;
+ case 'observer-a-duplication':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'c.md',
+ contents: `c${tag}\n`,
+ label: 'l',
+ metadata: { duplicatedLineCount: 1 },
+ });
+ return;
+ case 'external-change-rescue':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'd.md',
+ contents: `d${tag}\n`,
+ label: 'l',
+ metadata: { incomingDiskSha: 'sha' },
+ });
+ return;
+ case 'defer-exhaustion-loss':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'e.md',
+ contents: `e${tag}\n`,
+ label: 'l',
+ metadata: { deferCount: 8 },
+ });
+ return;
+ case 'observer-a-apply-loss':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'h.md',
+ contents: `h${tag}\n`,
+ label: 'l',
+ metadata: { lostSubstrings: ['dropped'] },
+ });
+ return;
+ case 'bridge-derive-loss':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'f.md',
+ contents: `f${tag}\n`,
+ label: 'l',
+ metadata: { lostSubstrings: ['dropped'] },
+ });
+ return;
+ case 'bridge-backstop-trip':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'g.md',
+ contents: `g${tag}\n`,
+ label: 'l',
+ metadata: { rounds: 8 },
+ });
+ return;
+ case 'persistence-reconcile-loss':
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind,
+ docName: 'i.md',
+ contents: `i${tag}\n`,
+ label: 'l',
+ metadata: { atRiskLines: 1, witnessAvailable: true },
+ });
+ return;
+ case 'auto-consolidation':
+ await writeAutoConsolidationCheckpoint(shadow, tag === '' ? 1 : Number(tag));
+ return;
+ default: {
+ const unseeded: never = kind;
+ throw new Error(`unseeded checkpoint kind: ${unseeded}`);
+ }
+ }
+ };
+
+ test('buckets every registered checkpoint kind without throwing', async () => {
+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');
+
+ for (const kind of CHECKPOINT_KINDS) await seedKind(kind);
+
+ // Generous limits: the assertion is that every kind is scanned and bucketed
+ // without throwing, not that anything is deleted.
+ const result = await gcCheckpointRefs(shadow, 'main', {
+ ...DEFAULT_CHECKPOINT_RETENTION,
+ maxBridgeMergeLoss: 50,
+ maxProducerGuardLoss: 50,
+ maxObserverADuplication: 50,
+ maxExternalChangeRescue: 50,
+ maxDeferExhaustionLoss: 50,
+ maxBridgeDeriveLoss: 50,
+ maxObserverAApplyLoss: 50,
+ maxBridgeBackstopTrip: 50,
+ maxPersistenceReconcileLoss: 50,
+ maxAutoConsolidation: 50,
+ ttlMs: 0,
+ });
+
+ expect(result.scanned).toBe(CHECKPOINT_KINDS.length);
+ expect(result.retained).toBe(CHECKPOINT_KINDS.length);
+ });
+
+ test('every registered kind is actually REAPED at its own limit, not merely bucketed', async () => {
+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');
+
+ // Two checkpoints of every kind, then GC at limit 1. A kind that is scanned
+ // and bucketed but never handed to `planDeletions` retains BOTH and is
+ // 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');
+ }
+
+ // Every `max*` limit set to 1, derived from the policy shape so a new
+ // retention field cannot be silently left at its default here.
+ const limits = Object.fromEntries(
+ Object.entries(DEFAULT_CHECKPOINT_RETENTION).map(([k, v]) =>
+ k.startsWith('max') ? [k, 1] : [k, v],
+ ),
+ ) as typeof DEFAULT_CHECKPOINT_RETENTION;
+
+ const result = await gcCheckpointRefs(shadow, 'main', { ...limits, ttlMs: 0 });
+
+ // One reaped per kind — every bucket drained to its limit of 1.
+ const deleted = Object.entries(result).filter(([k]) => k.startsWith('deleted'));
+ expect(deleted.length).toBe(CHECKPOINT_KINDS.length);
+ for (const [counter, count] of deleted) {
+ expect(`${counter}=${count}`).toBe(`${counter}=1`);
+ }
+ expect(result.retained).toBe(CHECKPOINT_KINDS.length);
+ });
});
describe('sweepLegacyShadowRefs (US-018, D35, NFR-6)', () => {
diff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.ts
index c7aaaa2d7..a7c2f8652 100644
--- a/packages/server/src/shadow-repo.ts
+++ b/packages/server/src/shadow-repo.ts
@@ -29,6 +29,9 @@ import { existsSync, readdirSync, rmSync } from 'node:fs';
import { resolve } from 'node:path';
import {
type AutoConsolidationTrigger,
+ CHECKPOINT_KIND_REGISTRY,
+ CHECKPOINT_KINDS,
+ type CheckpointKind,
formatCheckpointBodyLine,
formatCheckpointSubject,
formatImportSubject,
@@ -818,6 +821,21 @@ export async function safetyCheckpoint(
* branch-switch path) would otherwise have discarded dirty Y.Doc content.
* `contents` is the rescued in-memory markdown; `incomingDiskSha` names
* the disk SHA we chose over it.
+ * - `defer-exhaustion-loss` — the derive-timing defer guard reached its
+ * drain-count bound and force-resolved. `contents` is the pre-resolve
+ * fragment serialization (which still holds the un-propagated keystroke);
+ * `deferCount` is a content-free count of the deferrals that preceded it.
+ * - `observer-a-apply-loss` — the XmlFragment→Y.Text APPLY post-condition found
+ * the byte-preserving apply arms dropped content the fragment's intended
+ * markdown held. Distinct from `bridge-merge-loss` (a Path-B MERGE drop) so
+ * the two detection sites keep separate counters and retention budgets.
+ * `contents` is the pre-loss fragment serialization; `lostSubstrings` names
+ * the dropped content.
+ * - `bridge-derive-loss` — the Y.Text→XmlFragment derive post-condition found
+ * the pre-derive fragment held content the authoritative Y.Text lacked, about
+ * to be discarded by a paired agent-undo derive. `contents` is the pre-derive
+ * fragment serialization (the restore anchor); `lostSubstrings` names the
+ * dropped content for diagnosis.
*/
export type InMemoryCheckpointParams =
| {
@@ -851,11 +869,52 @@ export type InMemoryCheckpointParams =
label: string;
branch?: string;
metadata: { incomingDiskSha: string };
+ }
+ | {
+ kind: 'defer-exhaustion-loss';
+ docName: string;
+ contents: string;
+ label: string;
+ branch?: string;
+ metadata: { deferCount: number };
+ }
+ | {
+ kind: 'observer-a-apply-loss';
+ docName: string;
+ contents: string;
+ label: string;
+ branch?: string;
+ metadata: { lostSubstrings: string[] };
+ }
+ | {
+ kind: 'bridge-derive-loss';
+ docName: string;
+ contents: string;
+ label: string;
+ branch?: string;
+ metadata: { lostSubstrings: string[] };
+ }
+ | {
+ kind: 'persistence-reconcile-loss';
+ docName: string;
+ contents: string;
+ label: string;
+ branch?: string;
+ metadata: { atRiskLines: number; witnessAvailable: boolean };
+ }
+ | {
+ kind: 'bridge-backstop-trip';
+ docName: string;
+ contents: string;
+ label: string;
+ branch?: string;
+ metadata: { rounds: number };
};
/**
- * Silent in-memory checkpoint — writes `contents` as a blob at
- * `<docName>.md` in an isolated git tree, commits with body
+ * Silent in-memory checkpoint — writes `contents` as a blob at the
+ * extension-less tree path `<docName>` (docNames are extension-less by
+ * convention; `foo` → `foo.md` on disk) in an isolated git tree, commits with body
* `checkpoint: ${label}\n\nok-checkpoint-v1: ${JSON}`, and updates the ref
* `refs/checkpoints/<branch>/<sha>`. Never touches `refs/wip/*` — this is a
* one-shot recovery artifact, not part of the per-writer WIP chain
@@ -894,9 +953,16 @@ async function saveInMemoryCheckpointInner(
// Path inside the tree mirrors the real content layout so TimelinePanel's
// existing per-doc view logic (walks the tree at the commit's docName)
// resolves identically for silent-checkpoint artifacts.
- const treePath = contentRoot
- ? `${contentRoot.replace(/\/$/, '')}/${params.docName}`
- : params.docName;
+ //
+ // A '.'-only (or './'-prefixed) contentRoot means the content dir IS the repo
+ // root. `git update-index --cacheinfo` rejects a `./`-prefixed tree path, so
+ // collapse it to a bare docName — mirroring the WIP builders, which treat ''
+ // and '.' as the same root pathspec. Without this a silent checkpoint throws
+ // `Invalid path './<doc>'` and the recovery floor never persists on a booted
+ // server (which passes contentRoot '.').
+ const normalizedRoot =
+ contentRoot === '.' ? '' : contentRoot.replace(/^\.\//, '').replace(/\/$/, '');
+ const treePath = normalizedRoot ? `${normalizedRoot}/${params.docName}` : params.docName;
// Byte-size of the rescued content; encoded in metadata so the rescue
// read path can render the listing without spawning a per-ref `git ls-tree`
// subprocess.
@@ -937,6 +1003,46 @@ async function saveInMemoryCheckpointInner(
metadata: params.metadata,
};
break;
+ case 'defer-exhaustion-loss':
+ parsed = {
+ kind: 'defer-exhaustion-loss',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
+ case 'observer-a-apply-loss':
+ parsed = {
+ kind: 'observer-a-apply-loss',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
+ case 'bridge-derive-loss':
+ parsed = {
+ kind: 'bridge-derive-loss',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
+ case 'bridge-backstop-trip':
+ parsed = {
+ kind: 'bridge-backstop-trip',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
+ case 'persistence-reconcile-loss':
+ parsed = {
+ kind: 'persistence-reconcile-loss',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
}
const bodyLine = formatCheckpointBodyLine(parsed);
const message = `checkpoint: ${params.label}\n\n${bodyLine}`;
@@ -1122,6 +1228,46 @@ export interface CheckpointRetentionPolicy {
* paths. Default 50.
*/
maxExternalChangeRescue: number;
+ /**
+ * Maximum `defer-exhaustion-loss` checkpoints to keep per branch. Written
+ * when the derive-timing defer guard force-resolves at its drain-count bound.
+ * Its own budget so a doc stuck in sustained defer-exhaustion cannot evict
+ * merge-drop or serializer-corruption recovery anchors. Default 50.
+ */
+ maxDeferExhaustionLoss: number;
+ /**
+ * Maximum `bridge-derive-loss` checkpoints to keep per branch. Written when
+ * the Y.Text→XmlFragment derive post-condition detects the pre-derive
+ * fragment held content Y.Text lacked. Its own budget so a doc undergoing
+ * repeated derive-loss cannot evict merge-drop or serializer-corruption
+ * recovery anchors. Default 50.
+ */
+ maxBridgeDeriveLoss: number;
+ /**
+ * Maximum `observer-a-apply-loss` checkpoints to keep per branch. Written when
+ * the Observer-A apply post-condition detects the byte-preserving apply arms
+ * dropped fragment content. Its own budget so a doc undergoing repeated apply
+ * drops cannot evict Path-B merge-drop or serializer-corruption anchors.
+ * Default 50.
+ */
+ maxObserverAApplyLoss: number;
+ /**
+ * Maximum `bridge-backstop-trip` checkpoints to keep per branch. Written when
+ * the Y.Text→XmlFragment re-derive loop hits its drain-count backstop and
+ * freezes. Its own budget so a doc stuck in a runaway re-derive loop cannot
+ * evict merge-drop or serializer-corruption recovery anchors. Default 50.
+ */
+ maxBridgeBackstopTrip: number;
+ /**
+ * Maximum `persistence-reconcile-loss` checkpoints to keep per branch.
+ * Written when the persistence pre-write check finds a divergence outside the
+ * derive-timing guard's protected set and rebuilds the fragment. Its own
+ * budget so a doc resting on a construct that diverges on every write-back
+ * cannot evict merge-drop or serializer-corruption recovery anchors — the
+ * budget is the second line of defense; the mint-side dedup in `persistence.ts`
+ * is the first. Default 50.
+ */
+ maxPersistenceReconcileLoss: number;
/**
* Maximum `auto-consolidation` checkpoints to keep per branch.
* These are service-authored when dead WIP chains are folded; left unbounded
@@ -1148,6 +1294,11 @@ export const DEFAULT_CHECKPOINT_RETENTION: CheckpointRetentionPolicy = {
maxProducerGuardLoss: 50,
maxObserverADuplication: 50,
maxExternalChangeRescue: 50,
+ maxDeferExhaustionLoss: 50,
+ maxBridgeDeriveLoss: 50,
+ maxObserverAApplyLoss: 50,
+ maxBridgeBackstopTrip: 50,
+ maxPersistenceReconcileLoss: 50,
maxAutoConsolidation: 2,
ttlMs: 30 * 24 * 60 * 60 * 1000,
};
@@ -1158,10 +1309,90 @@ export interface CheckpointGcResult {
deletedProducerGuardLoss: number;
deletedObserverADuplication: number;
deletedExternalChangeRescue: number;
+ deletedDeferExhaustionLoss: number;
+ deletedBridgeDeriveLoss: number;
+ deletedObserverAApplyLoss: number;
+ deletedBridgeBackstopTrip: number;
+ deletedPersistenceReconcileLoss: number;
deletedAutoConsolidation: number;
retained: number;
}
+/** The per-bucket deletion counters on {@link CheckpointGcResult}. */
+type GcDeletionCounter = Exclude<keyof CheckpointGcResult, 'scanned' | 'retained'>;
+
+interface GcBucketPolicy {
+ /** The retention limit this bucket draws from. */
+ limit: (policy: CheckpointRetentionPolicy) => number;
+ /** Which `CheckpointGcResult` counter its deletions land on. */
+ counter: GcDeletionCounter;
+ /** Whether the TTL lower bound applies (false = count-only retention). */
+ applyTtl: boolean;
+}
+
+/**
+ * Retention wiring per GC bucket. `satisfies Record<CheckpointKind, …>` is what
+ * makes this exhaustive: a checkpoint kind added to the parser cannot compile
+ * until it declares a limit, a counter, and its TTL applicability here — so a
+ * new kind can never end up scanned-but-never-reaped, accumulating refs forever
+ * with no cap and no TTL.
+ */
+const GC_BUCKET_POLICY = {
+ 'bridge-merge-loss': {
+ limit: (p) => p.maxBridgeMergeLoss,
+ counter: 'deletedBridgeMergeLoss',
+ applyTtl: true,
+ },
+ 'producer-guard-loss': {
+ limit: (p) => p.maxProducerGuardLoss,
+ counter: 'deletedProducerGuardLoss',
+ applyTtl: true,
+ },
+ 'observer-a-duplication': {
+ limit: (p) => p.maxObserverADuplication,
+ counter: 'deletedObserverADuplication',
+ applyTtl: true,
+ },
+ 'external-change-rescue': {
+ limit: (p) => p.maxExternalChangeRescue,
+ counter: 'deletedExternalChangeRescue',
+ applyTtl: true,
+ },
+ 'defer-exhaustion-loss': {
+ limit: (p) => p.maxDeferExhaustionLoss,
+ counter: 'deletedDeferExhaustionLoss',
+ applyTtl: true,
+ },
+ 'observer-a-apply-loss': {
+ limit: (p) => p.maxObserverAApplyLoss,
+ counter: 'deletedObserverAApplyLoss',
+ applyTtl: true,
+ },
+ 'bridge-derive-loss': {
+ limit: (p) => p.maxBridgeDeriveLoss,
+ counter: 'deletedBridgeDeriveLoss',
+ applyTtl: true,
+ },
+ 'bridge-backstop-trip': {
+ limit: (p) => p.maxBridgeBackstopTrip,
+ counter: 'deletedBridgeBackstopTrip',
+ applyTtl: true,
+ },
+ 'persistence-reconcile-loss': {
+ limit: (p) => p.maxPersistenceReconcileLoss,
+ counter: 'deletedPersistenceReconcileLoss',
+ applyTtl: true,
+ },
+ // Count-only: TTL must never be able to reap every surviving
+ // auto-checkpoint, or the chained consolidated history it anchors becomes
+ // unreachable.
+ 'auto-consolidation': {
+ limit: (p) => p.maxAutoConsolidation,
+ counter: 'deletedAutoConsolidation',
+ applyTtl: false,
+ },
+} as const satisfies Record<CheckpointKind, GcBucketPolicy>;
+
/**
* GC `refs/checkpoints/<branch>/*` kind-aware: keep the most-recent N per
* kind (per policy), delete older entries, apply TTL as a lower bound.
@@ -1191,6 +1422,11 @@ async function gcCheckpointRefsInner(
deletedProducerGuardLoss: 0,
deletedObserverADuplication: 0,
deletedExternalChangeRescue: 0,
+ deletedDeferExhaustionLoss: 0,
+ deletedBridgeDeriveLoss: 0,
+ deletedObserverAApplyLoss: 0,
+ deletedBridgeBackstopTrip: 0,
+ deletedPersistenceReconcileLoss: 0,
deletedAutoConsolidation: 0,
retained: 0,
};
@@ -1241,16 +1477,10 @@ async function gcCheckpointRefsInner(
return result;
}
- type TypedKind =
- | 'bridge-merge-loss'
- | 'producer-guard-loss'
- | 'observer-a-duplication'
- | 'external-change-rescue'
- | 'auto-consolidation';
interface Entry {
sha: string;
timestamp: number; // ms since epoch
- kind: TypedKind | null;
+ kind: CheckpointKind | null;
}
const entries: Entry[] = [];
for (const record of logRaw.split('\x1e')) {
@@ -1264,24 +1494,21 @@ async function gcCheckpointRefsInner(
entries.push({ sha, timestamp: Number.isFinite(ts) ? ts : 0, kind });
}
- // Partition by kind. Save-Version (kind=null) entries are always retained.
- // This record MUST list every kind parseCheckpoint can return, or
- // `byKind[e.kind].push` throws on the unmapped kind: adding a new checkpoint
- // kind to the parser without adding it here is the bug this guards against.
- const byKind: Record<TypedKind, Entry[]> = {
- 'bridge-merge-loss': [],
- 'producer-guard-loss': [],
- 'observer-a-duplication': [],
- 'external-change-rescue': [],
- 'auto-consolidation': [],
- };
+ // Partition by GC BUCKET, derived from the shared registry rather than a
+ // hand-kept list — `CHECKPOINT_KINDS` is the enumeration and
+ // `CHECKPOINT_KIND_REGISTRY[kind].gcBucket` is the routing, so a kind added to
+ // the parser lands in a real bucket by construction. Save-Version (kind=null)
+ // entries are always retained.
+ const byBucket = Object.fromEntries(
+ CHECKPOINT_KINDS.map((kind) => [kind, [] as Entry[]]),
+ ) as Record<CheckpointKind, Entry[]>;
let retainedUntyped = 0;
for (const e of entries) {
if (e.kind === null) {
retainedUntyped++;
continue;
}
- byKind[e.kind].push(e);
+ byBucket[CHECKPOINT_KIND_REGISTRY[e.kind].gcBucket].push(e);
}
const now = Date.now();
@@ -1289,12 +1516,7 @@ async function gcCheckpointRefsInner(
const planDeletions = (
list: Entry[],
limit: number,
- counter:
- | 'deletedBridgeMergeLoss'
- | 'deletedProducerGuardLoss'
- | 'deletedObserverADuplication'
- | 'deletedExternalChangeRescue'
- | 'deletedAutoConsolidation',
+ counter: GcDeletionCounter,
// auto-consolidation is count-only: TTL must never be able to reap every
// surviving auto-checkpoint, or the chained consolidated history it anchors
// becomes unreachable. Pass false to disable the TTL lower bound.
@@ -1317,28 +1539,18 @@ async function gcCheckpointRefsInner(
}
}
};
- planDeletions(byKind['bridge-merge-loss'], policy.maxBridgeMergeLoss, 'deletedBridgeMergeLoss');
- planDeletions(
- byKind['producer-guard-loss'],
- policy.maxProducerGuardLoss,
- 'deletedProducerGuardLoss',
- );
- planDeletions(
- byKind['observer-a-duplication'],
- policy.maxObserverADuplication,
- 'deletedObserverADuplication',
- );
- planDeletions(
- byKind['external-change-rescue'],
- policy.maxExternalChangeRescue,
- 'deletedExternalChangeRescue',
- );
- planDeletions(
- byKind['auto-consolidation'],
- policy.maxAutoConsolidation,
- 'deletedAutoConsolidation',
- false,
- );
+ // Exhaustive by construction: every bucket in the registry gets a plan, and
+ // `GC_BUCKET_POLICY` is `satisfies Record<CheckpointKind, …>` so a new kind
+ // cannot compile without declaring its limit, counter, and TTL applicability.
+ for (const bucket of CHECKPOINT_KINDS) {
+ const bucketPolicy = GC_BUCKET_POLICY[bucket];
+ planDeletions(
+ byBucket[bucket],
+ bucketPolicy.limit(policy),
+ bucketPolicy.counter,
+ bucketPolicy.applyTtl,
+ );
+ }
for (const ref of deleteRefs) {
try {
diff --git a/packages/server/src/timeline-query.ts b/packages/server/src/timeline-query.ts
index 757ebd260..5784f2d57 100644
--- a/packages/server/src/timeline-query.ts
+++ b/packages/server/src/timeline-query.ts
@@ -19,11 +19,12 @@
import { existsSync } from 'node:fs';
import type { EntryType, TimelineEntry } from '@inkeep/open-knowledge-core';
import {
+ isSurfacedCheckpointKind,
parseCheckpoint,
parseOkActors,
readContributors,
} from '@inkeep/open-knowledge-core/shadow-repo-layout';
-import { getDocExtension } from './doc-extensions.ts';
+import { extensionlessDocTreePath, getDocExtension } from './doc-extensions.ts';
import { getLogger } from './logger.ts';
import { managedArtifactTimelinePaths } from './managed-artifact-persistence.ts';
import {
@@ -270,7 +271,7 @@ async function filterEntriesByChain<E extends { sha: string }>(
entries: E[],
chain: Array<{ path: string; renameCommit: string | null }>,
branch: string,
- pathFor: (name: string) => string,
+ pathCandidatesFor: (name: string) => readonly string[],
cache: AncestorShaSetCache,
seedsCache: SeedsCache,
): Promise<E[]> {
@@ -289,7 +290,10 @@ async function filterEntriesByChain<E extends { sha: string }>(
);
// Build the probe list. For each entry, for each chain step where the
- // entry's SHA satisfies the cycle bound, emit one probe.
+ // entry's SHA satisfies the cycle bound, emit one probe per path candidate
+ // (extension-full disk path + the extension-less docName path silent
+ // single-blob checkpoint trees use). The entry is kept if ANY candidate
+ // resolves to a blob in its tree.
type Probe = { entryIdx: number; sha: string; path: string };
const probes: Probe[] = [];
for (let entryIdx = 0; entryIdx < entries.length; entryIdx++) {
@@ -298,7 +302,9 @@ async function filterEntriesByChain<E extends { sha: string }>(
const step = chain[chainIdx];
const ancestors = predecessorAncestors[chainIdx];
if (ancestors !== null && !ancestors.has(entry.sha)) continue;
- probes.push({ entryIdx, sha: entry.sha, path: pathFor(step.path) });
+ for (const path of pathCandidatesFor(step.path)) {
+ probes.push({ entryIdx, sha: entry.sha, path });
+ }
}
}
@@ -492,6 +498,16 @@ export async function getDocumentHistory(
normalizedRoot
? `${normalizedRoot}/${name}${getDocExtension(name)}`
: `${name}${getDocExtension(name)}`;
+ // Ordered tree-path candidates for checkpoint-row filtering: the
+ // extension-full disk path, then the extension-less docName path that silent
+ // single-blob checkpoint trees (`saveInMemoryCheckpoint`) use. `pathFor`
+ // stays single-valued for the byte-identical baseline + git-log pathspec,
+ // where only the real disk path applies.
+ const pathCandidatesFor = (name: string): readonly string[] => {
+ const full = pathFor(name);
+ const extless = extensionlessDocTreePath(full, name);
+ return extless ? [full, extless] : [full];
+ };
// Managed-artifact docs (skills/templates) are versioned under their
// `.ok/...` artifact key, NOT the synthetic `__skill__/...` doc name — so the
@@ -600,7 +616,7 @@ export async function getDocumentHistory(
allEntries,
chain,
branch,
- pathFor,
+ pathCandidatesFor,
cache,
seedsCache,
);
@@ -623,7 +639,7 @@ export async function getDocumentHistory(
const filtered = allEntries.filter(
(e) =>
- (includeAuto || e.checkpoint?.kind !== 'auto-consolidation') &&
+ (includeAuto || isSurfacedCheckpointKind(e.checkpoint?.kind)) &&
matchesAuthor(e, authorFilter) &&
(excludeAuthorFilter.length === 0 || !matchesAuthor(e, excludeAuthorFilter)),
);
@@ -729,7 +745,7 @@ export async function getDocumentHistory(
allCpEntries,
chain,
branch,
- pathFor,
+ pathCandidatesFor,
ancestorSetCache,
seedsCache,
);
@@ -881,12 +897,14 @@ export async function getDocumentHistory(
// tree paths), not user history — never expose them through the timeline.
filtered = filtered.filter((e) => e.type !== 'park');
- // Hide auto-consolidation checkpoint rows by default. The walk already
- // traversed their WIP ancestry (so the WIP rows they anchor stay visible);
- // only the synthetic checkpoint row is dropped, and it is dropped BEFORE
- // pagination so a hidden row never costs a visible page slot.
+ // Hide checkpoint kinds the shared registry marks `visibility: 'hidden'`
+ // (auto-consolidation today) by default. The walk already traversed their
+ // WIP ancestry (so the WIP rows they anchor stay visible); only the
+ // synthetic checkpoint row is dropped, and it is dropped BEFORE pagination
+ // so a hidden row never costs a visible page slot. Registry-driven so a
+ // future hidden kind is excluded without editing this filter.
if (!includeAuto) {
- filtered = filtered.filter((e) => e.checkpoint?.kind !== 'auto-consolidation');
+ filtered = filtered.filter((e) => isSurfacedCheckpointKind(e.checkpoint?.kind));
}
// Drop no-op rows: a WIP/upstream commit whose blob for this doc is