Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
PRD-9752 Follow outside renames and handle branch switches as edits (#7170)
mike-inkeepe4467f0a47d2
diff --git a/.changeset/follow-outside-renames.md b/.changeset/follow-outside-renames.mdnew file mode 100644index 000000000..6e74a0689--- /dev/null+++ b/.changeset/follow-outside-renames.md@@ -0,0 +1,5 @@+---+'@inkeep/open-knowledge': patch+---++Moving or renaming an open document outside OpenKnowledge now keeps it open under its new name with your unsaved typing. If its file is deleted, your typing is saved to history first. Switching git branches merges unsaved typing with the new branch instead of replacing it.diff --git a/docs/content/features/timeline-and-recovery.mdx b/docs/content/features/timeline-and-recovery.mdxindex fccecf352..a424bdd0d 100644--- a/docs/content/features/timeline-and-recovery.mdx+++ b/docs/content/features/timeline-and-recovery.mdx@@ -25,7 +25,13 @@ Project-wide checkpoints saved by agents via the [`checkpoint` MCP tool](/docs/rOpenKnowledge also saves recovery entries itself. When it detects an external file change on its own and has no acknowledged base to merge the change against, the disk version replaces the document and the pre-change version is preserved as a **Recovered content** entry, which you can restore like any other timeline entry. When an outside edit and the document's open version change the same paragraph, both versions stay in the document, the open version first and the outside version directly under it, nothing is asked, and both earlier versions are saved as entries. When one side deleted a paragraph the other changed, the changed version stays in the document, and both earlier versions are saved as entries. When the two cannot be merged safely, for example a very large file or a merge OpenKnowledge cannot verify, the open version stays and the outside version is saved as an entry. An agent write that meets an outside edit follows the same rules and lands. OpenKnowledge raises a conflict, and changes nothing until it is resolved, when the file on disk holds Git conflict markers, when it cannot save the outside version to the timeline, when an agent write has no acknowledged version to merge against, or when another app restores an exact older copy over an acknowledged edit (see [Conflicts that don't come from Git](/docs/features/git/sync#conflicts-that-dont-come-from-git)).-When both versions were kept, or a version was saved to the timeline instead of merged, a notice at the top of that document says what happened. It stays until you dismiss it, unless the document is renamed or deleted, the version it names leaves the timeline, or more than 200 newer notices push it out. Each branch keeps its own notices. Where the window has a timeline and entries were saved, **Open timeline** shows them. The notice never asks you to choose a version: restoring an entry is how you go back.+When another app or a terminal renames or moves the file of an open document, the document stays open under its new name with any typing you have not saved yet, and its timeline and its notice move with it.++When the file of an open document is deleted outside OpenKnowledge, the document stays open while OpenKnowledge re-checks the folder, in case the file was moved rather than deleted. If no moved file turns up, usually within a few seconds and at most about 30 seconds, the delete stands: any unsaved typing is first saved as a **Recovered content** entry on that document's timeline, then the document closes, and nothing is written back to the deleted path. The entry stays under the document's name: agents can read it with the `history` tool, and it shows on the timeline again if a document with the same name is created.++A Git branch switch, pull, stash or reset is taken in like any other outside change. Typing you had not saved yet is merged into the new branch's version of each open file, and where both changed the same paragraph, both versions stay in the document and both earlier versions are saved as entries, as described above.++When both versions were kept, or a version was saved to the timeline instead of merged, a notice at the top of that document says what happened. It stays until you dismiss it, unless the document is deleted, the version it names leaves the timeline, or more than 200 newer notices, counted across all branches, push it out. If the document is renamed or moved, in the app or outside it, the notice moves with it. Each branch keeps its own notices. Where the window has a timeline and entries were saved, **Open timeline** shows them. The notice never asks you to choose a version: restoring an entry is how you go back.The timeline is not the editor's undo history. Each timeline entry is a snapshot of the whole document, while undo steps back through your own recent edits in the pane where you are working. Agent edits, human edits, and file-system changes are batched into an entry once activity settles. Upstream syncs get their own entry when the sync lands. For when source-mode undo starts fresh, see [Editor → Undo in source mode](/docs/features/editor#undo-in-source-mode).diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdxindex c18404f48..7a9a06b9f 100644--- a/docs/content/reference/mcp.mdx+++ b/docs/content/reference/mcp.mdx@@ -124,13 +124,15 @@ When OpenKnowledge saves a Markdown document, it first compares the file with thA `reconcile` conflict also carries a `reason`: `refused-conflict-markers`, `refused-no-base`, `refused-too-large`, `disk-markers`, or `stale-external-write`; `merged-with-markers` appears only on entries recorded by earlier versions, or when both kept versions could not be applied to the open document. On `stale-external-write` the compatibility field `conflictKind` is `stale-external-write`. Every other row uses `conflictKind: "git"`. An outside edit to the same block as unsaved edits is not a conflict: both versions are kept in the document. `refused-too-large` means a merge past the size cap or one that failed OpenKnowledge's fidelity check, and is raised only when the outside version could not be saved to history; otherwise the OpenKnowledge version stays and the outside version goes to the document's history. The server log names the failed check.-A write to a document whose file was deleted, renamed or moved on disk returns `urn:ok:error:doc-removed` (409): the edit reached collaborative state, but the disk write was refused. Retrying the same write does not help, and the `detail` says which case applies. If the file was deleted, re-create the document with `write` if you still want the content. If it was renamed or moved outside the app, the `detail` names its new path: re-read the document there and re-apply your change. If a different file now sits at the old path and has not been loaded into the document, only a reload of that document from disk clears the refusal, so tell the user instead of retrying.+A write to a document whose file was deleted, renamed or moved on disk returns `urn:ok:error:doc-removed` (409): the edit reached collaborative state, but the disk write was refused. Retrying the same write does not help, and the `detail` says which case applies. If the file was deleted, re-create the document with `write` if you still want the content. If it was renamed or moved and the edit did not move with it, because it reached the document after the move or OpenKnowledge could not carry it, the `detail` names the new path: re-read the document there and re-apply your change. If a different file now sits at the old path and has not been loaded into the document, only a reload of that document from disk clears the refusal, so tell the user instead of retrying.++When OpenKnowledge follows a rename or move made outside the app, it carries the document's text, with every edit it already held, to the new name. A write whose disk save was still pending waits for that to finish, then returns `urn:ok:error:doc-moved` (409) if its edit was carried, and the `detail` names the new name: the edit is saved there, so do not repeat it; re-read the document at its new name. If the edit was not carried, the write returns `urn:ok:error:doc-removed` as described above. Waiting for the carry counts toward the same 20 seconds as the rest of the write. If the carry has not finished when they run out, the write returns success before its disk save and no error follows: the edit goes wherever the carry takes it, to the new name or, if the carry fails, to the document's history. Re-read the document at its new name to confirm. While the file of an open document is missing, OpenKnowledge holds the document for a re-check of the folder, in case the file was moved rather than deleted, and a write's disk save waits up to 20 seconds for that to settle. If OpenKnowledge then follows a move, the write returns `urn:ok:error:doc-moved` or `urn:ok:error:doc-removed` by the same rule. If the delete stands, the write returns `urn:ok:error:doc-removed` (409) and the `detail` says the edit went to the document's history, not to disk; re-create the document with `write` if you still want the content. If OpenKnowledge stops while the file is still missing, the write returns `urn:ok:error:server-stopped` (503) and the edit is in the document's history. A hold can last up to 30 seconds. If it is still unresolved when the write's 20 seconds run out, the write returns success before its disk save, so that success does not confirm the edit is on disk: the edit goes wherever the hold resolves, to the new name or to the document's history, and no error follows. Re-read the document to confirm, and if it is gone, look for it under a new name or in its history.A write whose document path cannot be resolved inside the content directory returns `urn:ok:error:path-escape` (400): the edit reached collaborative state, but the disk write was refused. This covers a symlink cycle at the document's own path, a link resolving outside the content directory, and a link resolving into a `.git` folder, an OpenKnowledge config folder itself, or its machine-local state. It is not retryable — repair the path on disk before writing this content again.A write refused because the document's duplication baseline could not be read at the final disk flush returns `urn:ok:error:store-refused` (503): the edit reached collaborative state, but the disk write was refused rather than risk persisting duplicated content. The document file was not updated; the server preserves the edited document, with a copy in its recovery buffer unless that buffer is unavailable or unwritable. Retry only after the filesystem fault is repaired.-A write that arrives while Git is updating the project's `HEAD` or index waits for that to finish and then applies to the checked-out content. That covers a branch switch, a commit, a merge or a reset, and also index-only activity such as `git add` or a `git status` that refreshes the index. Fetching from the remote during sync does not hold writes back; a disk save that sync deferred completes when sync finishes. A request waits at most 20 seconds in total, however many documents it writes. If a branch switch replaces a document whose disk save was still pending, the write returns `urn:ok:error:branch-switched` (409) and the edit was not saved. `POST /api/agent-write-batch` reports this per entry inside its `200` envelope. `restore_version` skips the wait before applying, but its confirmation of the disk save can still wait under the same cap, and it can return the same error. Re-read the document, then repeat the edit if it is still needed. If any of that Git activity is still running when the 20 seconds run out, the write applies anyway and its success response can arrive before the disk save, so that response does not confirm the edit is on disk.+A write that arrives while Git is updating the project's `HEAD` or index waits for that to finish and then applies to the checked-out content. That covers a branch switch, a commit, a merge or a reset, and also index-only activity such as `git add` or a `git status` that refreshes the index. Fetching from the remote during sync does not hold writes back; a disk save that sync deferred completes when sync finishes. A request waits at most 20 seconds in total, however many documents it writes. If a branch switch starts while a write's disk save is still pending, the write returns `urn:ok:error:branch-switched` (409): the edit stays in the open document, merged with the checked-out branch's version of the file the way an outside edit is, and is saved with the document's next save. Do not repeat it; re-read the document to confirm. `POST /api/agent-write-batch` reports this per entry inside its `200` envelope. `restore_version` skips the wait before applying, but its confirmation of the disk save can still wait under the same cap, and it can return the same error. If any of that Git activity is still running when the 20 seconds run out, the write applies anyway and its success response can arrive before the disk save, so that response does not confirm the edit is on disk.A whole-document replace attempted while another writer changed the same document in the last few seconds returns `urn:ok:error:concurrent-overwrite-refused` (409): nothing was written, so there is no partial edit to undo. This is not tracked conflict state, so there is nothing to resolve. A single-document HTTP response carries `retryAfterSeconds` alongside a matching `Retry-After` header, and the `write` tool appends the same bound to its error text (`Retry after 3s.`). After whole-request schema validation succeeds, `POST /api/agent-write-batch` keeps its `200` success envelope; each concurrent-overwrite refusal carries the problem type and `retryAfterSeconds`, while sibling entries are unaffected. Invalid input instead rejects the whole request before processing. Wait that long and repeat the write, or use `position: "append"` or `"prepend"`, or `edit`, which bypass concurrent-overwrite protection but still require valid input. Peer writers are distinguished by identity. Anyone supplying an `agentId` or `x-ok-connection-id` must use a stable value unique to one writer, containing only ASCII `[A-Za-z0-9_-]` characters and 1–64 characters long. A nonconforming `agentId` is discarded: `POST /api/agent-write-md` and `POST /api/agent-write-batch` then treat the caller as unidentified, while `POST /api/lint/fix` falls back to the project [principal](./what-open-knowledge-writes.mdx) when available. A nonconforming `x-ok-connection-id` is silently replaced with a minted identity. A `POST /api/agent-write-md` caller sends its `agentId` on every write. The MCP write tools declare no `agentId` field. OpenKnowledge mints an identity per MCP connection unless an MCP Streamable HTTP client forwards a valid `x-ok-connection-id` while creating the protocol session. Writers that share or reuse an identity share [writer attribution](./core-concepts.md#attribution-and-collaboration), the server-side write session, and undo history, and are not refused against each other; the server does not detect identity collisions. Having an identity records you as a peer, so a `replace` carrying a different identity is refused for the next few seconds, while your own recent write does not arm the refusal against your follow-up `replace`. A writer that has no identity of its own is never recorded as a peer, so it never arms the refusal against a later writer. That covers a `POST /api/agent-write-md` that omits `agentId`, and a `lint` fix that both omits `agentId` and runs on a project with no principal. A caller that sent no `agentId` is still refused its own `replace` when a writer that did send one changed the document in the last few seconds, because that caller cannot be shown to be the recorded writer. Two `POST /api/agent-write-md` callers that both omit `agentId` are never refused against each other, though a recent change from a connected editor still refuses both of them.diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex 8d0140dc7..33d2594f8 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -153,7 +153,7 @@ The app runs a collaboration server for the open project. It writes runtime stat| `.ok/local/sync-state.json` | GitHub-sync engine state | In-project, gitignored || `.ok/local/conflicts.json` | Every conflict the app is holding a document for, including conflicts that involve no remote. A row for OpenKnowledge's own merge of the editor against disk embeds up to three full copies of the document body, so **keep this file while any conflict is open**. Deleting it loses those copies. If the app cannot read the file, it renames it to `conflicts.json.corrupt-<timestamp>` and leaves it in place | In-project, gitignored || `.ok/local/stale-external-writes.json` | Recovery snapshot for a rejected stale external save. It can hold the acknowledged, rejected, and retained document text. Protection expires after 30 minutes, but an unresolved snapshot stays until you resolve the conflict | In-project, gitignored |-| `.ok/local/doc-notices.json` | The notice a document shows after both versions of an edit were kept, or a version was saved to the timeline instead of merged: document names, times, and timeline entry ids, never document text. A notice is removed when you dismiss it, when its document is renamed or deleted, when the version it names leaves the timeline, or when more than 200 newer notices push it out, and each branch keeps its own. If the app cannot read the file, it starts with no notices | In-project, gitignored |+| `.ok/local/doc-notices.json` | The notice a document shows after both versions of an edit were kept, or a version was saved to the timeline instead of merged: document names, times, and timeline entry ids, never document text. A notice is removed when you dismiss it, when its document is deleted, when the version it names leaves the timeline, or when more than 200 newer notices, counted across all branches, push it out. It follows its document through a rename, and each branch keeps its own. If the app cannot read the file, it starts with no notices | In-project, gitignored || `.ok/local/receipts.jsonl` | One record per document OpenKnowledge has opened or saved: a hash of the version it and the file last agreed on, its size, and the file's identity and modification time. No document text. OpenKnowledge keeps the same record in memory while it runs, and a save of a Markdown document compares the file with that record first, so an outside edit is merged instead of written over; other writers do not check it yet. After a restart the file is only used to count documents changed while OpenKnowledge was closed. Safe to delete: the next load rebuilds it | In-project, gitignored || `.ok/local/state.json`, `.ok/local/last-spawn-error.log` | State-schema manifest and the last detached-spawn error log | In-project, gitignored || `.ok/local/acp-agents.json` | Read, not written: your own list of [custom in-app agents](../features/editor.mdx#add-your-own-in-app-agent), re-read every time the agent catalog is built | In-project, gitignored |@@ -297,7 +297,7 @@ On Windows, Claude Desktop and OpenCode configs live under `%APPDATA%\Claude\` a| `.ok/local/sync-state.json` | GitHub-sync engine state | In-project, gitignored || `.ok/local/conflicts.json` | Every conflict the app is holding a document for, including conflicts that involve no remote. A row for OpenKnowledge's own merge of the editor against disk embeds up to three full copies of the document body, so **keep this file while any conflict is open**. Deleting it loses those copies. If the app cannot read the file, it renames it to `conflicts.json.corrupt-<timestamp>` and leaves it in place | In-project, gitignored || `.ok/local/stale-external-writes.json` | Recovery snapshot for a rejected stale external save. It can hold the acknowledged, rejected, and retained document text. Protection expires after 30 minutes, but an unresolved snapshot stays until you resolve the conflict | In-project, gitignored |-| `.ok/local/doc-notices.json` | The notice a document shows after both versions of an edit were kept, or a version was saved to the timeline instead of merged: document names, times, and timeline entry ids, never document text. A notice is removed when you dismiss it, when its document is renamed or deleted, when the version it names leaves the timeline, or when more than 200 newer notices push it out, and each branch keeps its own. If the app cannot read the file, it starts with no notices | In-project, gitignored |+| `.ok/local/doc-notices.json` | The notice a document shows after both versions of an edit were kept, or a version was saved to the timeline instead of merged: document names, times, and timeline entry ids, never document text. A notice is removed when you dismiss it, when its document is deleted, when the version it names leaves the timeline, or when more than 200 newer notices, counted across all branches, push it out. It follows its document through a rename, and each branch keeps its own. If the app cannot read the file, it starts with no notices | In-project, gitignored || `.ok/local/receipts.jsonl` | One record per document OpenKnowledge has opened or saved: a hash of the version it and the file last agreed on, its size, and the file's identity and modification time. No document text. OpenKnowledge keeps the same record in memory while it runs, and a save of a Markdown document compares the file with that record first, so an outside edit is merged instead of written over; other writers do not check it yet. After a restart the file is only used to count documents changed while OpenKnowledge was closed. Safe to delete: the next load rebuilds it | In-project, gitignored || `.ok/local/state.json`, `.ok/local/last-spawn-error.log` | State-schema manifest and the last detached-spawn error log | In-project, gitignored || `.ok/local/acp-agents.json` | Read, not written: your own list of [custom in-app agents](../features/editor.mdx#add-your-own-in-app-agent), re-read every time the agent catalog is built | In-project, gitignored |diff --git a/packages/app/tests/integration/branch-switch-agent-write.test.ts b/packages/app/tests/integration/branch-switch-agent-write.test.tsindex 21d34e461..3d261fa3e 100644--- a/packages/app/tests/integration/branch-switch-agent-write.test.ts+++ b/packages/app/tests/integration/branch-switch-agent-write.test.ts@@ -95,7 +95,7 @@ async function settledWithin<T>(promise: Promise<T>, ms: number): Promise<booleadescribe('agent writes during a git branch switch', () => {test.runIf(process.platform !== 'win32')(- 'a patch sent after the reset but before the switch settles is written to the new branch',+ 'a patch sent while the switch settles is held, then written to the new branch',async () => {let releaseSettle: () => void = () => {};const settleHeld = new Promise<void>((resolve) => {@@ -120,11 +120,10 @@ describe('agent writes during a git branch switch', () => {git(contentDir, 'checkout feature');await pollUntil(- () =>- settleSpy.mock.calls.length > 0 && serverText(server, 'notes').includes('On feature.'),+ () => settleSpy.mock.calls.length > 0,20_000,50,- 'the branch switch to reset the open document and reach the held settle',+ 'the branch switch to reach the held settle',);expect(server.instance.durabilityState.isBatchInProgress()).toBe(true);@@ -181,7 +180,7 @@ describe('agent writes during a git branch switch', () => {);test.runIf(process.platform !== 'win32')(- 'a write whose deferred store is discarded by the switch is not acknowledged as saved',+ 'a write whose deferred store is discarded by the switch is reported as kept in the open document',async () => {const { contentDir, server } = await bootOnMainWithFeatureBranch();const durability = server.instance.durabilityState;@@ -218,11 +217,12 @@ describe('agent writes during a git branch switch', () => {);expect(response.status).toBe(409);- expect((response.body as { type?: string } | null)?.type).toBe(- 'urn:ok:error:branch-switched',- );+ const problem = response.body as { type?: string; detail?: string } | null;+ expect(problem?.type).toBe('urn:ok:error:branch-switched');+ expect(problem?.detail).toContain('do not repeat the edit');expect(ackedBeforeSwitch).toBe(false);expect(readNotes(contentDir)).not.toContain('Appended before the switch.');+ expect(serverText(server, 'notes')).toContain('Appended before the switch.');},90_000,);diff --git a/packages/app/tests/integration/branch-switch-batch.test.ts b/packages/app/tests/integration/branch-switch-batch.test.tsnew file mode 100644index 000000000..7649673d0--- /dev/null+++ b/packages/app/tests/integration/branch-switch-batch.test.ts@@ -0,0 +1,227 @@+import { execSync } from 'node:child_process';+import {+ chmodSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ realpathSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { ensureProjectGit } from '@inkeep/open-knowledge-server';+import { afterEach, describe, expect, test, vi } from 'vitest';+import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';+import { getLogger } from '../../../server/src/logger';+import { getMetrics } from '../../../server/src/metrics';+import {+ BRANCH_SWITCH_FOLLOW_UP_DELAY_MS,+ BRANCH_SWITCH_FOLLOW_UP_LIMIT,+} from '../../../server/src/server-factory';+import { createManualClock } from '../../../server/src/watcher-clock.test-helper';+import { createWatcherDouble } from '../../../server/src/watcher-double.test-helper';+import { createTestClient, createTestServer, pollUntil } from './test-harness';++const cleanups: Array<() => Promise<void> | void> = [];+const CAN_REVOKE_READ = process.platform !== 'win32' && process.getuid?.() !== 0;++afterEach(async () => {+ for (const cleanup of cleanups.splice(0).reverse()) await cleanup();+});++function git(cwd: string, args: string): void {+ execSync(`git ${args}`, {+ cwd,+ env: {+ ...process.env,+ GIT_CONFIG_GLOBAL: '/dev/null',+ GIT_AUTHOR_NAME: 'test',+ GIT_AUTHOR_EMAIL: '[email protected]',+ GIT_COMMITTER_NAME: 'test',+ GIT_COMMITTER_EMAIL: '[email protected]',+ },+ stdio: 'ignore',+ });+}++async function openNotesTypedOnMain() {+ const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-branch-switch-batch-')));+ cleanups.push(() => rmSync(contentDir, { recursive: true, force: true }));+ await ensureProjectGit(contentDir);+ configureTestGitRepository(contentDir);+ const notes = join(contentDir, 'notes.md');+ writeFileSync(notes, '# Notes\n\nShared line on main.\n\nTail.\n');+ git(contentDir, 'add notes.md');+ git(contentDir, 'commit -m main');+ git(contentDir, 'checkout -b feature');+ writeFileSync(notes, '# Notes\n\nShared line on feature.\n\nTail.\n');+ git(contentDir, 'commit -am feature');+ git(contentDir, 'checkout main');++ const double = createWatcherDouble();+ const clock = createManualClock(Date.now());+ const server = await createTestServer({+ contentDir,+ keepContentDir: true,+ gitEnabled: true,+ watcherBackend: double.backend,+ watcherClock: clock,+ debounce: 300_000,+ maxDebounce: 600_000,+ });+ cleanups.push(() => server.cleanup());+ const client = await createTestClient(server.port, 'notes', { skipInvariantWatcher: true });+ cleanups.push(() => client.cleanup());+ await pollUntil(() => client.ytext.toString().includes('on main.'), 10_000, 25, 'the load');+ const liveText = () =>+ server.instance.hocuspocus.documents.get('notes')?.getText('source').toString() ?? '';++ client.doc.transact(() => {+ const at = client.ytext.toString().indexOf('Shared line on main.');+ client.ytext.delete(at, 'Shared line on main.'.length);+ client.ytext.insert(at, 'Shared line on main, typed here.');+ });+ await pollUntil(() => liveText().includes('typed here'), 10_000, 25, 'the typing');++ const switchTo = async (branch: 'feature' | 'main', clockStepMs: number): Promise<void> => {+ git(contentDir, `checkout -f ${branch}`);+ expect(readFileSync(notes, 'utf-8')).toContain(`on ${branch}.`);+ double+ .subscriptionFor(join(contentDir, '.git'))+ .deliver([{ type: 'update', path: join(contentDir, '.git', 'HEAD') }]);+ await pollUntil(+ () => server.instance.durabilityState.isBatchInProgress(),+ 10_000,+ 25,+ 'the switch to open a batch',+ );+ double.subscriptionFor(contentDir).deliver([{ type: 'update', path: notes }]);+ await pollUntil(+ () => {+ clock.advance(clockStepMs);+ return (+ !server.instance.durabilityState.isBatchInProgress() &&+ liveText().includes(`on ${branch}.`)+ );+ },+ 15_000,+ 25,+ `the switch to ${branch} to end and take in its file`,+ );+ };++ return {+ contentDir,+ clock,+ liveText,+ lifecycleStatus: () =>+ server.instance.hocuspocus.documents.get('notes')?.getMap('lifecycle').get('status'),+ switchToFeature: () => switchTo('feature', 100),+ switchBackToMain: () => switchTo('main', 1),+ };+}++describe('a git branch switch is taken in like any other outside change', () => {+ test.runIf(process.platform !== 'win32')(+ 'unsaved typing in the block the other branch changed keeps both versions',+ async () => {+ const rig = await openNotesTypedOnMain();+ const shortfallsBefore = getMetrics().branchSwitchRecheckShortfalls;++ await rig.switchToFeature();++ expect(rig.liveText()).toContain('Shared line on main, typed here.');+ expect(rig.liveText()).toContain('Shared line on feature.');+ expect(rig.liveText()).not.toContain('<<<<<<<');+ expect(rig.lifecycleStatus()).toBeUndefined();+ expect(getMetrics().branchSwitchRecheckShortfalls - shortfallsBefore).toBe(0);+ },+ 60_000,+ );++ test.runIf(CAN_REVOKE_READ)(+ 'a switch whose re-check cannot read the whole tree is checked again a bounded number of times',+ async () => {+ const rig = await openNotesTypedOnMain();+ const locked = join(rig.contentDir, 'locked');+ mkdirSync(locked);+ writeFileSync(join(locked, 'inside.md'), '# Inside\n');+ chmodSync(locked, 0o000);+ cleanups.push(() => chmodSync(locked, 0o755));+ const shortfallsBefore = getMetrics().branchSwitchRecheckShortfalls;+ const shortfalls = () => getMetrics().branchSwitchRecheckShortfalls - shortfallsBefore;++ await rig.switchToFeature();+ expect(rig.liveText()).toContain('Shared line on main, typed here.');++ await pollUntil(+ () => {+ rig.clock.advance(1_000);+ return shortfalls() >= 1 + BRANCH_SWITCH_FOLLOW_UP_LIMIT;+ },+ 15_000,+ 25,+ 'the switch re-check and every follow-up to fall short',+ );+ for (let tick = 0; tick < 20; tick++) {+ rig.clock.advance(BRANCH_SWITCH_FOLLOW_UP_DELAY_MS);+ await new Promise((resolve) => setTimeout(resolve, 25));+ }+ expect(shortfalls()).toBe(1 + BRANCH_SWITCH_FOLLOW_UP_LIMIT);+ },+ 60_000,+ );++ test.runIf(CAN_REVOKE_READ)(+ 'a later switch that observes the whole tree ends the follow-up re-checks of an earlier one',+ async () => {+ const rig = await openNotesTypedOnMain();+ const locked = join(rig.contentDir, 'locked');+ mkdirSync(locked);+ writeFileSync(join(locked, 'inside.md'), '# Inside\n');+ chmodSync(locked, 0o000);+ cleanups.push(() => chmodSync(locked, 0o755));+ const shortfallsBefore = getMetrics().branchSwitchRecheckShortfalls;+ const shortfalls = () => getMetrics().branchSwitchRecheckShortfalls - shortfallsBefore;++ await rig.switchToFeature();+ await pollUntil(+ () => {+ rig.clock.advance(1);+ return shortfalls() >= 2;+ },+ 15_000,+ 25,+ 'the switch re-check and its first follow-up to fall short',+ );+ chmodSync(locked, 0o755);+ await rig.switchBackToMain();+ expect(shortfalls()).toBe(2);++ chmodSync(locked, 0o000);+ const serverLog = getLogger('server');+ const followUpLines: string[] = [];+ const capture = (...args: unknown[]) => {+ for (const arg of args) {+ if (typeof arg === 'string' && arg.includes('after switching to feature')) {+ followUpLines.push(arg);+ }+ }+ };+ const info = vi.spyOn(serverLog, 'info').mockImplementation(capture);+ const warn = vi.spyOn(serverLog, 'warn').mockImplementation(capture);+ cleanups.push(() => {+ info.mockRestore();+ warn.mockRestore();+ });+ for (let tick = 0; tick < 20; tick++) {+ rig.clock.advance(BRANCH_SWITCH_FOLLOW_UP_DELAY_MS);+ await new Promise((resolve) => setTimeout(resolve, 25));+ }+ expect(followUpLines).toEqual([]);+ expect(shortfalls()).toBe(2);+ },+ 60_000,+ );+});diff --git a/packages/app/tests/integration/outside-rename-pairing.test.ts b/packages/app/tests/integration/outside-rename-pairing.test.tsnew file mode 100644index 000000000..7b5218407--- /dev/null+++ b/packages/app/tests/integration/outside-rename-pairing.test.ts@@ -0,0 +1,569 @@+import { randomUUID } from 'node:crypto';+import {+ chmodSync,+ existsSync,+ mkdirSync,+ readFileSync,+ renameSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import { join } from 'node:path';+import { resolveShadowDir } from '@inkeep/open-knowledge-core/shadow-repo-layout';+import { afterEach, describe, expect, test, vi } from 'vitest';+import { contentHash } from '../../../server/src/file-watcher';+import { getLogger } from '../../../server/src/logger';+import { getMetrics } from '../../../server/src/metrics';+import { loadRenameLogIndex, resetRenameLogIndexCache } from '../../../server/src/rename-log';+import { VANISH_HOLD_LIMIT_MS } from '../../../server/src/vanished-documents';+import { createManualClock, type ManualClock } from '../../../server/src/watcher-clock.test-helper';+import { createWatcherDouble } from '../../../server/src/watcher-double.test-helper';+import { fetchDocNotices } from '../../src/hooks/use-doc-notices';+import {+ agentWriteMd,+ createTestClient,+ createTestServer,+ pollUntil,+ type TestClient,+ type TestServer,+} from './test-harness';++const SAVED = '# Doc\n\nShared paragraph.\n\nTail.\n';++const cleanups: Array<() => Promise<void> | void> = [];+const realFetch = globalThis.fetch;++afterEach(async () => {+ globalThis.fetch = realFetch;+ resetRenameLogIndexCache();+ for (const cleanup of cleanups.splice(0).reverse()) await cleanup();+});++interface Rig {+ server: TestServer;+ double: ReturnType<typeof createWatcherDouble>;+ clock: ManualClock;+ client: TestClient;+ docName: string;+ file: string;+ movedName: string;+ moved: string;+}++const CAN_REVOKE_READ = process.platform !== 'win32' && process.getuid?.() !== 0;++async function openUnsavedDocument(+ options: { debounce?: number; maxDebounce?: number } = {},+): Promise<Rig> {+ const double = createWatcherDouble();+ const clock = createManualClock(Date.now());+ const server = await createTestServer({+ gitEnabled: true,+ commitDebounceMs: 50,+ watcherBackend: double.backend,+ watcherClock: clock,+ freshnessIntervalMs: 5_000,+ debounce: options.debounce ?? 300_000,+ maxDebounce: options.maxDebounce ?? 600_000,+ });+ cleanups.push(() => server.cleanup());+ globalThis.fetch = (input, init) =>+ realFetch(+ typeof input === 'string' && input.startsWith('/')+ ? `http://127.0.0.1:${server.port}${input}`+ : input,+ init,+ );+ const docName = `outside-move-${randomUUID()}`;+ const file = join(server.contentDir, `${docName}.md`);+ await agentWriteMd(server.port, SAVED, { docName, position: 'replace' });+ await pollUntil(+ () => existsSync(file) && readFileSync(file, 'utf-8') === SAVED,+ 10_000,+ 25,+ 'the seeded document to reach disk',+ );+ const client = await createTestClient(server.port, docName, { skipInvariantWatcher: true });+ cleanups.push(() => client.cleanup());+ await pollUntil(() => client.ytext.toString() === SAVED, 10_000, 25, 'the client to load');+ const movedName = `${docName}-moved`;+ return {+ server,+ double,+ clock,+ client,+ docName,+ file,+ movedName,+ moved: join(server.contentDir, `${movedName}.md`),+ };+}++function liveText(rig: Rig, docName: string): string {+ return rig.server.instance.hocuspocus.documents.get(docName)?.getText('source').toString() ?? '';+}++function lifecycleOf(rig: Rig, docName: string): unknown {+ return rig.server.instance.hocuspocus.documents.get(docName)?.getMap('lifecycle').get('status');+}++async function type(rig: Rig, line: string): Promise<void> {+ rig.client.ytext.insert(rig.client.ytext.length, `\n${line}\n`);+ await pollUntil(() => liveText(rig, rig.docName).includes(line), 10_000, 25, `"${line}"`);+}++function deliver(rig: Rig, type: 'create' | 'update' | 'delete', path: string): void {+ rig.double.subscriptionFor(rig.server.contentDir).deliver([{ type, path }]);+}++async function textOf(rig: Rig, docName: string): Promise<string> {+ const response = await realFetch(+ `http://127.0.0.1:${rig.server.port}/api/document?docName=${encodeURIComponent(docName)}`,+ );+ if (response.status !== 200) return '';+ return ((await response.json()) as { content?: string }).content ?? '';+}++async function awaitRenamed(rig: Rig): Promise<void> {+ await pollUntil(() => lifecycleOf(rig, rig.docName) === 'renamed', 10_000, 25, 'the move');+}++async function awaitVanished(pendingBefore: number): Promise<void> {+ await pollUntil(+ () => getMetrics().vanishPending > pendingBefore,+ 10_000,+ 25,+ 'the vanished document to be held',+ );+}++describe('an open document whose file moves outside the app', () => {+ test('a move delivered as a delete and later a create keeps the typing from before and during the gap', async () => {+ const rig = await openUnsavedDocument();+ await type(rig, 'Typed before the move.');+ const pendingBefore = getMetrics().vanishPending;++ renameSync(rig.file, rig.moved);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ expect(lifecycleOf(rig, rig.docName)).toBeUndefined();+ await type(rig, 'Typed while the move was half delivered.');++ deliver(rig, 'create', rig.moved);+ await awaitRenamed(rig);+ expect(+ rig.server.instance.hocuspocus.documents.get(rig.docName)?.getMap('lifecycle').get('newPath'),+ ).toBe(rig.movedName);+ await pollUntil(+ async () => (await textOf(rig, rig.movedName)).includes('Typed while the move'),+ 10_000,+ 25,+ 'the moved document to carry the typing',+ );+ const moved = await textOf(rig, rig.movedName);+ expect(moved).toContain('Typed before the move.');+ expect(moved).toContain('Shared paragraph.');+ expect(existsSync(rig.file)).toBe(false);++ const durability = rig.server.instance.durabilityState;+ expect(durability.getReceipt(rig.docName)).toBeUndefined();+ expect(durability.getReceipt(rig.movedName)?.hash).toBe(+ contentHash(readFileSync(rig.moved, 'utf-8')),+ );++ await pollUntil(+ () => {+ resetRenameLogIndexCache();+ const renames = loadRenameLogIndex(resolveShadowDir(rig.server.contentDir));+ return renames.byTo.get(rig.movedName)?.from === rig.docName;+ },+ 10_000,+ 25,+ 'the move to be recorded in the rename log',+ );+ }, 60_000);++ test('a move whose create the watcher never delivers is found by the re-check after the delete', async () => {+ const rig = await openUnsavedDocument();+ await type(rig, 'Typed before a silent move.');+ const pendingBefore = getMetrics().vanishPending;++ renameSync(rig.file, rig.moved);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ rig.clock.advance(1_000);++ await awaitRenamed(rig);+ await pollUntil(+ async () => (await textOf(rig, rig.movedName)).includes('Typed before a silent move.'),+ 10_000,+ 25,+ 'the moved document to carry the typing',+ );+ expect(lifecycleOf(rig, rig.docName)).toBe('renamed');+ expect(existsSync(rig.file)).toBe(false);+ }, 60_000);++ test('a move with an edit is paired by file identity and the edit merges with the typing', async () => {+ const rig = await openUnsavedDocument();+ await type(rig, 'Typed before the move and edit.');+ const pairedBefore = getMetrics().vanishPairedIdentity;+ const pendingBefore = getMetrics().vanishPending;++ renameSync(rig.file, rig.moved);+ writeFileSync(rig.moved, '# Doc\n\nShared paragraph.\n\nTail, edited outside.\n');+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ deliver(rig, 'create', rig.moved);++ await awaitRenamed(rig);+ expect(getMetrics().vanishPairedIdentity - pairedBefore).toBe(1);+ await pollUntil(+ async () => {+ const moved = await textOf(rig, rig.movedName);+ return (+ moved.includes('Typed before the move and edit.') && moved.includes('edited outside')+ );+ },+ 10_000,+ 25,+ 'the typing and the outside edit to merge in the moved document',+ );+ }, 60_000);++ test('a delete with no matching create stands after the re-check, and the typing is kept in history', async () => {+ const rig = await openUnsavedDocument();+ await type(rig, 'Typed before the delete.');+ const deletedBefore = getMetrics().vanishDeleted;+ const pendingBefore = getMetrics().vanishPending;++ rmSync(rig.file);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ expect(lifecycleOf(rig, rig.docName)).toBeUndefined();+ rig.clock.advance(1_000);++ await pollUntil(+ () => getMetrics().vanishDeleted > deletedBefore,+ 10_000,+ 25,+ 'the delete to stand',+ );+ expect(existsSync(rig.file)).toBe(false);+ await pollUntil(+ async () => {+ const response = await realFetch(`http://127.0.0.1:${rig.server.port}/api/rescue`);+ const entries = (await response.json()) as Array<{ docName: string }>;+ return entries.some((entry) => entry.docName === rig.docName);+ },+ 10_000,+ 50,+ 'the typing to be kept in history',+ );+ }, 60_000);++ test('a save split into a delete and a create at the same path is taken in as an edit', async () => {+ const rig = await openUnsavedDocument();+ await type(rig, 'Typed before the outside save.');+ const recreatedBefore = getMetrics().vanishRecreated;+ const pendingBefore = getMetrics().vanishPending;++ rmSync(rig.file);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ writeFileSync(rig.file, '# Doc\n\nShared paragraph.\n\nTail, saved outside.\n');+ deliver(rig, 'create', rig.file);++ await pollUntil(+ () => liveText(rig, rig.docName).includes('saved outside'),+ 10_000,+ 25,+ 'the outside save to merge',+ );+ expect(liveText(rig, rig.docName)).toContain('Typed before the outside save.');+ expect(lifecycleOf(rig, rig.docName)).toBeUndefined();+ expect(getMetrics().vanishRecreated - recreatedBefore).toBe(1);+ }, 60_000);++ test('the re-check that finds a file gone does not settle it; the next whole pass does', async () => {+ const rig = await openUnsavedDocument();+ await type(rig, 'Typed before a silent delete.');+ const pendingBefore = getMetrics().vanishPending;+ const deletedBefore = getMetrics().vanishDeleted;++ rmSync(rig.file);+ await rig.server.instance.recheckDisk();+ expect(getMetrics().vanishPending - pendingBefore).toBe(1);+ expect(getMetrics().vanishDeleted - deletedBefore).toBe(0);+ expect(lifecycleOf(rig, rig.docName)).toBeUndefined();+ expect(rig.server.instance.hocuspocus.documents.has(rig.docName)).toBe(true);++ await rig.server.instance.recheckDisk();+ expect(getMetrics().vanishDeleted - deletedBefore).toBe(1);+ expect(existsSync(rig.file)).toBe(false);+ }, 60_000);++ test.runIf(CAN_REVOKE_READ)(+ 'a pass that cannot read the whole tree does not settle a held document, and the hold limit resolves it visibly',+ async () => {+ const rig = await openUnsavedDocument();+ const locked = join(rig.server.contentDir, 'locked');+ mkdirSync(locked);+ writeFileSync(join(locked, 'inside.md'), '# Inside\n');+ chmodSync(locked, 0o000);+ cleanups.push(() => chmodSync(locked, 0o755));+ await type(rig, 'Typed before a delete while a folder is unreadable.');+ const pendingBefore = getMetrics().vanishPending;+ const deletedBefore = getMetrics().vanishDeleted;+ const unconfirmedBefore = getMetrics().vanishUnconfirmed;++ rmSync(rig.file);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ await rig.server.instance.recheckDisk();+ await rig.server.instance.recheckDisk();+ expect(getMetrics().vanishDeleted - deletedBefore).toBe(0);+ expect(lifecycleOf(rig, rig.docName)).toBeUndefined();++ rig.clock.advance(VANISH_HOLD_LIMIT_MS);+ await pollUntil(+ () => getMetrics().vanishUnconfirmed > unconfirmedBefore,+ 10_000,+ 25,+ 'the hold limit to resolve the document',+ );+ expect(getMetrics().vanishDeleted - deletedBefore).toBe(0);+ expect(existsSync(rig.file)).toBe(false);+ await pollUntil(+ async () => {+ const response = await realFetch(`http://127.0.0.1:${rig.server.port}/api/rescue`);+ const entries = (await response.json()) as Array<{ docName: string }>;+ return entries.some((entry) => entry.docName === rig.docName);+ },+ 10_000,+ 50,+ 'the typing to be kept in history',+ );+ },+ 60_000,+ );++ test('a held document whose settling fails after its hold ended is reported as released, and another still settles', async () => {+ const rig = await openUnsavedDocument();+ const otherName = `${rig.docName}-other`;+ const otherFile = join(rig.server.contentDir, `${otherName}.md`);+ await agentWriteMd(rig.server.port, SAVED, { docName: otherName, position: 'replace' });+ await pollUntil(+ () => existsSync(otherFile) && readFileSync(otherFile, 'utf-8') === SAVED,+ 10_000,+ 25,+ 'the second document to reach disk',+ );+ const other = await createTestClient(rig.server.port, otherName, {+ skipInvariantWatcher: true,+ });+ cleanups.push(() => other.cleanup());+ await pollUntil(() => other.ytext.toString() === SAVED, 10_000, 25, 'the second client');+ const held = rig.server.instance.durabilityState;+ const releaseStores = held.releaseStores.bind(held);+ const releaseFault = vi.spyOn(held, 'releaseStores').mockImplementation((docName: string) => {+ if (docName === rig.docName) throw new Error('release fault');+ releaseStores(docName);+ });+ cleanups.push(() => releaseFault.mockRestore());+ const serverLog = getLogger('server');+ const faults: Array<{ docName?: unknown; stillHeld?: unknown; message: string }> = [];+ const logError = vi+ .spyOn(serverLog, 'error')+ .mockImplementation((data: unknown, message?: unknown) => {+ if (typeof message !== 'string' || !message.includes('internal error')) return;+ const fields = (data ?? {}) as { docName?: unknown; stillHeld?: unknown };+ faults.push({ docName: fields.docName, stillHeld: fields.stillHeld, message });+ });+ cleanups.push(() => logError.mockRestore());+ const pendingBefore = getMetrics().vanishPending;+ const deletedBefore = getMetrics().vanishDeleted;++ rmSync(rig.file);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ rmSync(otherFile);+ deliver(rig, 'delete', otherFile);+ await awaitVanished(pendingBefore + 1);+ await rig.server.instance.recheckDisk();++ expect(held.areStoresHeld(otherName)).toBe(false);+ expect(getMetrics().vanishDeleted - deletedBefore).toBe(1);+ expect(faults).toEqual([expect.objectContaining({ docName: rig.docName, stillHeld: false })]);+ expect(faults[0]?.message).toContain('its hold had already ended');+ }, 60_000);++ test('a store that fires while a document is held is deferred, and the typing reaches only the new name', async () => {+ const rig = await openUnsavedDocument({ debounce: 50, maxDebounce: 200 });+ const pendingBefore = getMetrics().vanishPending;+ const refusalsBefore = getMetrics().persistenceStoreRemovedDocCount;++ renameSync(rig.file, rig.moved);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ await type(rig, 'Typed while held, with a short save delay.');+ await new Promise((resolve) => setTimeout(resolve, 600));+ expect(getMetrics().persistenceStoreRemovedDocCount - refusalsBefore).toBe(0);+ expect(existsSync(rig.file)).toBe(false);++ deliver(rig, 'create', rig.moved);+ await awaitRenamed(rig);+ await pollUntil(+ () => readFileSync(rig.moved, 'utf-8').includes('Typed while held'),+ 10_000,+ 25,+ 'the typing to be saved under the new name',+ );+ expect(existsSync(rig.file)).toBe(false);+ expect(getMetrics().persistenceStoreRemovedDocCount - refusalsBefore).toBe(0);+ }, 60_000);++ test('an agent edit made while the document is held is reported as moved with it when the move is found', async () => {+ const rig = await openUnsavedDocument();+ const pendingBefore = getMetrics().vanishPending;+ renameSync(rig.file, rig.moved);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);++ const write = realFetch(`http://127.0.0.1:${rig.server.port}/api/agent-write-md`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({+ docName: rig.docName,+ markdown: 'Agent line written while held.\n',+ position: 'append',+ agentId: 'held-writer',+ }),+ });+ await pollUntil(+ () => liveText(rig, rig.docName).includes('Agent line'),+ 10_000,+ 25,+ 'the edit',+ );+ deliver(rig, 'create', rig.moved);++ const response = await write;+ expect(response.status).toBe(409);+ const body = (await response.json()) as { type?: string; detail?: string };+ expect(body.type).toBe('urn:ok:error:doc-moved');+ expect(body.detail).toContain(rig.movedName);+ await pollUntil(+ async () => (await textOf(rig, rig.movedName)).includes('Agent line written while held.'),+ 10_000,+ 25,+ 'the agent edit to be in the moved document',+ );+ }, 60_000);++ test('an agent edit made while the document is held is asked to be re-applied when the move cannot carry it', async () => {+ const rig = await openUnsavedDocument();+ const pendingBefore = getMetrics().vanishPending;+ renameSync(rig.file, rig.moved);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ const hocuspocus = rig.server.instance.hocuspocus;+ const openDirect = hocuspocus.openDirectConnection.bind(hocuspocus);+ const carryFault = vi+ .spyOn(hocuspocus, 'openDirectConnection')+ .mockImplementation((...args: Parameters<typeof hocuspocus.openDirectConnection>) =>+ args[0] === rig.movedName ? Promise.reject(new Error('carry fault')) : openDirect(...args),+ );+ cleanups.push(() => carryFault.mockRestore());++ const write = realFetch(`http://127.0.0.1:${rig.server.port}/api/agent-write-md`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({+ docName: rig.docName,+ markdown: 'Agent line the move could not carry.\n',+ position: 'append',+ agentId: 'held-writer',+ }),+ });+ await pollUntil(+ () => liveText(rig, rig.docName).includes('Agent line'),+ 10_000,+ 25,+ 'the edit',+ );+ deliver(rig, 'create', rig.moved);++ const response = await write;+ expect(response.status).toBe(409);+ const body = (await response.json()) as { type?: string; detail?: string };+ expect(body.type).toBe('urn:ok:error:doc-removed');+ expect(body.detail).toContain('re-apply your change there');+ expect(body.detail).toContain(rig.movedName);+ expect(carryFault).toHaveBeenCalledWith(rig.movedName);+ }, 60_000);++ test('an agent edit made while the document is held is reported as kept in history when the delete stands', async () => {+ const rig = await openUnsavedDocument();+ const pendingBefore = getMetrics().vanishPending;+ rmSync(rig.file);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);++ const write = realFetch(`http://127.0.0.1:${rig.server.port}/api/agent-write-md`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({+ docName: rig.docName,+ markdown: 'Agent line written before the delete stood.\n',+ position: 'append',+ agentId: 'held-writer',+ }),+ });+ await pollUntil(+ () => liveText(rig, rig.docName).includes('Agent line'),+ 10_000,+ 25,+ 'the edit',+ );+ rig.clock.advance(1_000);++ const response = await write;+ expect(response.status).toBe(409);+ const body = (await response.json()) as { type?: string; title?: string; detail?: string };+ expect(body.type).toBe('urn:ok:error:doc-removed');+ expect(body.title).toContain('deleted outside the app');+ expect(body.detail).toContain('history');+ expect(existsSync(rig.file)).toBe(false);+ }, 60_000);++ test('a notice on the document follows it to its new name', async () => {+ const rig = await openUnsavedDocument();+ rig.client.doc.transact(() => {+ const at = rig.client.ytext.toString().indexOf('Shared paragraph.');+ rig.client.ytext.delete(at, 'Shared paragraph.'.length);+ rig.client.ytext.insert(at, 'Shared paragraph, edited here.');+ });+ await pollUntil(() => liveText(rig, rig.docName).includes('edited here'));+ writeFileSync(rig.file, '# Doc\n\nShared paragraph, edited outside.\n\nTail.\n');+ await rig.server.instance.recheckDisk();+ await pollUntil(+ async () =>+ ((await fetchDocNotices()) ?? []).some((notice) => notice.docName === rig.docName),+ 10_000,+ 50,+ 'the both-kept notice',+ );+ const pendingBefore = getMetrics().vanishPending;++ renameSync(rig.file, rig.moved);+ deliver(rig, 'delete', rig.file);+ await awaitVanished(pendingBefore);+ deliver(rig, 'create', rig.moved);+ await awaitRenamed(rig);++ const notices = (await fetchDocNotices()) ?? [];+ expect(notices.filter((notice) => notice.docName === rig.docName)).toEqual([]);+ expect(notices.filter((notice) => notice.docName === rig.movedName)).toHaveLength(1);+ }, 60_000);+});diff --git a/packages/app/tests/integration/rename-history.test.ts b/packages/app/tests/integration/rename-history.test.tsindex 9bacb7290..cfa0a8c23 100644--- a/packages/app/tests/integration/rename-history.test.ts+++ b/packages/app/tests/integration/rename-history.test.ts@@ -1,4 +1,4 @@-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';import { join } from 'node:path';import { resolveShadowDir } from '@inkeep/open-knowledge-core/shadow-repo-layout';import { afterEach, describe, expect, test } from 'vitest';@@ -745,6 +745,62 @@ describe('Timeline rename-history mitigation — integration', () => {expect(matching[0].commitSha).toMatch(/^[0-9a-f]{40}$/);}, 60_000);+ test('an outside rename of an open document is claimed by a commit, and its history follows across a restart even when a recorded writer head is gone', async () => {+ const first = await createRestartableServer({ gitEnabled: true, commitDebounceMs: 50 });+ cleanups.push(() => first.shutdown());+ await agentWriteMdAndAwaitWip(first, '# Outside v1\n', {+ docName: 'outside-a',+ position: 'replace',+ ...AGENT,+ });+ const preRenameShas = await getWipShas(first, 'outside-a');+ expect(preRenameShas.size).toBeGreaterThan(0);+ const client = await createTestClient(first.port, 'outside-a', { skipInvariantWatcher: true });+ cleanups.push(() => client.cleanup());+ await pollUntil(() => client.ytext.toString().includes('Outside v1'), 15_000, 50);+ await crossSecondBoundary();++ renameSync(join(first.contentDir, 'outside-a.md'), join(first.contentDir, 'outside-b.md'));+ await pollUntil(+ () =>+ readRenameLogEntries(first).some(+ (entry) =>+ entry.from === 'outside-a' && entry.to === 'outside-b' && entry.commitSha !== '',+ ),+ 20_000,+ 100,+ 'the outside rename to be claimed by a commit',+ );+ expect([...(await getWipShas(first, 'outside-b'))]).toEqual(+ expect.arrayContaining([...preRenameShas]),+ );++ const goneHead = 'f'.repeat(40);+ const logPath = renameLogPath(resolveShadowDir(first.contentDir));+ const plantedLines = readFileSync(logPath, 'utf-8')+ .split('\n')+ .filter((line) => line.length > 0)+ .map((line) => {+ const entry = JSON.parse(line) as RenameLogEntry;+ if (entry.from !== 'outside-a' || entry.to !== 'outside-b') return line;+ expect(entry.anchors?.length ?? 0).toBeGreaterThan(0);+ return JSON.stringify({ ...entry, anchors: [goneHead, ...(entry.anchors ?? [])] });+ });+ writeFileSync(logPath, `${plantedLines.join('\n')}\n`, 'utf-8');++ const second = await first.shutdownAndRestartOnSamePort({ downtimeMs: 0 });+ cleanups.push(() => second.shutdown());+ resetRenameLogIndexCache();+ expect(+ readRenameLogEntries(second).find(+ (entry) => entry.from === 'outside-a' && entry.to === 'outside-b',+ )?.anchors,+ ).toContain(goneHead);+ expect([...(await getWipShas(second, 'outside-b'))]).toEqual(+ expect.arrayContaining([...preRenameShas]),+ );+ }, 90_000);+test('rename followed at once by a graceful restart keeps the pre-rename history', async () => {const first = await createRestartableServer({gitEnabled: true,diff --git a/packages/app/tests/integration/stale-recovery-removal.test.ts b/packages/app/tests/integration/stale-recovery-removal.test.tsindex fab8d2ab2..f42ac5b2a 100644--- a/packages/app/tests/integration/stale-recovery-removal.test.ts+++ b/packages/app/tests/integration/stale-recovery-removal.test.ts@@ -193,6 +193,9 @@ async function recoveryScenario(recreate: boolean) {} else {handlerRelease.resolve();await recovery;+ await expect+ .poll(() => running.instance.hocuspocus.documents.has(docName), { timeout: 10_000 })+ .toBe(false);const { resident, ...after } = await snapshot(initial);expect({ residentPresent: resident !== undefined, ...after }).toMatchObject({disk: null,diff --git a/packages/core/src/handoff/urn-ipc-registry.ts b/packages/core/src/handoff/urn-ipc-registry.tsindex 424911920..2955ce83f 100644--- a/packages/core/src/handoff/urn-ipc-registry.ts+++ b/packages/core/src/handoff/urn-ipc-registry.ts@@ -63,6 +63,8 @@ export const URN_HTTP_ONLY: ReadonlySet<ProblemType> = new Set<ProblemType>(['urn:ok:error:save-held','urn:ok:error:doc-removed','urn:ok:error:branch-switched',+ 'urn:ok:error:doc-moved',+ 'urn:ok:error:server-stopped','urn:ok:error:doc-in-conflict','urn:ok:error:no-conflict-tracked','urn:ok:error:unresolved-conflict-markers',diff --git a/packages/core/src/schemas/api/_envelope.ts b/packages/core/src/schemas/api/_envelope.tsindex adba83d05..4e13984c0 100644--- a/packages/core/src/schemas/api/_envelope.ts+++ b/packages/core/src/schemas/api/_envelope.ts@@ -87,6 +87,8 @@ export const ProblemTypeSchema = z.enum(['urn:ok:error:save-held','urn:ok:error:doc-removed','urn:ok:error:branch-switched',+ 'urn:ok:error:doc-moved',+ 'urn:ok:error:server-stopped','urn:ok:error:doc-not-found','urn:ok:error:doc-already-exists','urn:ok:error:doc-not-open',diff --git a/packages/server/src/api-agent-write-deferred-store-wait.test.ts b/packages/server/src/api-agent-write-deferred-store-wait.test.tsindex 4fdc4cb17..a33dc7006 100644--- a/packages/server/src/api-agent-write-deferred-store-wait.test.ts+++ b/packages/server/src/api-agent-write-deferred-store-wait.test.ts@@ -10,7 +10,13 @@ import {createApiExtension,createDerivedDocumentIndexApiPortStub,} from './api-extension.test-helper.ts';-import { DocumentDurabilityState, WRITE_WAIT_BUDGET_MS } from './document-durability-state.ts';+import {+ DocumentDurabilityState,+ OK_DOC_REMOVED,+ type RenameCarryAnswer,+ WRITE_WAIT_BUDGET_MS,+ writtenThroughOf,+} from './document-durability-state.ts';interface CapturedResponse {status: number;@@ -252,7 +258,7 @@ describe('agent-write flush: bounded wait for a deferred store', () => {const responding = postAgentWrite(docName);await flushWaiting;await vi.advanceTimersByTimeAsync(WRITE_WAIT_BUDGET_MS - 1);- deferral.settle({ kind: 'discarded' });+ deferral.settle({ kind: 'discarded', cause: { kind: 'branch-switch' } });const response = await responding;expect(response.status).toBe(409);@@ -262,3 +268,118 @@ describe('agent-write flush: bounded wait for a deferred store', () => {expect(unsettledEvents(warn)).toEqual([]);});});++describe('agent-write flush: a document renamed outside the app while the write waits', () => {+ function renameOutsideWithCarry(docName: string, movedTo: string): Promise<RenameCarryAnswer> {+ const carry = durabilityState.beginRenameCarry(docName);+ const document = hocuspocus.documents.get(docName);+ if (!document) throw new Error(`${docName} is not loaded`);+ const carried = writtenThroughOf(document);+ const lifecycle = document.getMap('lifecycle');+ lifecycle.set('status', 'renamed');+ lifecycle.set('newPath', movedTo);+ durabilityState.settleRenameCarry(docName, carried);+ return carry;+ }++ function refusedAsRenamed(docName: string, movedTo: string, carry: Promise<RenameCarryAnswer>) {+ return {+ code: OK_DOC_REMOVED,+ message: `${docName} was renamed to ${movedTo} on disk`,+ removal: { kind: 'renamed' as const, renamedTo: movedTo, carry },+ };+ }++ test('a batch edit the rename carried is reported as moved when an earlier document held the flush', async () => {+ durabilityState.holdStores('held-first');+ const deferral = durabilityState.openDeferredStore('held-first');+ const flushWaiting = whenFlushStartsWaiting();++ const responding = postAgentWriteBatch(['held-first', 'renamed-later']);+ await flushWaiting;+ const carry = renameOutsideWithCarry('renamed-later', 'moved-later');+ durabilityState.recordStoreFailure(+ 'renamed-later',+ refusedAsRenamed('renamed-later', 'moved-later', carry),+ );+ deferral.settle({ kind: 'completed' });+ const response = await responding;++ expect(response.status).toBe(200);+ const { results } = JSON.parse(response.body) as {+ results: Array<{+ docName: string;+ status: string;+ error?: { type?: string; detail?: string };+ }>;+ };+ expect(results[0]?.status).toBe('written');+ expect(results[1]?.error?.type).toBe('urn:ok:error:doc-moved');+ expect(results[1]?.error?.detail).toContain('moved-later');+ });++ test('a deferred store refused as renamed reports a carried edit as moved', async () => {+ const docName = 'renamed-deferred';+ durabilityState.holdStores(docName);+ const deferral = durabilityState.openDeferredStore(docName);+ const flushWaiting = whenFlushStartsWaiting();++ const responding = postAgentWrite(docName);+ await flushWaiting;+ const carry = renameOutsideWithCarry(docName, 'moved-deferred');+ deferral.settle({+ kind: 'failed',+ failure: refusedAsRenamed(docName, 'moved-deferred', carry),+ });+ const response = await responding;++ expect(response.status).toBe(409);+ const body = JSON.parse(response.body) as { type: string; detail: string };+ expect(body.type).toBe('urn:ok:error:doc-moved');+ expect(body.detail).not.toContain('re-apply');+ });++ test('an edit made after the carry took its text is asked to be re-applied', async () => {+ const docName = 'renamed-after';+ await postAgentWrite(docName);+ const carry = renameOutsideWithCarry(docName, 'moved-after');+ durabilityState.holdStores(docName);+ const deferral = durabilityState.openDeferredStore(docName);+ const flushWaiting = whenFlushStartsWaiting();++ const responding = postAgentWrite(docName);+ await flushWaiting;+ deferral.settle({ kind: 'failed', failure: refusedAsRenamed(docName, 'moved-after', carry) });+ const response = await responding;++ expect(response.status).toBe(409);+ const body = JSON.parse(response.body) as { type: string; detail: string };+ expect(body.type).toBe('urn:ok:error:doc-removed');+ expect(body.detail).toContain('re-apply your change there');+ });++ test("a carry still running when the write's wait runs out is acknowledged, never re-applied", async () => {+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });+ vi.spyOn(console, 'warn').mockImplementation(() => {});+ const docName = 'renamed-slow';+ durabilityState.holdStores(docName);+ const deferral = durabilityState.openDeferredStore(docName);+ const flushWaiting = whenFlushStartsWaiting();++ let answered = false;+ const responding = postAgentWrite(docName).then((response) => {+ answered = true;+ return response;+ });+ await flushWaiting;+ const carry = durabilityState.beginRenameCarry(docName);+ deferral.settle({ kind: 'failed', failure: refusedAsRenamed(docName, 'moved-slow', carry) });+ await vi.advanceTimersByTimeAsync(WRITE_WAIT_BUDGET_MS - 1);+ expect(answered).toBe(false);++ await vi.advanceTimersByTimeAsync(1);+ const response = await responding;++ expect(response.status).toBe(200);+ });+});diff --git a/packages/server/src/api-extension.persistence-failure.test.ts b/packages/server/src/api-extension.persistence-failure.test.tsindex e0200e02a..1dc5bd8f9 100644--- a/packages/server/src/api-extension.persistence-failure.test.ts+++ b/packages/server/src/api-extension.persistence-failure.test.ts@@ -2,6 +2,9 @@ import type { ServerResponse } from 'node:http';import { describe, expect, test } from 'vitest';import { respondPersistenceFailure } from './api-extension.ts';import {+ OK_DOC_MOVED,+ OK_DOC_REMOVED,+ OK_SERVER_STOPPED,OK_STORE_DISCARDED,OK_STORE_HELD,OK_STORE_REFUSED,@@ -169,7 +172,7 @@ describe('respondPersistenceFailure: a held save', () => {});describe('respondPersistenceFailure: store discarded by a branch switch', () => {- test('an OK_STORE_DISCARDED failure renders a 409 telling the agent the edit was not saved', () => {+ test('an OK_STORE_DISCARDED failure renders a 409 telling the agent the edit stays in the open document', () => {const { res, writeHeadCalls, endCalls } = makeMockRes();const failure: StoreFailure = {code: OK_STORE_DISCARDED,@@ -181,7 +184,97 @@ describe('respondPersistenceFailure: store discarded by a branch switch', () =>expect(writeHeadCalls[0]?.status).toBe(409);const body = JSON.parse(endCalls[0] ?? '{}') as Record<string, unknown>;expect(body.type).toBe('urn:ok:error:branch-switched');- expect(String(body.title)).toContain('not saved');- expect(String(body.detail)).toContain('Re-read');+ expect(String(body.title)).toContain('kept in the open document');+ expect(String(body.detail)).toContain('do not repeat the edit');+ });+});++describe('respondPersistenceFailure: the save of a document whose file went missing', () => {+ test('a move followed outside the app renders a 409 doc-moved that names the new name', () => {+ const { res, writeHeadCalls, endCalls } = makeMockRes();+ const failure: StoreFailure = {+ code: OK_DOC_MOVED,+ message: 'notes was moved outside the app to archive/notes, and its open document followed',+ removal: { kind: 'renamed', renamedTo: 'archive/notes' },+ };++ respondPersistenceFailure(res, failure, 'agent-write-md');++ expect(writeHeadCalls[0]?.status).toBe(409);+ const body = JSON.parse(endCalls[0] ?? '{}') as Record<string, unknown>;+ expect(body.type).toBe('urn:ok:error:doc-moved');+ expect(String(body.detail)).toContain('archive/notes');+ expect(String(body.detail)).toContain('Do not repeat the edit');+ });++ test('a delete that stood renders a 409 doc-removed saying the edit is in the history', () => {+ const { res, writeHeadCalls, endCalls } = makeMockRes();+ const failure: StoreFailure = {+ code: OK_DOC_REMOVED,+ message: 'notes was deleted outside the app before the edit reached disk',+ removal: { kind: 'deleted-outside' },+ };++ respondPersistenceFailure(res, failure, 'agent-write-md');++ expect(writeHeadCalls[0]?.status).toBe(409);+ const body = JSON.parse(endCalls[0] ?? '{}') as Record<string, unknown>;+ expect(body.type).toBe('urn:ok:error:doc-removed');+ expect(String(body.title)).toContain('deleted outside the app');+ expect(String(body.detail)).toContain('history');+ });++ test('a shutdown while the file was missing renders a 503 server-stopped', () => {+ const { res, writeHeadCalls, endCalls } = makeMockRes();+ const failure: StoreFailure = {+ code: OK_SERVER_STOPPED,+ message: 'The server stopped while the file of notes was missing',+ };++ respondPersistenceFailure(res, failure, 'agent-write-md');++ expect(writeHeadCalls[0]?.status).toBe(503);+ const body = JSON.parse(endCalls[0] ?? '{}') as Record<string, unknown>;+ expect(body.type).toBe('urn:ok:error:server-stopped');+ expect(String(body.detail)).toContain('history');+ });+});++describe('respondPersistenceFailure: a document renamed outside the app', () => {+ test('an OK_DOC_MOVED failure renders doc-moved without the re-apply instruction', () => {+ const { res, writeHeadCalls, endCalls } = makeMockRes();+ respondPersistenceFailure(+ res,+ {+ code: OK_DOC_MOVED,+ message: 'notes was renamed to archive/notes on disk',+ removal: { kind: 'renamed', renamedTo: 'archive/notes' },+ },+ 'agent-write-md',+ );++ expect(writeHeadCalls[0]?.status).toBe(409);+ const body = JSON.parse(endCalls[0] ?? '{}') as Record<string, unknown>;+ expect(body.type).toBe('urn:ok:error:doc-moved');+ expect(String(body.detail)).toContain('Do not repeat the edit');+ expect(String(body.detail)).not.toContain('re-apply');+ });++ test('an OK_DOC_REMOVED renamed failure renders doc-removed asking to re-apply at the new name', () => {+ const { res, writeHeadCalls, endCalls } = makeMockRes();+ respondPersistenceFailure(+ res,+ {+ code: OK_DOC_REMOVED,+ message: 'notes was renamed to archive/notes on disk',+ removal: { kind: 'renamed', renamedTo: 'archive/notes' },+ },+ 'agent-write-md',+ );++ expect(writeHeadCalls[0]?.status).toBe(409);+ const body = JSON.parse(endCalls[0] ?? '{}') as Record<string, unknown>;+ expect(body.type).toBe('urn:ok:error:doc-removed');+ expect(String(body.detail)).toContain('re-apply your change there');});});diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex 6aa0d3ae4..e5004a3a0 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -64,7 +64,6 @@ import {stripFrontmatter,type ValidationDiagnostic,} from '@inkeep/open-knowledge-core';-import { formatRenameSubject } from '@inkeep/open-knowledge-core/shadow-repo-layout';import {parseSkillDir,pluginRepositoryUrl,@@ -226,13 +225,19 @@ import {import type { DocNoticeLedger } from './doc-notices.ts';import {assertNeverDeferredStoreWait,+ type DeferredStoreDiscardCause,type DocumentDurabilityState,+ editWasCarried,+ OK_DOC_MOVED,OK_DOC_REMOVED,OK_PATH_UNRESOLVABLE,+ OK_SERVER_STOPPED,OK_STORE_DISCARDED,OK_STORE_HELD,OK_STORE_REFUSED,type StoreFailure,+ type WrittenThrough,+ writtenThroughOf,} from './document-durability-state.ts';import type { RefreshDocumentsFromDisk } from './document-refresh.ts';import {@@ -368,11 +373,7 @@ import {import { isWithinDir, toPosix } from './path-utils.ts';import { assertProjectContentSubtree } from './project-content-scope.ts';import { isValidRelativeContentPath } from './relative-content-path.ts';-import {- appendRenameLogEntry,- getOrLoadRenameLogIndex,- type RenameLogEntry,-} from './rename-log.ts';+import { followRenameRecords } from './rename-records.ts';import { ServerMutationShuttingDownError } from './server-content-policy.ts';import type { PairedWriteOrigin } from './server-observers.ts';import { createAssetService } from './services/assets.ts';@@ -1441,6 +1442,13 @@ function removedDocProblem(failure: StoreFailure) {title: 'Edit applied in memory; disk write refused because the document was renamed.',detail: `${failure.message}. Retrying will not help: re-read the document at ${failure.removal.renamedTo} and re-apply your change there.`,} satisfies BatchEntryError;+ case 'deleted-outside':+ return {+ type: 'urn:ok:error:doc-removed' as const,+ title:+ 'Edit not saved to disk: the document was deleted outside the app, and the edit went to its history.',+ detail: `${failure.message}. Retrying will not help: the document is closed. Its history (the timeline) has the edit; re-create the document with write if you still want the content.`,+ } satisfies BatchEntryError;case undefined:return {type: 'urn:ok:error:doc-removed' as const,@@ -1451,6 +1459,24 @@ function removedDocProblem(failure: StoreFailure) {}}+function movedDocProblem(failure: StoreFailure) {+ const movedTo = failure.removal?.kind === 'renamed' ? failure.removal.renamedTo : 'its new name';+ return {+ type: 'urn:ok:error:doc-moved' as const,+ title: 'Edit kept: the document was moved outside the app, and the edit moved with it.',+ detail: `${failure.message}. Do not repeat the edit: it is in ${movedTo}, which saves it under that name. Re-read ${movedTo} to confirm.`,+ } satisfies BatchEntryError;+}++function stoppedServerProblem(failure: StoreFailure) {+ return {+ type: 'urn:ok:error:server-stopped' as const,+ title:+ "Edit not saved to disk: the server stopped while the document's file was missing, and the edit went to its history.",+ detail: `${failure.message}. After OpenKnowledge restarts, find the edit in the document's history (the timeline), and re-create the document with write if you still want it.`,+ } satisfies BatchEntryError;+}+function pathFaultProblem(failure: StoreFailure) {return {type: 'urn:ok:error:path-escape' as const,@@ -1460,11 +1486,46 @@ function pathFaultProblem(failure: StoreFailure) {} satisfies BatchEntryError;}+function discardedStoreFailure(docName: string, cause: DeferredStoreDiscardCause): StoreFailure {+ switch (cause.kind) {+ case 'branch-switch':+ return {+ code: OK_STORE_DISCARDED,+ message: `A Git branch switch discarded the pending save of ${docName}`,+ };+ case 'renamed-outside':+ return {+ code: OK_DOC_REMOVED,+ message: `${docName} was moved outside the app to ${cause.to}, and its open document followed`,+ removal: {+ kind: 'renamed',+ renamedTo: cause.to,+ ...(cause.carry ? { carry: cause.carry } : {}),+ },+ };+ case 'deleted-outside':+ return {+ code: OK_DOC_REMOVED,+ message: `${docName} was deleted outside the app before the edit reached disk`,+ removal: { kind: 'deleted-outside' },+ };+ case 'shutdown':+ return {+ code: OK_SERVER_STOPPED,+ message: `The server stopped while the file of ${docName} was missing`,+ };+ default: {+ const unhandled: never = cause;+ throw new Error(`unhandled discard cause: ${JSON.stringify(unhandled)}`);+ }+ }+}+function discardedStoreProblem(failure: StoreFailure) {return {type: 'urn:ok:error:branch-switched' as const,- title: 'Edit not saved: the Git branch changed before it reached disk.',- detail: `${failure.message}. The document now shows the checked-out branch. Re-read it, then repeat the edit if it is still needed.`,+ title: 'Edit kept in the open document: the Git branch changed before it reached disk.',+ detail: `${failure.message}. The edit stays in the open document, merged with the checked-out branch's version of the file, and is saved with the document's next save; do not repeat the edit. Re-read the document to confirm it.`,} satisfies BatchEntryError;}@@ -1560,6 +1621,16 @@ export function respondPersistenceFailure(errorResponse(res, 409, type, title, { handler, detail });return;}+ if (failure.code === OK_DOC_MOVED) {+ const { type, title, detail } = movedDocProblem(failure);+ errorResponse(res, 409, type, title, { handler, detail });+ return;+ }+ if (failure.code === OK_SERVER_STOPPED) {+ const { type, title, detail } = stoppedServerProblem(failure);+ errorResponse(res, 503, type, title, { handler, detail });+ return;+ }if (failure.code === OK_PATH_UNRESOLVABLE) {const { type, title, detail } = pathFaultProblem(failure);errorResponse(res, 400, type, title, { handler, detail });@@ -1680,6 +1751,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {githubReferenceFetch,getConfigDiagnostics,} = options;+ const docNoticeLedger = options.docNotices;const declaredGitHubHosts =options.declaredGitHubHosts ?? readDeclaredGitHubHosts(homeDirOverride);const resolveSyncCredentialConfig =@@ -1993,7 +2065,39 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {| { kind: 'stale-external-write' }| null;- async function flushDiskAndDetectOutcome(docName: string): Promise<FlushOutcome> {+ async function answerForCarriedEdit(+ docName: string,+ failure: StoreFailure,+ writtenThrough: WrittenThrough | undefined,+ ): Promise<FlushOutcome> {+ if (failure.code !== OK_DOC_REMOVED || failure.removal?.kind !== 'renamed') {+ return { kind: 'failure', failure };+ }+ const answer = await durabilityState.awaitRenameCarry(docName, failure.removal.carry);+ if (answer.kind === 'unsettled') {+ log.warn(+ { docName },+ "[agent-write] the rename carry did not settle within the write's wait; acknowledging before it reaches disk",+ );+ return null;+ }+ return {+ kind: 'failure',+ failure: editWasCarried(writtenThrough, answer.carried)+ ? { ...failure, code: OK_DOC_MOVED }+ : failure,+ };+ }++ function writtenThroughOfResident(docName: string): WrittenThrough | undefined {+ const resident = hocuspocus.documents.get(docName);+ return resident ? writtenThroughOf(resident) : undefined;+ }++ async function flushDiskAndDetectOutcome(+ docName: string,+ writtenThrough: WrittenThrough | undefined = writtenThroughOfResident(docName),+ ): Promise<FlushOutcome> {const debounceId = `onStoreDocument-${docName}`;if (hocuspocus.debouncer.isDebounced(debounceId)) {durabilityState.markAgentWriteStore(docName);@@ -2001,23 +2105,17 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {}const deferredWaitStarted = Date.now();const deferredWait = await durabilityState.awaitDeferredStoreOutcome(docName);+ let failure: StoreFailure | undefined;switch (deferredWait?.kind) {case undefined:case 'completed':break;case 'discarded':- return {- kind: 'failure',- failure: {- code: OK_STORE_DISCARDED,- message: `A Git branch switch discarded the pending save of ${docName}`,- },- };+ failure = discardedStoreFailure(docName, deferredWait.cause);+ break;case 'failed':- return {- kind: 'failure',- failure: durabilityState.takeStoreFailure(docName) ?? deferredWait.failure,- };+ failure = durabilityState.takeStoreFailure(docName) ?? deferredWait.failure;+ break;case 'unsettled': {const waitedMs = Date.now() - deferredWaitStarted;console.warn(@@ -2037,8 +2135,8 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {default:assertNeverDeferredStoreWait(deferredWait);}- const failure = durabilityState.takeStoreFailure(docName);- if (failure) return { kind: 'failure', failure };+ failure ??= durabilityState.takeStoreFailure(docName) ?? undefined;+ if (failure) return answerForCarriedEdit(docName, failure, writtenThrough);if (durabilityState.takeStaleExternalWriteFreeze(docName)) {return { kind: 'stale-external-write' };}@@ -3282,7 +3380,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {}const liveContents = await captureAndCloseDocuments([...renameMap.keys()], 'renamed');-if (process.env.NODE_ENV === 'test' &&process.env.OK_TEST_RENAME_FAULT === 'pre-append'@@ -3290,70 +3387,29 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {throw new Error('OK_TEST_RENAME_FAULT=pre-append');}- if (shadowRef?.current) {- const shadow = shadowRef.current;- const loggableAffectedDocs = affectedDocs.filter(- ({ from, to }) => stripDocExtension(from) !== stripDocExtension(to),- );- if (loggableAffectedDocs.length > 0) {- withSpanSync(- 'rename.appendLog',- { attributes: { 'rename.kind': kind } },- (span) => {- const groupId = randomUUID();- const at = new Date().toISOString();- const branch = getCurrentBranch?.() ?? 'main';- const renameLogIndex = getOrLoadRenameLogIndex(shadow.gitDir);- const actorWriter = options?.actor- ? {- writerId: options.actor.writerId,- displayName: options.actor.displayName,- }- : { writerId: SERVICE_WRITER.id, displayName: SERVICE_WRITER.name };- let entriesAppended = 0;- for (const { from, to } of loggableAffectedDocs) {- const logEntry: RenameLogEntry = {- v: 1,- from,- to,- at,- commitSha: '',- branch,- groupId,- kind,- actor: actorWriter,- };- appendRenameLogEntry(shadow.gitDir, logEntry, renameLogIndex, shadow);- entriesAppended += 1;- if (options?.actor) {- recordContributor(- to,- options.actor.writerId,- options.actor.displayName,- options.actor.colorSeed,- formatRenameSubject(from, to),- options.actor.actorMetadata,- undefined,- [{ from, to }],- );- } else {- recordContributor(- to,- SERVICE_WRITER.id,- SERVICE_WRITER.name,- SERVICE_WRITER.id,- formatRenameSubject(from, to),- undefined,- undefined,- [{ from, to }],- );- }+ withSpanSync('rename.appendLog', { attributes: { 'rename.kind': kind } }, (span) => {+ const actor = options?.actor;+ const entriesAppended = followRenameRecords({+ moves: affectedDocs,+ kind,+ branch: getCurrentBranch?.() ?? 'main',+ writer: actor+ ? {+ writerId: actor.writerId,+ displayName: actor.displayName,+ colorSeed: actor.colorSeed,+ actor: actor.actorMetadata,}- span.setAttribute('rename.entries_appended', entriesAppended);- },- );- }- }+ : {+ writerId: SERVICE_WRITER.id,+ displayName: SERVICE_WRITER.name,+ colorSeed: SERVICE_WRITER.id,+ },+ shadow: shadowRef?.current,+ notices: docNoticeLedger,+ });+ span.setAttribute('rename.entries_appended', entriesAppended);+ });const explicitDestExt: string | null =kind === 'file' && isSupportedDocFile(toPath) ? extname(toPath) : null;@@ -3720,6 +3776,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {summaryResponseFields(normalizedSummary);let disposeEffectCapture: (() => void) | undefined;+ let writtenThrough: WrittenThrough | undefined;try {const icon = iconFromClientName(clientName);const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);@@ -3764,6 +3821,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {...(changedBlocks !== undefined ? { changedBlocks } : {}),});}, session.origin);+ writtenThrough = writtenThroughOf(session.dc.document);recordContributor(docName,agentId,@@ -3780,7 +3838,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {agentPresenceBroadcaster?.touchMode(agentId, 'idle');}- const flushOutcome = await flushDiskAndDetectOutcome(docName);+ const flushOutcome = await flushDiskAndDetectOutcome(docName, writtenThrough);if (flushOutcome?.kind === 'failure') {respondPersistenceFailure(res, flushOutcome.failure, 'agent-write');return;@@ -3944,6 +4002,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {const results: (BatchResult | undefined)[] = new Array(body.docs.length);const pending: PendingEntry[] = [];+ const writtenThroughByDoc = new Map<string, WrittenThrough>();try {const icon = iconFromClientName(clientName);@@ -4043,6 +4102,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {...(changedBlocks !== undefined ? { changedBlocks } : {}),});}, session.origin);+ writtenThroughByDoc.set(resolvedDocName, writtenThroughOf(session.dc.document));} finally {disposeEntryEffectCapture();}@@ -4082,7 +4142,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {const flushErrors = new Map<string, BatchErrorResult['error'] | undefined>();for (const p of pending) {if (flushErrors.has(p.docName)) continue;- const flushOutcome = await flushDiskAndDetectOutcome(p.docName);+ const flushOutcome = await flushDiskAndDetectOutcome(+ p.docName,+ writtenThroughByDoc.get(p.docName),+ );if (flushOutcome?.kind === 'failure') {if (flushOutcome.failure.code === OK_DOC_REMOVED) {flushErrors.set(p.docName, removedDocProblem(flushOutcome.failure));@@ -4094,6 +4157,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {flushErrors.set(p.docName, heldSaveProblem(flushOutcome.failure));} else if (flushOutcome.failure.code === OK_STORE_DISCARDED) {flushErrors.set(p.docName, discardedStoreProblem(flushOutcome.failure));+ } else if (flushOutcome.failure.code === OK_DOC_MOVED) {+ flushErrors.set(p.docName, movedDocProblem(flushOutcome.failure));+ } else if (flushOutcome.failure.code === OK_SERVER_STOPPED) {+ flushErrors.set(p.docName, stoppedServerProblem(flushOutcome.failure));} else {const reason = classifyUploadErrno({code: flushOutcome.failure.code,diff --git a/packages/server/src/content-filter.test.ts b/packages/server/src/content-filter.test.tsindex 266431a85..5a9404909 100644--- a/packages/server/src/content-filter.test.ts+++ b/packages/server/src/content-filter.test.ts@@ -19,7 +19,8 @@ import {createContentFilter,createContentFilterAsync,} from './content-filter.ts';-import { installTestLoggers, loggerFactory } from './logger.ts';+import { getLogger, installTestLoggers, loggerFactory } from './logger.ts';+import { getMetrics } from './metrics.ts';describe('ContentFilter', () => {let projectDir: string;@@ -1933,6 +1934,54 @@ describe('ContentFilter', () => {});});+ test.each([+ ['sync', createContentFilter],+ ['async', createContentFilterAsync],+ ] as const)(+ 'a %s filter warns once per in-place skill re-scan fault, says when it clears, and counts every failure',+ async (_label, create) => {+ let failing = false;+ const filter = await create({+ projectDir,+ contentDir: projectDir,+ rescanInPlaceSkillDirs: () => {+ if (failing) throw new Error('scan fault');+ return new Set<string>();+ },+ });+ const log = getLogger('content-filter');+ const warn = vi.spyOn(log, 'warn');+ const info = vi.spyOn(log, 'info');+ try {+ const faultWarnings = () =>+ warn.mock.calls.filter(([, message]) =>+ String(message).startsWith('in-place skill re-scan failed'),+ );+ const clearedNotes = () =>+ info.mock.calls.filter(([, message]) => message === 'in-place skill re-scan works again');+ const before = getMetrics().inPlaceSkillRescanFailures;++ failing = true;+ for (let pass = 0; pass < 3; pass++) filter.refreshInPlaceSkillDirs();+ expect(getMetrics().inPlaceSkillRescanFailures - before).toBe(3);+ expect(faultWarnings()).toHaveLength(1);++ failing = false;+ filter.refreshInPlaceSkillDirs();+ filter.refreshInPlaceSkillDirs();+ expect(clearedNotes()).toHaveLength(1);++ failing = true;+ filter.refreshInPlaceSkillDirs();+ expect(faultWarnings()).toHaveLength(2);+ expect(getMetrics().inPlaceSkillRescanFailures - before).toBe(4);+ } finally {+ warn.mockRestore();+ info.mockRestore();+ }+ },+ );+describe('rebuildIgnorePatterns', () => {test('concurrent rebuild calls coalesce into one flight plus one trailing run', async () => {let scans = 0;diff --git a/packages/server/src/content-filter.ts b/packages/server/src/content-filter.tsindex 4646413a3..59469c0d9 100644--- a/packages/server/src/content-filter.ts+++ b/packages/server/src/content-filter.ts@@ -18,6 +18,7 @@ import { withHiddenWindowsConsole } from './child-process-windows-hide.ts';import { isSupportedDocFile, stripDocExtension } from './doc-extensions.ts';import { isProjectRoot } from './fs/find-project-root.ts';import { getLogger } from './logger.ts';+import { incrementInPlaceSkillRescanFailures } from './metrics.ts';import { toPosix } from './path-utils.ts';import { withSpan } from './telemetry.ts';@@ -648,9 +649,30 @@ export interface ContentFilter {peekFreshInPlaceSkillDirsFingerprint(): string;}+function createSkillRescanReporter(): { failed(err: unknown): void; succeeded(): void } {+ let faulted = false;+ return {+ failed(err) {+ incrementInPlaceSkillRescanFailures();+ if (faulted) return;+ faulted = true;+ log.warn(+ { err },+ 'in-place skill re-scan failed; the previous allow-list stays until a re-scan succeeds, and further failures are only counted',+ );+ },+ succeeded() {+ if (!faulted) return;+ faulted = false;+ log.info({}, 'in-place skill re-scan works again');+ },+ };+}+export function createContentFilter(opts: ContentFilterOptions): ContentFilter {const { projectDir, contentDir, onAfterRebuild, singleDocRelPath } = opts;let inPlaceSkillDirs: ReadonlySet<string> = opts.inPlaceSkillDirs ?? new Set();+ const skillRescan = createSkillRescanReporter();let configuredAttachmentFolder = attachmentFolderShape(opts.attachmentFolderPath ?? DEFAULT_ATTACHMENT_FOLDER_PATH,);@@ -980,8 +1002,9 @@ export function createContentFilter(opts: ContentFilterOptions): ContentFilter {if (!opts.rescanInPlaceSkillDirs) return;try {inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);+ skillRescan.succeeded();} catch (err) {- log.warn({ err }, 'in-place skill re-scan failed — keeping previous allow-list');+ skillRescan.failed(err);}},@@ -1010,8 +1033,9 @@ export function createContentFilter(opts: ContentFilterOptions): ContentFilter {if (opts.rescanInPlaceSkillDirs) {try {inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);+ skillRescan.succeeded();} catch (err) {- log.warn({ err }, 'in-place skill re-scan failed — keeping previous allow-list');+ skillRescan.failed(err);}}@@ -1313,6 +1337,7 @@ async function initContentDirStateAsync(export async function createContentFilterAsync(opts: ContentFilterOptions): Promise<ContentFilter> {const { projectDir, contentDir, onAfterRebuild, singleDocRelPath } = opts;let inPlaceSkillDirs: ReadonlySet<string> = opts.inPlaceSkillDirs ?? new Set();+ const skillRescan = createSkillRescanReporter();let configuredAttachmentFolder = attachmentFolderShape(opts.attachmentFolderPath ?? DEFAULT_ATTACHMENT_FOLDER_PATH,);@@ -1604,8 +1629,9 @@ export async function createContentFilterAsync(opts: ContentFilterOptions): Promif (!opts.rescanInPlaceSkillDirs) return;try {inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);+ skillRescan.succeeded();} catch (err) {- log.warn({ err }, 'in-place skill re-scan failed — keeping previous allow-list');+ skillRescan.failed(err);}},@@ -1634,8 +1660,9 @@ export async function createContentFilterAsync(opts: ContentFilterOptions): Promif (opts.rescanInPlaceSkillDirs) {try {inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);+ skillRescan.succeeded();} catch (err) {- log.warn({ err }, 'in-place skill re-scan failed — keeping previous allow-list');+ skillRescan.failed(err);}}const prevIg = ig;diff --git a/packages/server/src/doc-notices.test.ts b/packages/server/src/doc-notices.test.tsindex 19fd23fc6..0c1325451 100644--- a/packages/server/src/doc-notices.test.ts+++ b/packages/server/src/doc-notices.test.ts@@ -6,7 +6,7 @@ import simpleGit from 'simple-git';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import { configureTestGitRepository } from '../../../test-support/configure-git-fixture.test-helper.ts';import { _resetDocExtensionsForTests, registerDocExtension } from './doc-extensions.ts';-import { DocNoticeLedger, docNoticesPath } from './doc-notices.ts';+import { DocNoticeLedger, docNoticesPath, NOTICE_WITHDRAW_AFTER_MS } from './doc-notices.ts';import { createMergeHistoryRecorder } from './merge-history.ts';import {DEFAULT_CHECKPOINT_RETENTION,@@ -21,9 +21,14 @@ describe('DocNoticeLedger', () => {let projectDir: string;let signal: ReturnType<typeof vi.fn<() => void>>;+ let clock = 0;+ let held = new Set<string>();+beforeEach(() => {projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-doc-notices-')));signal = vi.fn<() => void>();+ clock = 0;+ held = new Set();});afterEach(() => {@@ -44,6 +49,8 @@ describe('DocNoticeLedger', () => {getShadow: () => options.shadow,isReady: () => options.ready ?? true,signal,+ isHeld: (docName) => held.has(docName),+ now: () => clock,});}@@ -132,7 +139,7 @@ describe('DocNoticeLedger', () => {expect(signal).not.toHaveBeenCalled();});- test('a notice for a document whose file is gone is withdrawn', async () => {+ test('a notice is withdrawn once its file has been missing on reads ten seconds apart', async () => {seedDoc('notes');seedDoc('folder/kept');const notices = ledger();@@ -141,10 +148,66 @@ describe('DocNoticeLedger', () => {rmSync(join(projectDir, 'notes.md'));- expect((await notices.list('main')).map((notice) => notice.docName)).toEqual(['folder/kept']);+ const listed = async () => (await notices.list('main')).map((notice) => notice.docName);+ expect(await listed()).toEqual(['folder/kept', 'notes']);+ expect(await listed()).toEqual(['folder/kept', 'notes']);+ clock += NOTICE_WITHDRAW_AFTER_MS - 1;+ expect(await listed()).toEqual(['folder/kept', 'notes']);+ clock += 1;+ expect(await listed()).toEqual(['folder/kept']);expect((await ledger().list('main')).map((notice) => notice.docName)).toEqual(['folder/kept']);});+ test('a notice whose document the server holds as vanished is not withdrawn', async () => {+ seedDoc('notes');+ const notices = ledger();+ notices.record('notes', 'main', { kind: 'both-kept', kept: KEPT_ONE });+ rmSync(join(projectDir, 'notes.md'));+ held.add('notes');++ const listed = async () => (await notices.list('main')).map((notice) => notice.docName);+ expect(await listed()).toEqual(['notes']);+ clock += NOTICE_WITHDRAW_AFTER_MS * 3;+ expect(await listed()).toEqual(['notes']);++ held.delete('notes');+ expect(await listed()).toEqual(['notes']);+ clock += NOTICE_WITHDRAW_AFTER_MS;+ expect(await listed()).toEqual([]);+ });++ test('a file missing for one read, as during a save that deletes then writes, keeps its notice', async () => {+ seedDoc('notes');+ const notices = ledger();+ notices.record('notes', 'main', { kind: 'both-kept', kept: KEPT_ONE });++ rmSync(join(projectDir, 'notes.md'));+ expect((await notices.list('main')).map((notice) => notice.docName)).toEqual(['notes']);+ seedDoc('notes');+ expect((await notices.list('main')).map((notice) => notice.docName)).toEqual(['notes']);+ rmSync(join(projectDir, 'notes.md'));+ clock += NOTICE_WITHDRAW_AFTER_MS;+ expect((await notices.list('main')).map((notice) => notice.docName)).toEqual(['notes']);+ });++ test('a renamed document keeps its notice under the new name and file', async () => {+ seedDoc('notes');+ const notices = ledger();+ const id = notices.record('notes', 'main', { kind: 'both-kept', kept: KEPT_ONE });+ rmSync(join(projectDir, 'notes.md'));+ seedDoc('archive/notes');++ notices.rename('notes', 'archive/notes', 'main', 'archive/notes.md');++ const listed = await notices.list('main');+ expect(listed).toEqual([+ expect.objectContaining({ id, docName: 'archive/notes', file: 'archive/notes.md' }),+ ]);+ expect((await ledger().list('main')).map((notice) => notice.docName)).toEqual([+ 'archive/notes',+ ]);+ });+test('a notice for an .mdx document keeps its file name and survives a restart before the extensions are known again', async () => {seedDoc('guide', '.mdx');registerDocExtension('guide', '.mdx');@@ -165,7 +228,10 @@ describe('DocNoticeLedger', () => {rmSync(join(projectDir, 'notes.md'));expect((await ledger({ ready: false }).list('main')).map((n) => n.docName)).toEqual(['notes']);- expect((await ledger().list('main')).map((n) => n.docName)).toEqual([]);+ const ready = ledger();+ expect((await ready.list('main')).map((n) => n.docName)).toEqual(['notes']);+ clock += NOTICE_WITHDRAW_AFTER_MS;+ expect((await ready.list('main')).map((n) => n.docName)).toEqual([]);});test('every change tells the app to refetch, and a read that changes nothing does not', async () => {diff --git a/packages/server/src/doc-notices.ts b/packages/server/src/doc-notices.tsindex 5842e43c5..8abe0ed67 100644--- a/packages/server/src/doc-notices.ts+++ b/packages/server/src/doc-notices.ts@@ -1,12 +1,13 @@import { randomUUID } from 'node:crypto';-import { existsSync, readFileSync } from 'node:fs';-import { dirname, join } from 'node:path';+import { existsSync, readFileSync, statSync } from 'node:fs';+import { dirname, extname, join } from 'node:path';import { type DocNoticeWire, DocNoticeWireSchema } from '@inkeep/open-knowledge-core';import { z } from 'zod';import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';import { getLocalDir } from './config/paths.ts';import { docNameToRelativePath } from './doc-extensions.ts';import { tracedMkdirSync, tracedRenameSync, tracedWriteFileSync } from './fs-traced.ts';+import { errnoCode } from './http/handler-utils.ts';import { getLogger } from './logger.ts';import { type ShadowHandle, shadowGit } from './shadow-repo.ts';@@ -15,6 +16,7 @@ const log = getLogger('doc-notices');const DOC_NOTICES_FILENAME = 'doc-notices.json';const DOC_NOTICES_VERSION = 1;const MAX_NOTICES = 200;+export const NOTICE_WITHDRAW_AFTER_MS = 10_000;const MAX_ENTRIES_PER_NOTICE = 8;type BothKeptNotice = Extract<DocNoticeWire, { kind: 'both-kept' }>;@@ -40,6 +42,8 @@ export interface DocNoticeLedgerOptions {getShadow: () => ShadowHandle | null | undefined;isReady: () => boolean;signal: () => void;+ isHeld?: (docName: string) => boolean;+ now?: () => number;}const StoredNoticeSchema = z.object({@@ -69,6 +73,7 @@ export class DocNoticeLedger implements DocNoticeSink {private readonly options: DocNoticeLedgerOptions;private readonly storePath: string;private readonly byKey = new Map<string, StoredNotice>();+ private readonly missingSince = new Map<string, number>();constructor(options: DocNoticeLedgerOptions) {this.options = options;@@ -98,6 +103,7 @@ export class DocNoticeLedger implements DocNoticeSink {? { ...common, kind: 'both-kept', kept: event.kept }: { ...common, kind: 'moved-to-history', side: event.side, reason: event.reason };this.byKey.delete(key);+ this.missingSince.delete(key);this.byKey.set(key, { branch, notice });for (const oldest of this.byKey.keys()) {if (this.byKey.size <= MAX_NOTICES) break;@@ -122,6 +128,31 @@ export class DocNoticeLedger implements DocNoticeSink {}}+ rename(oldDocName: string, newDocName: string, branch: string, newFile?: string): void {+ if (!isNoticeDoc(oldDocName) || !isNoticeDoc(newDocName)) return;+ const oldKey = keyOf(branch, oldDocName);+ const stored = this.byKey.get(oldKey);+ if (!stored) return;+ this.byKey.delete(oldKey);+ this.missingSince.delete(oldKey);+ const newKey = keyOf(branch, newDocName);+ this.byKey.delete(newKey);+ this.missingSince.delete(newKey);+ this.byKey.set(newKey, {+ branch,+ notice: {+ ...stored.notice,+ docName: newDocName,+ file: newFile ?? `${newDocName}${extname(stored.notice.file)}`,+ },+ });+ log.info(+ { docName: newDocName, from: oldDocName, branch },+ `[doc-notices] notice followed a rename: ${oldDocName} -> ${newDocName}`,+ );+ this.commit();+ }+async list(branch: string): Promise<DocNoticeWire[]> {if (this.options.isReady()) await this.withdrawStale(branch);return [...this.byKey.values()]@@ -132,7 +163,18 @@ export class DocNoticeLedger implements DocNoticeSink {private async withdrawStale(branch: string): Promise<void> {const onBranch = [...this.byKey].filter(([, stored]) => stored.branch === branch);- const gone = onBranch.filter(([, stored]) => !this.fileExists(stored.notice.file));+ const gone: Array<[string, StoredNotice]> = [];+ const now = this.options.now?.() ?? Date.now();+ for (const [key, stored] of onBranch) {+ const presence = this.filePresence(stored.notice.file);+ if (presence === 'present' || this.options.isHeld?.(stored.notice.docName) === true) {+ this.missingSince.delete(key);+ } else if (presence === 'missing') {+ const since = this.missingSince.get(key);+ if (since === undefined) this.missingSince.set(key, now);+ else if (now - since >= NOTICE_WITHDRAW_AFTER_MS) gone.push([key, stored]);+ }+ }const left = await this.versionsLeftHistory(branch,onBranch.filter(([key]) => !gone.some(([goneKey]) => goneKey === key)),@@ -140,6 +182,7 @@ export class DocNoticeLedger implements DocNoticeSink {const removed = [...gone, ...left].filter(([key, stored]) => this.byKey.get(key) === stored);for (const [key, stored] of removed) {this.byKey.delete(key);+ this.missingSince.delete(key);log.info({ docName: stored.notice.docName, branch },`[doc-notices] notice withdrawn: ${stored.notice.docName}`,@@ -153,6 +196,7 @@ export class DocNoticeLedger implements DocNoticeSink {for (const [key, stored] of this.byKey) {if (stored.notice.docName !== docName || stored.notice.id !== id) continue;this.byKey.delete(key);+ this.missingSince.delete(key);log.info({ docName }, `[doc-notices] notice dismissed: ${docName}`);this.commit();return true;@@ -160,8 +204,16 @@ export class DocNoticeLedger implements DocNoticeSink {return false;}- private fileExists(file: string): boolean {- return existsSync(join(this.options.contentDir, file));+ private filePresence(file: string): 'present' | 'missing' | 'unknown' {+ try {+ statSync(join(this.options.contentDir, file));+ return 'present';+ } catch (err) {+ const code = errnoCode(err);+ if (code === 'ENOENT' || code === 'ENOTDIR') return 'missing';+ log.warn({ err, code }, '[doc-notices] could not check a notice file; notice kept');+ return 'unknown';+ }}private async versionsLeftHistory(diff --git a/packages/server/src/document-durability-state.test.ts b/packages/server/src/document-durability-state.test.tsindex fb23e7c2f..413fad837 100644--- a/packages/server/src/document-durability-state.test.ts+++ b/packages/server/src/document-durability-state.test.ts@@ -13,6 +13,7 @@ import {import { tmpdir } from 'node:os';import { join } from 'node:path';import { describe, expect, test, vi } from 'vitest';+import * as Y from 'yjs';import { DiskReceiptLog } from './disk-receipts.ts';import {_resetDocExtensionsForTests,@@ -25,8 +26,10 @@ import {DISPLACED_VERSION_TTL_MS,DocumentDurabilityState,DocumentDurabilityStateError,+ editWasCarried,type StorePublishOutcome,WRITE_WAIT_BUDGET_MS,+ writtenThroughOf,} from './document-durability-state.ts';import * as tracedFs from './fs-traced.ts';import { getLogger } from './logger.ts';@@ -45,28 +48,52 @@ describe('DocumentDurabilityState', () => {expect(state.takeStoreFailure('doc')).toBeNull();});- test('retains reconciled bases independently for each visited branch', () => {+ test('a batch held by two owners lasts until both release it, and only the last release ends it', () => {+ const state = new DocumentDurabilityState();+ state.holdBatch('head-watcher');+ state.holdBatch('sync-engine');+ state.holdBatch('sync-engine');++ expect(state.releaseBatch('conflict-resolve')).toBe(false);+ expect(state.isBatchInProgress()).toBe(true);+ expect(state.releaseBatch('sync-engine')).toBe(false);+ expect(state.isBatchInProgress()).toBe(true);+ expect(state.releaseBatch('head-watcher')).toBe(true);+ expect(state.isBatchInProgress()).toBe(false);+ expect(state.releaseBatch('head-watcher')).toBe(false);+ });++ test('keeps one reconciled base across branch switches, the bytes last agreed with disk', () => {const state = new DocumentDurabilityState();state.setReconciledBase('doc', 'main bytes');state.switchReconciledBaseScope('feature');- state.setReconciledBase('doc', 'feature bytes');+ expect(state.getReconciledBase('doc')).toBe('main bytes');- expect(state.getReconciledBase('doc')).toBe('feature bytes');+ state.setReconciledBase('doc', 'feature bytes');state.switchReconciledBaseScope('main');- expect(state.getReconciledBase('doc')).toBe('main bytes');+ expect(state.getReconciledBase('doc')).toBe('feature bytes');});- test('deletes a reconciled base only from the active branch', () => {+ test('a base deleted on one branch stays deleted after a switch', () => {const state = new DocumentDurabilityState();state.setReconciledBase('doc', 'main bytes');state.switchReconciledBaseScope('feature');- state.setReconciledBase('doc', 'feature bytes');+ state.deleteReconciledBase('doc');state.switchReconciledBaseScope('main');- state.deleteReconciledBase('doc');expect(state.getReconciledBase('doc')).toBeUndefined();+ });++ test('a document with a stale external write on the target branch keeps that branch base', () => {+ const state = new DocumentDurabilityState();state.switchReconciledBaseScope('feature');- expect(state.getReconciledBase('doc')).toBe('feature bytes');+ state.setReconciledBase('doc', 'feature acknowledged');+ state.recordStaleExternalWrite('doc', 'stale bytes');+ state.switchReconciledBaseScope('main');+ state.setReconciledBase('doc', 'main bytes');++ state.switchReconciledBaseScope('feature');+ expect(state.getReconciledBase('doc')).toBe('feature acknowledged');});test('isolates every owned coordination channel between instances', async () => {@@ -1544,3 +1571,108 @@ describe('the durable receipt follows the acknowledged base', () => {expect(state.getReceipt('loaded')?.hash).toBe(contentHash('v1\n'));});});++describe('which edits a rename outside the app carried to the new name', () => {+ function frozenDocWithCarriedAndLaterEdit() {+ const document = new Y.Doc();+ const source = document.getText('source');+ source.insert(0, 'Before the move.\n');+ const carriedEdit = writtenThroughOf(document);+ const carried = writtenThroughOf(document);+ source.insert(source.length, 'After the move.\n');+ const laterEdit = writtenThroughOf(document);+ return { carriedEdit, carried, laterEdit };+ }++ test('an edit the carry included is carried, and an edit made after it is not', () => {+ const { carriedEdit, carried, laterEdit } = frozenDocWithCarriedAndLaterEdit();+ expect(editWasCarried(carriedEdit, carried)).toBe(true);+ expect(editWasCarried(laterEdit, carried)).toBe(false);+ expect(editWasCarried(carriedEdit, null)).toBe(false);+ expect(editWasCarried(undefined, carried)).toBe(false);+ expect(editWasCarried({ ...carriedEdit, clientId: carriedEdit.clientId + 1 }, carried)).toBe(+ false,+ );+ });++ test('a write refused while the carry runs waits for it, and a failed carry answers not carried', async () => {+ const state = new DocumentDurabilityState();+ const { carried } = frozenDocWithCarriedAndLaterEdit();+ const carry = state.beginRenameCarry('notes');+ let answered = false;+ const answer = state.awaitRenameCarry('notes', carry).then((value) => {+ answered = true;+ return value;+ });+ await Promise.resolve();+ expect(answered).toBe(false);+ state.settleRenameCarry('notes', null);+ expect(await answer).toEqual({ kind: 'settled', carried: null });++ const archive = state.beginRenameCarry('archive');+ const carriedAnswer = state.awaitRenameCarry('archive', archive);+ state.settleRenameCarry('archive', carried);+ expect(await carriedAnswer).toEqual({ kind: 'settled', carried });+ expect(await state.awaitRenameCarry('archive', state.renameCarryOf('archive'))).toEqual({+ kind: 'settled',+ carried,+ });+ });++ test('a route that begins a carry and never reaches it answers not carried', async () => {+ const state = new DocumentDurabilityState();+ const carry = state.beginRenameCarry('notes');+ expect(state.beginRenameCarry('notes')).toBe(carry);+ state.abandonRenameCarry('notes');+ expect(await carry).toEqual({ kind: 'settled', carried: null });+ });++ test('a revive while the carry runs still answers the waiting write, and the late settle leaves no record', async () => {+ const state = new DocumentDurabilityState();+ const { carried } = frozenDocWithCarriedAndLaterEdit();+ const carry = state.beginRenameCarry('notes');+ state.endRenameCarry('notes');+ state.settleRenameCarry('notes', carried);+ expect(await carry).toEqual({ kind: 'settled', carried });+ expect(state.renameCarryOf('notes')).toBeUndefined();++ state.beginRenameCarry('archive');+ state.settleRenameCarry('archive', carried);+ state.endRenameCarry('archive');+ expect(state.renameCarryOf('archive')).toBeUndefined();+ state.settleRenameCarry('archive', carried);+ expect(state.renameCarryOf('archive')).toBeUndefined();+ });++ test('ending every record at shutdown answers a waiting write as unsettled and leaves none', async () => {+ const state = new DocumentDurabilityState();+ const { carried } = frozenDocWithCarriedAndLaterEdit();+ const pending = state.beginRenameCarry('notes');+ state.beginRenameCarry('archive');+ state.settleRenameCarry('archive', carried);+ state.endAllRenameCarries();+ expect(await pending).toEqual({ kind: 'unsettled' });+ expect(state.renameCarryOf('notes')).toBeUndefined();+ expect(state.renameCarryOf('archive')).toBeUndefined();+ });++ test("a carry that outlasts the write's remaining wait answers unsettled, never not carried", async () => {+ const state = new DocumentDurabilityState();+ const carry = state.beginRenameCarry('notes');+ const warn = vi+ .spyOn(getLogger('document-durability-state'), 'warn')+ .mockImplementation(() => {});+ try {+ const started = Date.now();+ const answer = await state.runWithinWriteWaitBudget(+ () => state.awaitRenameCarry('notes', carry),+ 20,+ );+ expect(answer).toEqual({ kind: 'unsettled' });+ expect(Date.now() - started).toBeLessThan(WRITE_WAIT_BUDGET_MS);+ expect(warn).toHaveBeenCalledOnce();+ } finally {+ warn.mockRestore();+ }+ });+});diff --git a/packages/server/src/document-durability-state.ts b/packages/server/src/document-durability-state.tsindex 38d831fae..f02381c51 100644--- a/packages/server/src/document-durability-state.ts+++ b/packages/server/src/document-durability-state.ts@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';import { dirname } from 'node:path';import { currentCliCommandName } from '@inkeep/open-knowledge-core';import { atomicTempPath } from '@inkeep/open-knowledge-core/server';+import { type Doc, getState } from 'yjs';import { type DiskReceipt, DiskReceiptLog, type FileObservation } from './disk-receipts.ts';import {tracedMkdirSync,@@ -20,6 +21,39 @@ import {} from './metrics.ts';import { contentHash } from './version-hash.ts';+export interface WrittenThrough {+ readonly clientId: number;+ readonly clock: number;+}++export function writtenThroughOf(document: Doc): WrittenThrough {+ return { clientId: document.clientID, clock: getState(document.store, document.clientID) };+}++export function editWasCarried(+ write: WrittenThrough | undefined,+ carried: WrittenThrough | null,+): boolean {+ return (+ write !== undefined &&+ carried !== null &&+ write.clientId === carried.clientId &&+ write.clock <= carried.clock+ );+}++export type RenameCarryAnswer =+ | { readonly kind: 'settled'; readonly carried: WrittenThrough | null }+ | { readonly kind: 'unsettled' };++type RenameCarry =+ | {+ readonly state: 'pending';+ ended: boolean;+ readonly answer: PromiseWithResolvers<RenameCarryAnswer>;+ }+ | { readonly state: 'settled'; readonly carried: WrittenThrough | null };+export interface StoreFailure {code?: string;message: string;@@ -32,8 +66,9 @@ export interface StoreFailure {}export type StoreFailureRemoval =- | { kind: 'renamed'; renamedTo: string }- | { kind: 'path-occupied' };+ | { kind: 'renamed'; renamedTo: string; carry?: Promise<RenameCarryAnswer> }+ | { kind: 'path-occupied' }+ | { kind: 'deleted-outside' };export interface StoreAttemptToken {readonly docName: string;@@ -42,10 +77,20 @@ export interface StoreAttemptToken {export type StorePublishOutcome = 'published' | 'stale' | 'reentrant';+export type DeferredStoreDiscardCause =+ | { readonly kind: 'branch-switch' }+ | {+ readonly kind: 'renamed-outside';+ readonly to: string;+ readonly carry?: Promise<RenameCarryAnswer>;+ }+ | { readonly kind: 'deleted-outside' }+ | { readonly kind: 'shutdown' };+export type DeferredStoreOutcome =| { readonly kind: 'completed' }| { readonly kind: 'failed'; readonly failure: StoreFailure }- | { readonly kind: 'discarded' };+ | { readonly kind: 'discarded'; readonly cause: DeferredStoreDiscardCause };export type DeferredStoreWait = DeferredStoreOutcome | { readonly kind: 'unsettled' };@@ -66,6 +111,8 @@ export const OK_PATH_UNRESOLVABLE = 'OK_PATH_UNRESOLVABLE';export const OK_STORE_REFUSED = 'OK_STORE_REFUSED';export const OK_STORE_HELD = 'OK_STORE_HELD';export const OK_STORE_DISCARDED = 'OK_STORE_DISCARDED';+export const OK_DOC_MOVED = 'OK_DOC_MOVED';+export const OK_SERVER_STOPPED = 'OK_SERVER_STOPPED';const IN_FLIGHT_FLUSH_TTL_MS = 60_000;@@ -306,6 +353,9 @@ export class DocumentDurabilityState {private nextDisplacedExpiryAt = Number.POSITIVE_INFINITY;private activeBranch: string;private batchInProgress = false;+ private readonly batchHolders = new Set<string>();+ private readonly heldStores = new Set<string>();+ private readonly renameCarries = new Map<string, RenameCarry>();private writeAdmissionHolds = 0;private readonly writeAdmissionWaiters = new Set<() => void>();private readonly writeWaitDeadline = new AsyncLocalStorage<number>();@@ -325,10 +375,20 @@ export class DocumentDurabilityState {switchReconciledBaseScope(branch: string): void {this.persist();- this.activeBranch = branch;- if (!this.reconciledBaseByBranch.has(branch)) {- this.reconciledBaseByBranch.set(branch, new Map());+ const carried = new Map(this.reconciledBaseByBranch.get(this.activeBranch) ?? []);+ const target = this.reconciledBaseByBranch.get(branch);+ if (target) {+ const branchScoped = new Set([+ ...(this.displacedVersionsByBranch.get(branch)?.keys() ?? []),+ ...(this.staleExternalWritesByBranch.get(branch)?.keys() ?? []),+ ]);+ for (const docName of branchScoped) {+ const own = target.get(docName);+ if (own !== undefined) carried.set(docName, own);+ }}+ this.activeBranch = branch;+ this.reconciledBaseByBranch.set(branch, carried);}getActiveBranch(): string {@@ -886,6 +946,97 @@ export class DocumentDurabilityState {}}+ holdStores(docName: string): void {+ this.heldStores.add(docName);+ }++ releaseStores(docName: string): void {+ this.heldStores.delete(docName);+ }++ areStoresHeld(docName: string): boolean {+ return this.heldStores.has(docName);+ }++ beginRenameCarry(docName: string): Promise<RenameCarryAnswer> {+ const current = this.renameCarries.get(docName);+ if (current?.state === 'pending') {+ current.ended = false;+ return current.answer.promise;+ }+ const answer = Promise.withResolvers<RenameCarryAnswer>();+ this.renameCarries.set(docName, { state: 'pending', ended: false, answer });+ return answer.promise;+ }++ renameCarryOf(docName: string): Promise<RenameCarryAnswer> | undefined {+ const current = this.renameCarries.get(docName);+ if (current === undefined) return undefined;+ return current.state === 'pending'+ ? current.answer.promise+ : Promise.resolve({ kind: 'settled', carried: current.carried });+ }++ settleRenameCarry(docName: string, carried: WrittenThrough | null): void {+ const current = this.renameCarries.get(docName);+ if (current?.state !== 'pending') return;+ current.answer.resolve({ kind: 'settled', carried });+ if (current.ended) this.renameCarries.delete(docName);+ else this.renameCarries.set(docName, { state: 'settled', carried });+ }++ abandonRenameCarry(docName: string): void {+ this.settleRenameCarry(docName, null);+ }++ endRenameCarry(docName: string): void {+ const current = this.renameCarries.get(docName);+ if (current?.state === 'pending') current.ended = true;+ else this.renameCarries.delete(docName);+ }++ endAllRenameCarries(): void {+ for (const current of this.renameCarries.values()) {+ if (current.state === 'pending') current.answer.resolve({ kind: 'unsettled' });+ }+ this.renameCarries.clear();+ }++ async awaitRenameCarry(+ docName: string,+ carry: Promise<RenameCarryAnswer> | undefined,+ timeoutMs = WRITE_WAIT_BUDGET_MS,+ ): Promise<RenameCarryAnswer> {+ if (carry === undefined) return { kind: 'settled', carried: null };+ const bound = this.remainingWriteWait(timeoutMs);+ let timer: ReturnType<typeof setTimeout> | undefined;+ const expired = new Promise<'expired'>((resolve) => {+ timer = setTimeout(() => resolve('expired'), bound);+ });+ try {+ const answer = await Promise.race([carry, expired]);+ if (answer !== 'expired') return answer;+ getLogger('document-durability-state').warn(+ { docName, waitedMs: bound },+ `[durability] the rename carry of ${docName} did not settle within the write's wait; the wait expired`,+ );+ return { kind: 'unsettled' };+ } finally {+ clearTimeout(timer);+ }+ }++ holdBatch(owner: string): void {+ this.batchHolders.add(owner);+ this.batchInProgress = true;+ }++ releaseBatch(owner: string): boolean {+ if (!this.batchHolders.delete(owner) || this.batchHolders.size > 0) return false;+ this.batchInProgress = false;+ return true;+ }+setBatchInProgress(value: boolean): void {this.batchInProgress = value;}@@ -964,7 +1115,8 @@ export class DocumentDurabilityState {timeoutMs = WRITE_WAIT_BUDGET_MS,): Promise<DeferredStoreWait | undefined> {const pending = this.deferredStoreOutcomes.get(docName);- if (pending === undefined || !this.isWriteAdmissionHeld()) return undefined;+ if (pending === undefined) return undefined;+ if (!this.isWriteAdmissionHeld() && !this.heldStores.has(docName)) return undefined;const unsettled = { kind: 'unsettled' } as const;const bound = this.remainingWriteWait(timeoutMs);if (bound === 0) return unsettled;diff --git a/packages/server/src/external-change.ts b/packages/server/src/external-change.tsindex eeebd3511..139cd780a 100644--- a/packages/server/src/external-change.ts+++ b/packages/server/src/external-change.ts@@ -193,6 +193,7 @@ export function reviveFrozenResidentDoc(}lifecycle.delete('status');lifecycle.delete('newPath');+ durabilityState.endRenameCarry(docName);getLogger('reconcile').info({ docName, status, replacedInMemoryContent },`[reconcile] revived ${docName}: its name is occupied on disk again, so the ${status} freeze no longer applies`,diff --git a/packages/server/src/file-watcher-freshness.test.ts b/packages/server/src/file-watcher-freshness.test.tsindex be1ca6747..125137527 100644--- a/packages/server/src/file-watcher-freshness.test.ts+++ b/packages/server/src/file-watcher-freshness.test.ts@@ -159,7 +159,7 @@ describe('timed freshness re-check', () => {async function watch(freshnessIntervalMs?: number | null,- extra: Pick<StartWatcherOptions, 'onRecoveryComplete'> = {},+ extra: Pick<StartWatcherOptions, 'onRecoveryComplete' | 'onRecoveryPassCompleted'> = {},): Promise<WatcherHandle> {double = createWatcherDouble();handle = await startWatcher(@@ -606,6 +606,43 @@ describe('timed freshness re-check', () => {},);+ test.runIf(CAN_REVOKE_READ)(+ 'the per-pass hook says whether a completed pass observed the whole tree',+ async () => {+ writeFileSync(join(contentDir, 'open.md'), '# Open\n');+ const passes: Array<{ pass: number; whole: boolean }> = [];+ await watch(null, {+ onRecoveryPassCompleted: async (pass, whole) => {+ passes.push({ pass, whole });+ },+ });++ await (handle as WatcherHandle).recheck();+ expect(passes.at(-1)?.whole).toBe(true);++ mkdirSync(join(contentDir, 'locked'));+ revokeRead(join(contentDir, 'locked'));+ await (handle as WatcherHandle).recheck();+ expect(passes.at(-1)?.whole).toBe(false);+ },+ );++ test('a pass that cannot read the content root reports no completed pass', async () => {+ writeFileSync(join(contentDir, 'kept.md'), '# Kept\n');+ const passes: number[] = [];+ await watch(null, {+ onRecoveryPassCompleted: async (pass) => {+ passes.push(pass);+ },+ });+ const before = passes.length;++ rmSync(contentDir, { recursive: true, force: true });+ const result = await (handle as WatcherHandle).recheck();+ expect(result.status).toBe('incomplete');+ expect(passes).toHaveLength(before);+ });+test('a content root that is gone leaves the known documents in place instead of deleting them', async () => {writeFileSync(join(contentDir, 'kept.md'), '# Kept\n');await watch(null);diff --git a/packages/server/src/file-watcher.test.ts b/packages/server/src/file-watcher.test.tsindex e64aee48b..20d0df5c0 100644--- a/packages/server/src/file-watcher.test.ts+++ b/packages/server/src/file-watcher.test.ts@@ -3,6 +3,7 @@ import {readFileSync,realpathSync,renameSync,+ statSync,symlinkSync,unlinkSync,writeFileSync,@@ -10,6 +11,7 @@ import {import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { resolve } from 'node:path';+import { statMtime } from '@inkeep/open-knowledge-core/server';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import { createContentFilter } from './content-filter.ts';import type { DiskEvent } from './file-watcher';@@ -17,6 +19,7 @@ import {classifyEvents,contentHash,evictStaleTrackerEntries,+ type FileIndexEntry,handleRawEvents,isSelfRemoval,isSelfWrite,@@ -551,6 +554,53 @@ describe('classifyEvents', () => {}});+ test("a new file that reuses a removed file's inode number is not a rename unless its size and time match", async () => {+ const removed = resolve(contentDir, 'removed.md');+ const external = resolve(contentDir, 'external.md');+ updateLastKnownHash(removed, contentHash('# Removed\n'));+ writeFileSync(external, '# External, a different file\n');+ const reused = statSync(external, { bigint: true });+ const indexWith = (size: number, modified: string) =>+ new Map<string, FileIndexEntry>([+ [+ 'removed',+ {+ kind: 'markdown',+ canonicalPath: removed,+ inode: `${reused.dev}:${reused.ino}`,+ size,+ modified,+ aliases: [],+ },+ ],+ ]);+ const classify = async (index: Map<string, FileIndexEntry>) => {+ const collected: DiskEvent[] = [];+ await handleRawEvents(+ [+ { type: 'delete', path: removed },+ { type: 'create', path: external },+ ],+ contentDir,+ undefined,+ index,+ new Map(),+ async (event) => {+ collected.push(event);+ },+ );+ return collected.map((event) => event.kind).sort();+ };++ expect(await classify(indexWith(9, '2020-01-01T00:00:00.000Z'))).toEqual(['create', 'delete']);++ updateLastKnownHash(removed, contentHash('# Removed\n'));+ lastKnownHash.delete(external);+ expect(await classify(indexWith(Number(reused.size), statMtime(reused).toISOString()))).toEqual(+ ['rename'],+ );+ });+test('emits separate delete+create when content hashes differ', async () => {const oldPath = resolve(contentDir, 'old.md');const newPath = resolve(contentDir, 'new.md');diff --git a/packages/server/src/file-watcher.ts b/packages/server/src/file-watcher.tsindex 23ea050cc..4799bff5e 100644--- a/packages/server/src/file-watcher.ts+++ b/packages/server/src/file-watcher.ts@@ -287,6 +287,7 @@ export interface RecheckResult {status: RecheckStatus;candidates: number;dispatched: number;+ partial?: boolean;}interface RecoveryOutcome {@@ -301,7 +302,8 @@ interface DispatchCounter {export interface WatcherHandle {unsubscribe: () => Promise<void>;- recheck: () => Promise<RecheckResult>;+ recheck: (mode?: RecoveryMode) => Promise<RecheckResult>;+ recoveryPassesStarted: () => number;recheckPaths: (paths: readonly string[]) => Promise<{ checked: number; found: number }>;getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;getAllFilesIndex: () => AllFileEntries;@@ -830,6 +832,52 @@ type MarkdownRemovalObservation = {const removalOrigins = new WeakMap<RawFileEvent, MarkdownRemovalOrigin>();const removalObservations = new WeakMap<MarkdownDiskEvent, MarkdownRemovalObservation>();+export interface MarkdownEventFacts {+ readonly identity?: string;+ readonly lastHash?: string;+ readonly size?: number;+ readonly modified?: string;+}++export function usableFileIdentity(identity: string | undefined): string | undefined {+ if (identity === undefined || identity === '' || identity.endsWith(':0')) return undefined;+ return identity;+}++interface CreatedFileFacts {+ readonly identity: string | undefined;+ readonly size: number;+ readonly modified: string;+}++const markdownEventFacts = new WeakMap<MarkdownDiskEvent, MarkdownEventFacts>();++export function getMarkdownEventFacts(event: DiskEvent): MarkdownEventFacts {+ if (event.kind !== 'create' && event.kind !== 'delete' && event.kind !== 'rename') return {};+ return markdownEventFacts.get(event) ?? {};+}++function fileIdentityOf(path: string): string | undefined {+ return createdFileFactsOf(path)?.identity;+}++function createdFileFactsOf(path: string): CreatedFileFacts | undefined {+ try {+ const stats = statSync(path, { bigint: true });+ return {+ identity: usableFileIdentity(filesystemIdentity(stats)),+ size: Number(stats.size),+ modified: statMtime(stats).toISOString(),+ };+ } catch (err) {+ const code = errnoCode(err);+ if (code !== 'ENOENT' && code !== 'ENOTDIR' && code !== 'ELOOP') {+ log.debug({ err, path, code }, `could not read the file identity of ${path}`);+ }+ return undefined;+ }+}+export function getMarkdownRemovalCurrentness(event: Extract<DiskEvent, { kind: 'delete' | 'rename' }>,): (() => boolean) | undefined {@@ -983,11 +1031,14 @@ async function classifyEventsInternal(}const createContents = new Map<string, string>();+ const createFacts = new Map<string, CreatedFileFacts>();const updateContents = new Map<string, string>();for (const event of creates) {beginOwnWriteObservation(event.path, observations);try {createContents.set(event.path, await readFile(event.path, 'utf-8'));+ const facts = createdFileFactsOf(event.path);+ if (facts !== undefined) createFacts.set(event.path, facts);} catch (e) {recordWatcherDecision('drop-read-failed', event.type, event.path);if (errnoCode(e) !== 'ENOENT') {@@ -1081,18 +1132,35 @@ async function classifyEventsInternal(const results: MarkdownDiskEvent[] = [];const pairedCreates = new Set<string>();const pairedDeletes = new Set<string>();+ const deletedFacts = new Map<string, MarkdownEventFacts>();for (const del of deletes) {if (aliasContext?.removals.get(del)?.isCurrent() === false) continue;+ const indexed = aliasContext?.fileIndex.get(pathToDocName(del.path, contentDir));+ const indexedHere =+ indexed?.kind === 'markdown' && indexed.canonicalPath === del.path ? indexed : undefined;+ const deletedIdentity = usableFileIdentity(indexedHere?.inode);const deletedHash = removeLastKnownHash(del.path);- if (!deletedHash) continue;+ deletedFacts.set(del.path, {+ identity: deletedIdentity,+ lastHash: deletedHash,+ size: indexedHere?.size,+ modified: indexedHere?.modified,+ });+ if (!deletedHash && deletedIdentity === undefined) continue;for (const create of creates) {if (pairedCreates.has(create.path)) continue;const content = createContents.get(create.path);if (content === undefined) continue;const hash = contentHash(content);- if (hash === deletedHash) {+ const created = createFacts.get(create.path);+ const sameUnchangedFile =+ deletedIdentity !== undefined &&+ created?.identity === deletedIdentity &&+ created.size === indexedHere?.size &&+ created.modified === indexedHere?.modified;+ if (hash === deletedHash || sameUnchangedFile) {pairedCreates.add(create.path);pairedDeletes.add(del.path);updateLastKnownHash(create.path, hash);@@ -1106,6 +1174,10 @@ async function classifyEventsInternal(};const observation = aliasContext?.removals.get(del);if (observation) removalObservations.set(renamed, observation);+ markdownEventFacts.set(renamed, {+ ...createFacts.get(create.path),+ lastHash: deletedHash,+ });results.push(renamed);break;}@@ -1123,6 +1195,8 @@ async function classifyEventsInternal(docName: origin?.kind === 'recovery' ? origin.docName : resolveDocName(del),};if (observation) removalObservations.set(event, observation);+ const facts = deletedFacts.get(del.path);+ if (facts) markdownEventFacts.set(event, facts);results.push(event);}@@ -1141,12 +1215,14 @@ async function classifyEventsInternal(content,});} else {- results.push({+ const created: MarkdownDiskEvent = {kind: 'create',path: create.path,docName: resolveDocName(create),content,- });+ };+ markdownEventFacts.set(created, { ...createFacts.get(create.path) });+ results.push(created);}}@@ -2558,11 +2634,12 @@ export function updateFileIndex(event: DiskEvent, fileIndex: Map<string, FileIndconst existing = fileIndex.get(docName);const ext = extractDocExtension(event.path);if (ext) registerDocExtension(docName, ext);+ const canonicalPath = existing?.canonicalPath ?? event.path;fileIndex.set(docName, {size: Buffer.byteLength(event.content, 'utf-8'),modified: new Date().toISOString(),- canonicalPath: existing?.canonicalPath ?? event.path,- inode: existing?.inode ?? '',+ canonicalPath,+ inode: fileIdentityOf(canonicalPath) ?? existing?.inode ?? '',aliases: existing?.aliases ?? [],kind: 'markdown',...derivePageMeta(event.content, docName),@@ -2594,7 +2671,7 @@ export function updateFileIndex(event: DiskEvent, fileIndex: Map<string, FileIndsize: Buffer.byteLength(event.content, 'utf-8'),modified: new Date().toISOString(),canonicalPath: event.newPath,- inode: existing?.inode ?? '',+ inode: fileIdentityOf(event.newPath) ?? existing?.inode ?? '',aliases: existing?.aliases ?? [],kind: 'markdown',...derivePageMeta(event.content, event.newDocName),@@ -3338,6 +3415,7 @@ function protectedGeneralNames(interface HandedObservation {readonly observed: DiskObservation;readonly sinceEpoch: number;+ readonly pass: number;}async function recoverDiskChanges(@@ -3850,13 +3928,20 @@ interface RecoveryDriverDeps {) => Promise<RecoveryOutcome>;setActivePublicMutations: (mutations: RecoveryPublicMutations | null) => void;onAfterMutation: () => void;- onRecoveryComplete?: () => Promise<void>;+ recoveryHooks: RecoveryHooks;backendName: WatcherBackend;}+interface RecoveryHooks {+ readonly onRecoveryComplete?: () => Promise<void>;+ readonly onRecoveryPassCompleted?: (pass: number, whole: boolean) => Promise<void>;+}+interface RecoveryDriver {requestRecovery: (mode: RecoveryMode, handed?: HandedObservation) => Promise<RecheckResult>;isIdle: () => boolean;+ passesStarted: () => number;+ beginPass: () => number;}function createRecoveryDriver(deps: RecoveryDriverDeps): RecoveryDriver {@@ -3865,6 +3950,7 @@ function createRecoveryDriver(deps: RecoveryDriverDeps): RecoveryDriver {let nextMode: RecoveryMode = 'metadata';let nextHanded: HandedObservation | undefined;let followUpRecovery: PromiseWithResolvers<RecheckResult> | undefined;+ let passesStarted = 0;const closed = (): RecheckResult => ({ status: 'closed', candidates: 0, dispatched: 0 });const recoverOnce = async (): Promise<RecheckResult> => {const mode = nextMode;@@ -3873,6 +3959,7 @@ function createRecoveryDriver(deps: RecoveryDriverDeps): RecoveryDriver {nextMode = 'metadata';nextHanded = undefined;if (deps.isClosed()) return closed();+ const pass = handed?.pass ?? ++passesStarted;recoveryRunning = true;const recoveryMutations: RecoveryPublicMutations = {markdownNames: new Set(),@@ -3888,11 +3975,13 @@ function createRecoveryDriver(deps: RecoveryDriverDeps): RecoveryDriver {const outcome = await deps.recover(recoveryMutations, counter, mode, handed);deps.onAfterMutation();if (outcome.completed) {- if (!outcome.partial) await deps.onRecoveryComplete?.();+ if (!outcome.partial) await deps.recoveryHooks.onRecoveryComplete?.();+ await deps.recoveryHooks.onRecoveryPassCompleted?.(pass, !outcome.partial);result = {status: 'completed',candidates: outcome.candidates,dispatched: counter.dispatched,+ ...(outcome.partial ? { partial: true } : {}),};const finished = {mode: handed ? 'timed' : mode,@@ -3957,13 +4046,20 @@ function createRecoveryDriver(deps: RecoveryDriverDeps): RecoveryDriver {}return nextRecovery;};- return { requestRecovery, isIdle: () => !recoveryRunning && nextRecovery === undefined };+ return {+ requestRecovery,+ isIdle: () => !recoveryRunning && nextRecovery === undefined,+ passesStarted: () => passesStarted,+ beginPass: () => ++passesStarted,+ };}interface WatcherBackendSubscription extends AsyncSubscription {runOrdered(work: () => Promise<void>): Promise<void>;requestRecovery(mode: RecoveryMode, handed?: HandedObservation): Promise<RecheckResult>;isRecoveryIdle(): boolean;+ recoveryPassesStarted(): number;+ beginRecoveryPass(): number;noticeRootMissing(): void;}@@ -3983,7 +4079,7 @@ async function startParcelWatcher(platform: NodeJS.Platform,onRawBatch?: (absPaths: readonly string[]) => void,discoveredStructuralDirs?: ReadonlySet<string>,- onRecoveryComplete?: () => Promise<void>,+ recoveryHooks: RecoveryHooks = {},clock: WatcherClock = watcherClock(),nativeBackend?: NativeWatcherBackend,carryOver: Set<string> = new Set(),@@ -4032,7 +4128,7 @@ async function startParcelWatcher(});return next;};- const { requestRecovery, isIdle } = createRecoveryDriver({+ const { requestRecovery, isIdle, passesStarted, beginPass } = createRecoveryDriver({runOrdered,isClosed: () => closed,recover: (recoveryMutations, counter, mode, handed) =>@@ -4056,7 +4152,7 @@ async function startParcelWatcher(),setActivePublicMutations,onAfterMutation,- onRecoveryComplete,+ recoveryHooks,backendName: 'parcel',});const notificationsFor =@@ -4148,6 +4244,8 @@ async function startParcelWatcher(runOrdered,requestRecovery,isRecoveryIdle: isIdle,+ recoveryPassesStarted: passesStarted,+ beginRecoveryPass: beginPass,noticeRootMissing: () => resubscriber.noticeRootMissing(),async settle() {if (closed) return;@@ -4268,7 +4366,7 @@ async function startChokidarWatcher(platform: NodeJS.Platform,clock: WatcherClock,onRawBatch?: (absPaths: readonly string[]) => void,- onRecoveryComplete?: () => Promise<void>,+ recoveryHooks: RecoveryHooks = {},carryOver: Set<string> = new Set(),coverageWhileLost: string = coverageWithoutWatcher(null),): Promise<WatcherBackendSubscription> {@@ -4284,7 +4382,7 @@ async function startChokidarWatcher(});return next;};- const { requestRecovery, isIdle } = createRecoveryDriver({+ const { requestRecovery, isIdle, passesStarted, beginPass } = createRecoveryDriver({runOrdered,isClosed: () => closed,recover: (recoveryMutations, counter, mode, handed) =>@@ -4308,7 +4406,7 @@ async function startChokidarWatcher(),setActivePublicMutations,onAfterMutation,- onRecoveryComplete,+ recoveryHooks,backendName: 'chokidar',});@@ -4415,6 +4513,8 @@ async function startChokidarWatcher(runOrdered,requestRecovery,isRecoveryIdle: isIdle,+ recoveryPassesStarted: passesStarted,+ beginRecoveryPass: beginPass,noticeRootMissing: () => resubscriber.noticeRootMissing(),unsubscribe: async () => {closed = true;@@ -4442,6 +4542,7 @@ export interface StartWatcherOptions {forceBackend?: 'parcel' | 'chokidar';onRawBatch?: (absPaths: readonly string[]) => void;onRecoveryComplete?: () => Promise<void>;+ onRecoveryPassCompleted?: (pass: number, whole: boolean) => Promise<void>;platform?: NodeJS.Platform;nativeBackend?: NativeWatcherBackend;clock?: WatcherClock;@@ -4479,7 +4580,8 @@ async function startWatcherWithClock(clock: WatcherClock,restoreClock: () => void,): Promise<WatcherHandle> {- const { onRawBatch, onRecoveryComplete } = opts;+ const { onRawBatch, onRecoveryComplete, onRecoveryPassCompleted } = opts;+ const recoveryHooks: RecoveryHooks = { onRecoveryComplete, onRecoveryPassCompleted };const contentDir = resolveDirectoryRoot(contentDirRaw, {root: 'content',component: 'file-watcher',@@ -4560,7 +4662,7 @@ async function startWatcherWithClock(platform,onRawBatch,structuralIgnoreDirs,- onRecoveryComplete,+ recoveryHooks,clock,opts.nativeBackend,carryOver,@@ -4593,7 +4695,7 @@ async function startWatcherWithClock(platform,clock,onRawBatch,- onRecoveryComplete,+ recoveryHooks,carryOver,coverageWhileLost,);@@ -4647,11 +4749,12 @@ async function startWatcherWithClock(const startedAt = clock.now();let elapsedMs = 0;const sinceEpoch = openObservationWindow();+ const pass = backendSubscription.beginRecoveryPass();try {const observed = await walkForFreshness();if (observed === null) return;const result = observed.complete- ? await backendSubscription.requestRecovery('metadata', { observed, sinceEpoch })+ ? await backendSubscription.requestRecovery('metadata', { observed, sinceEpoch, pass }): { status: 'incomplete' as const, candidates: 0, dispatched: 0 };if (handleClosed) return;elapsedMs = clock.now() - startedAt;@@ -4696,8 +4799,11 @@ async function startWatcherWithClock(restoreClock();}},- recheck() {- return backendSubscription.requestRecovery('full');+ recheck(mode = 'full') {+ return backendSubscription.requestRecovery(mode);+ },+ recoveryPassesStarted() {+ return backendSubscription.recoveryPassesStarted();},async recheckPaths(paths) {const unique = [...new Set(paths)];diff --git a/packages/server/src/head-watcher.test.ts b/packages/server/src/head-watcher.test.tsindex 0db1202f3..247af4e19 100644--- a/packages/server/src/head-watcher.test.ts+++ b/packages/server/src/head-watcher.test.ts@@ -97,6 +97,12 @@ describe('watchedGitFile', () => {expect(watchedGitFile('/x/.git/index.lock')).toBe('index.lock');});+ test('recognizes watched files in Windows paths, as the native backend reports them', () => {+ expect(watchedGitFile('C:\\work\\project\\.git\\HEAD')).toBe('HEAD');+ expect(watchedGitFile('C:\\work\\project\\.git\\index')).toBe('index');+ expect(watchedGitFile('C:\\work\\project\\.git\\config')).toBeNull();+ });+test('returns null for paths outside the watched set', () => {expect(watchedGitFile('/x/.git/config')).toBeNull();expect(watchedGitFile('/x/.git/objects/ab/cdef')).toBeNull();diff --git a/packages/server/src/head-watcher.ts b/packages/server/src/head-watcher.tsindex 01478841e..e9560fb50 100644--- a/packages/server/src/head-watcher.ts+++ b/packages/server/src/head-watcher.ts@@ -72,7 +72,7 @@ export function readProjectHeadState(projectRoot: string): ProjectHeadState {type HeadEventDispatch = (rawPath: string) => void;export function watchedGitFile(rawPath: string): string | null {- const fileName = rawPath.split('/').pop() ?? '';+ const fileName = rawPath.split(/[\\/]/).pop() ?? '';return WATCHED_FILES.has(fileName) ? fileName : null;}diff --git a/packages/server/src/http/agent-write-routes.ts b/packages/server/src/http/agent-write-routes.tsindex a4e416271..d8efd84cb 100644--- a/packages/server/src/http/agent-write-routes.ts+++ b/packages/server/src/http/agent-write-routes.ts@@ -67,7 +67,12 @@ import {} from '../content-divergence-gate.ts';import { recordContributor } from '../contributor-tracker.ts';import { canonicalDocName, registerDocExtension, stripDocExtension } from '../doc-extensions.ts';-import type { DocumentDurabilityState, StoreFailure } from '../document-durability-state.ts';+import {+ type DocumentDurabilityState,+ type StoreFailure,+ type WrittenThrough,+ writtenThroughOf,+} from '../document-durability-state.ts';import {type ReconcileBeforeWriteResult,reconcileDiskBeforeAgentWrite,@@ -188,6 +193,7 @@ export interface AgentWriteRouteDeps {countNormalizedSummary: (normalized: NormalizedSummary, fromDefault?: boolean) => void;flushDiskAndDetectOutcome: (docName: string,+ writtenThrough?: WrittenThrough,) => Promise<{ kind: 'failure'; failure: StoreFailure } | { kind: 'stale-external-write' } | null>;@@ -389,6 +395,7 @@ export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroupconst timestamp = new Date().toISOString();let writeDivergence: AgentWriteContentDivergence | undefined;let disposeEffectCapture: (() => void) | undefined;+ let writtenThrough: WrittenThrough | undefined;try {const icon = iconFromClientName(clientName);const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);@@ -430,6 +437,7 @@ export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroup...(changedBlocks !== undefined ? { changedBlocks } : {}),});}, session.origin);+ writtenThrough = writtenThroughOf(session.dc.document);if (writeDivergence !== undefined) {console.warn(JSON.stringify({@@ -460,7 +468,7 @@ export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroupdisposeEffectCapture?.();agentPresenceBroadcaster?.touchMode(agentId, 'idle');}- const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);+ const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName, writtenThrough);if (flushOutcome?.kind === 'failure') {respondPersistenceFailure(res, flushOutcome.failure, 'agent-write-md');return;diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.tsindex 3f0ca425d..b6538183f 100644--- a/packages/server/src/metrics.ts+++ b/packages/server/src/metrics.ts@@ -181,7 +181,18 @@ export interface ReconciliationMetrics {watcherResubscribes: number;watcherRootMissing: number;watcherUnreadableEntries: number;+ inPlaceSkillRescanFailures: number;watcherResubscribesAbandoned: number;+ vanishPending: number;+ vanishPairedIdentity: number;+ vanishPairedHash: number;+ vanishRecreated: number;+ vanishDeleted: number;+ vanishShutdown: number;+ vanishUnconfirmed: number;+ outsideRenameRecordFailures: number;+ outsideRenameClaimFailures: number;+ branchSwitchRecheckShortfalls: number;}const counters: ReconciliationMetrics = {@@ -313,7 +324,18 @@ const counters: ReconciliationMetrics = {watcherResubscribes: 0,watcherRootMissing: 0,watcherUnreadableEntries: 0,+ inPlaceSkillRescanFailures: 0,watcherResubscribesAbandoned: 0,+ vanishPending: 0,+ vanishPairedIdentity: 0,+ vanishPairedHash: 0,+ vanishRecreated: 0,+ vanishDeleted: 0,+ vanishShutdown: 0,+ vanishUnconfirmed: 0,+ outsideRenameRecordFailures: 0,+ outsideRenameClaimFailures: 0,+ branchSwitchRecheckShortfalls: 0,};export function incrementReconcile(): void {@@ -787,10 +809,65 @@ export function incrementWatcherUnreadableEntries(): void {counters.watcherUnreadableEntries++;}+export function incrementInPlaceSkillRescanFailures(): void {+ counters.inPlaceSkillRescanFailures++;+}+export function incrementWatcherResubscribesAbandoned(): void {counters.watcherResubscribesAbandoned++;}+export type VanishOutcome =+ | 'pending'+ | 'paired-identity'+ | 'paired-hash'+ | 'recreated'+ | 'deleted'+ | 'shutdown'+ | 'unconfirmed';++export function recordVanishOutcome(outcome: VanishOutcome): void {+ switch (outcome) {+ case 'pending':+ counters.vanishPending++;+ return;+ case 'paired-identity':+ counters.vanishPairedIdentity++;+ return;+ case 'paired-hash':+ counters.vanishPairedHash++;+ return;+ case 'recreated':+ counters.vanishRecreated++;+ return;+ case 'deleted':+ counters.vanishDeleted++;+ return;+ case 'shutdown':+ counters.vanishShutdown++;+ return;+ case 'unconfirmed':+ counters.vanishUnconfirmed++;+ return;+ default: {+ const unhandled: never = outcome;+ throw new Error(`unhandled vanish outcome: ${String(unhandled)}`);+ }+ }+}++export function incrementOutsideRenameRecordFailures(): void {+ counters.outsideRenameRecordFailures++;+}++export function incrementOutsideRenameClaimFailures(): void {+ counters.outsideRenameClaimFailures++;+}++export function incrementBranchSwitchRecheckShortfalls(): void {+ counters.branchSwitchRecheckShortfalls++;+}+export function incrementCollabSocketFilteredError(code: 'EPIPE' | 'ECONNRESET'): void {if (code === 'EPIPE') counters.collabSocketEpipeCount++;else counters.collabSocketEconnresetCount++;@@ -981,5 +1058,16 @@ export function resetMetrics(): void {counters.watcherResubscribes = 0;counters.watcherRootMissing = 0;counters.watcherUnreadableEntries = 0;+ counters.inPlaceSkillRescanFailures = 0;counters.watcherResubscribesAbandoned = 0;+ counters.vanishPending = 0;+ counters.vanishPairedIdentity = 0;+ counters.vanishPairedHash = 0;+ counters.vanishRecreated = 0;+ counters.vanishDeleted = 0;+ counters.vanishShutdown = 0;+ counters.vanishUnconfirmed = 0;+ counters.outsideRenameRecordFailures = 0;+ counters.outsideRenameClaimFailures = 0;+ counters.branchSwitchRecheckShortfalls = 0;}diff --git a/packages/server/src/parcel-drop-notice.test.ts b/packages/server/src/parcel-drop-notice.test.tsindex 1e1feffec..d6e01889f 100644--- a/packages/server/src/parcel-drop-notice.test.ts+++ b/packages/server/src/parcel-drop-notice.test.ts@@ -29,6 +29,7 @@ import {createContentFilter,createContentFilterAsync,} from './content-filter.ts';+import { DerivedDocumentIndex } from './derived-document-index.ts';import { _resetDocExtensionsForTests, getDocExtension } from './doc-extensions.ts';import {classifyEvents,@@ -4089,8 +4090,6 @@ test.each([server = await bootCompositionRig(contentDir);await server.ready;const active = server;- const firstConnection = await active.serverInstance.hocuspocus.openDirectConnection('first');- connections.push(firstConnection);const laterConnection = await active.serverInstance.hocuspocus.openDirectConnection('later');connections.push(laterConnection);const lifecycle = laterConnection.document.getMap('lifecycle');@@ -4106,13 +4105,16 @@ test.each([expect(readFileSync(later, 'utf8')).toBe(recreatedBytes);recreationCount += 1;};- active.serverInstance.hocuspocus.configuration.extensions.push({- async afterUnloadDocument({ documentName }: { documentName: string }) {- if (!armed || documentName !== 'first') return;- hookCount += 1;- if (timing === 'during') await recreate();+ const recordDiskDelete = DerivedDocumentIndex.prototype.recordDiskDelete;+ vi.spyOn(DerivedDocumentIndex.prototype, 'recordDiskDelete').mockImplementation(+ async function (this: DerivedDocumentIndex, documentName: string) {+ if (armed && documentName === 'first') {+ hookCount += 1;+ if (timing === 'during') await recreate();+ }+ return recordDiskDelete.call(this, documentName);},- });+ );const subscription = nativeSubscriptionOn(contentDir);unlinkSync(first);unlinkSync(later);@@ -4220,7 +4222,6 @@ test.each(['before', 'during'] as const)(server = await bootCompositionRig(contentDir);await server.ready;const active = server;- connections.push(await active.serverInstance.hocuspocus.openDirectConnection('first'));connections.push(await active.serverInstance.hocuspocus.openDirectConnection('later'));const recreate = async () => {const response = await fetch(`http://127.0.0.1:${active.port}/api/create-page`, {@@ -4234,15 +4235,19 @@ test.each(['before', 'during'] as const)(recreations += 1;phases.push('recreated');};- active.serverInstance.hocuspocus.configuration.extensions.push({- async afterUnloadDocument({ documentName }: { documentName: string }) {- if (!armed) return;- if (documentName === 'first') {- phases.push('first-unloaded');+ const recordDiskDelete = DerivedDocumentIndex.prototype.recordDiskDelete;+ vi.spyOn(DerivedDocumentIndex.prototype, 'recordDiskDelete').mockImplementation(+ async function (this: DerivedDocumentIndex, documentName: string) {+ if (armed && documentName === 'first') {+ phases.push('first-deleted');if (timing === 'during') await recreate();- } else if (documentName === 'later') {- phases.push('later-unloaded');}+ return recordDiskDelete.call(this, documentName);+ },+ );+ active.serverInstance.hocuspocus.configuration.extensions.push({+ async afterUnloadDocument({ documentName }: { documentName: string }) {+ if (armed && documentName === 'later') phases.push('later-unloaded');},});unlinkSync(first);@@ -4261,8 +4266,8 @@ test.each(['before', 'during'] as const)(armed = false;expect(phases).toEqual(timing === 'before'- ? ['recreated', 'first-unloaded', 'later-unloaded']- : ['first-unloaded', 'recreated', 'later-unloaded'],+ ? ['recreated', 'first-deleted', 'later-unloaded']+ : ['first-deleted', 'recreated', 'later-unloaded'],);expect(recreations).toBe(1);expect(readFileSync(later, 'utf8')).toBe(recreatedBytes);@@ -10193,6 +10198,8 @@ test.each([} else {await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path: canonical }]);}+ expect(lifecycle.get('status')).not.toBe('deleted-upstream');+ await server.serverInstance.recheckDisk();expect(lifecycle.get('status')).toBe('deleted-upstream');expect(server.serverInstance.hocuspocus.documents.has('real/note')).toBe(false);expect(@@ -10403,6 +10410,8 @@ test.each([rmSync(folder, { recursive: true });unlinkSync(gone);await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));+ expect(removedLifecycle.get('status')).not.toBe('deleted-upstream');+ await server.serverInstance.recheckDisk();expect.soft(lifecycle.get('status')).not.toBe('deleted-upstream');expect.soft(server.serverInstance.hocuspocus.documents.get('notes') === document).toBe(true);expect.soft(getDocExtension('notes')).toBe(docExt);diff --git a/packages/server/src/persistence-deferred-store.test.ts b/packages/server/src/persistence-deferred-store.test.tsindex 997c19230..6817399df 100644--- a/packages/server/src/persistence-deferred-store.test.ts+++ b/packages/server/src/persistence-deferred-store.test.ts@@ -300,7 +300,10 @@ describe('batch-gated L1 persistence', () => {expect(readFileSync(docPath, 'utf-8')).toBe('target branch content\n');expect(acks).toHaveLength(0);- await expect(outcome).resolves.toEqual({ kind: 'discarded' });+ await expect(outcome).resolves.toEqual({+ kind: 'discarded',+ cause: { kind: 'branch-switch' },+ });});test('a within-branch flush discards a store deferred on another branch', async () => {@@ -327,7 +330,10 @@ describe('batch-gated L1 persistence', () => {await persistence.flushDeferredStores('within-branch');expect(readFileSync(docPath, 'utf-8')).toBe('branch A base\n');- await expect(outcome).resolves.toEqual({ kind: 'discarded' });+ await expect(outcome).resolves.toEqual({+ kind: 'discarded',+ cause: { kind: 'branch-switch' },+ });document.destroy();});@@ -383,7 +389,10 @@ describe('batch-gated L1 persistence', () => {expect(readFileSync(secondPath, 'utf-8')).toBe('second base\n');await expect(firstOutcome).resolves.toEqual({ kind: 'completed' });await expect(secondPendingAfterDiscardCall).resolves.toBeUndefined();- await expect(secondOutcome).resolves.toEqual({ kind: 'discarded' });+ await expect(secondOutcome).resolves.toEqual({+ kind: 'discarded',+ cause: { kind: 'branch-switch' },+ });firstDoc.destroy();secondDoc.destroy();diff --git a/packages/server/src/persistence-publication-receipt.test.ts b/packages/server/src/persistence-publication-receipt.test.tsindex 0f98129f4..b85fcf87c 100644--- a/packages/server/src/persistence-publication-receipt.test.ts+++ b/packages/server/src/persistence-publication-receipt.test.ts@@ -301,7 +301,10 @@ describe('successful publication receipt ownership', () => {writeFileSync(fixture.docPath, 'other branch\n');durability.setBatchInProgress(false);await persistence.flushDeferredStores('discard-stale');- await expect(outcome).resolves.toEqual({ kind: 'discarded' });+ await expect(outcome).resolves.toEqual({+ kind: 'discarded',+ cause: { kind: 'branch-switch' },+ });releaseAdmission();expect(fixture.disk()).toBe('other branch\n');expect(authority.canRetire(discarded)).toBe(true);diff --git a/packages/server/src/persistence-removed-doc-publish.test.ts b/packages/server/src/persistence-removed-doc-publish.test.tsindex 86e75da3d..4d7dc652f 100644--- a/packages/server/src/persistence-removed-doc-publish.test.ts+++ b/packages/server/src/persistence-removed-doc-publish.test.ts@@ -217,14 +217,14 @@ describe('persistence publish guard — a removed document is never republished'expect(refusalEvents(warn).at(-1)?.reason).toBe('file-absent');});- test('refuses after a branch switch has dropped the reconciled base', async () => {+ test('refuses after the reconciled base has been dropped', async () => {writeFileSync(docPath, SEEDED, 'utf-8');const persistence = persistenceWith();await loadFromDisk(persistence);document.transact(() => appendUnflushedEdit(document), BROWSER_ORIGIN);vi.spyOn(console, 'warn').mockImplementation(() => {});- durabilityState.switchReconciledBaseScope('feature');+ durabilityState.deleteReconciledBase(docName);expect(durabilityState.getReconciledBase(docName)).toBeUndefined();rmSync(docPath);diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.tsindex 2807d794f..24a77c0cf 100644--- a/packages/server/src/persistence.ts+++ b/packages/server/src/persistence.ts@@ -68,6 +68,7 @@ import { applyDiskContentToDoc, FILE_WATCHER_ORIGIN } from './disk-content-intakimport type { FileObservation } from './disk-receipts.ts';import {assertNeverStorePublishOutcome,+ type DeferredStoreDiscardCause,type DeferredStoreOutcome,type DeferredStoreSettlement,DocumentDurabilityState,@@ -503,6 +504,7 @@ export interface PersistenceHandle {extension: Extension;readonly durabilityState: DocumentDurabilityState;flushDeferredStores: (mode?: 'within-branch' | 'discard-stale') => Promise<void>;+ discardDeferredStore: (docName: string, cause: DeferredStoreDiscardCause) => void;flushPendingGitCommit: () => Promise<void>;flushContributors: () => Promise<void>;waitForPendingCommits: () => Promise<void>;@@ -1359,9 +1361,9 @@ export function createPersistenceExtension(options: PersistenceOptions): Persist): StoreFailureRemoval | undefined {if (frozenPathOccupied(documentName)) return { kind: 'path-occupied' };const newPath = document.getMap('lifecycle').get('newPath');- return status === 'renamed' && typeof newPath === 'string' && newPath !== ''- ? { kind: 'renamed', renamedTo: newPath }- : undefined;+ if (status !== 'renamed' || typeof newPath !== 'string' || newPath === '') return undefined;+ const carry = durabilityState.renameCarryOf(documentName);+ return { kind: 'renamed', renamedTo: newPath, ...(carry ? { carry } : {}) };}function documentHadFileOnDisk(documentName: string, base: string | undefined): boolean {@@ -2192,10 +2194,27 @@ export function createPersistenceExtension(options: PersistenceOptions): Persist}function discardDeferredStores(): void {- for (const entry of deferredStores.values()) entry.settlement.settle({ kind: 'discarded' });+ for (const entry of deferredStores.values()) {+ entry.settlement.settle({ kind: 'discarded', cause: { kind: 'branch-switch' } });+ }deferredStores.clear();}+ function discardDeferredStore(documentName: string, cause: DeferredStoreDiscardCause): void {+ deferredStores.get(documentName)?.settlement.settle({ kind: 'discarded', cause });+ deferredStores.delete(documentName);+ }++ const isStoreHeld = (documentName: string): boolean =>+ durabilityState.areStoresHeld(documentName);++ function hasUnheldDeferredStores(): boolean {+ for (const documentName of deferredStores.keys()) {+ if (!isStoreHeld(documentName)) return true;+ }+ return false;+ }+async function flushDeferredStores(mode: 'within-branch' | 'discard-stale' = 'within-branch') {if (mode === 'discard-stale') discardDeferredStores();if (deferredStoreDrainInFlight) {@@ -2210,13 +2229,13 @@ export function createPersistenceExtension(options: PersistenceOptions): Persistlet drainMode = mode;while (true) {if (drainMode === 'discard-stale') discardDeferredStores();- const entries = [...deferredStores.entries()];- deferredStores.clear();+ const entries = [...deferredStores.entries()].filter(([name]) => !isStoreHeld(name));+ for (const [documentName] of entries) deferredStores.delete(documentName);if (drainMode !== 'discard-stale') {for (const [documentName, entry] of entries) {if (entry.branch !== durabilityState.getActiveBranch()) {- entry.settlement.settle({ kind: 'discarded' });+ entry.settlement.settle({ kind: 'discarded', cause: { kind: 'branch-switch' } });continue;}let outcome: DeferredStoreOutcome = { kind: 'completed' };@@ -2278,7 +2297,7 @@ export function createPersistenceExtension(options: PersistenceOptions): Persistconst nextMode = pendingDeferredStoreFlushMode;pendingDeferredStoreFlushMode = null;- if (deferredStores.size === 0 && nextMode === null) break;+ if (!hasUnheldDeferredStores() && nextMode === null) break;drainMode = nextMode ?? 'within-branch';}})().finally(() => {@@ -2511,7 +2530,7 @@ export function createPersistenceExtension(options: PersistenceOptions): Persistawait storeMermaidDoc(document, documentName, lastTransactionOrigin, mermaidPersistenceCtx);return;}- if (durabilityState.isBatchInProgress()) {+ if (durabilityState.isBatchInProgress() || isStoreHeld(documentName)) {deferStore({ document, documentName, lastTransactionOrigin });return;}@@ -2553,7 +2572,7 @@ export function createPersistenceExtension(options: PersistenceOptions): Persistif (isPersistenceExcludedDoc(documentName)) {return;}- if (durabilityState.isBatchInProgress()) {+ if (durabilityState.isBatchInProgress() || isStoreHeld(documentName)) {deferStore({ document, documentName, lastTransactionOrigin: null });return;}@@ -2568,6 +2587,7 @@ export function createPersistenceExtension(options: PersistenceOptions): Persistextension,durabilityState,flushDeferredStores,+ discardDeferredStore,flushPendingGitCommit,flushContributors,waitForPendingCommits,diff --git a/packages/server/src/rename-log.test.ts b/packages/server/src/rename-log.test.tsindex 9d22df684..f5b4ce063 100644--- a/packages/server/src/rename-log.test.ts+++ b/packages/server/src/rename-log.test.ts@@ -18,9 +18,11 @@ import {expandPredecessors,gcRenameLog,loadRenameLogIndex,+ logSeededReachable,MAX_PREDECESSOR_CHAIN_DEPTH,pendingRenameLogEntries,RENAME_LOG_HARD_CAP_BYTES,+ RENAME_LOG_MAX_LINE_BYTES,type RenameLogEntry,renameLogPath,resolveDocPathAtCommit,@@ -293,6 +295,39 @@ describe('appendRenameLogEntry', () => {}expect(warned).toBe(true);});++ test('keeps the entry and the leading writer anchors that fit the line limit, before and after the claim', () => {+ const index = createEmptyIndex();+ const anchors = Array.from({ length: 200 }, (_, i) => i.toString(16).padStart(40, '0'));+ const writerId = 'agent-conn-abc';+ appendRenameLogEntry(shadowDir, entry({ from: 'a', to: 'b', anchors }), index);+ expect(Buffer.byteLength(readFileSync(renameLogPath(shadowDir), 'utf-8'))).toBeLessThanOrEqual(+ RENAME_LOG_MAX_LINE_BYTES,+ );++ backfillRenameLogCommitSha(+ shadowDir,+ writerId,+ 'c'.repeat(40),+ index,+ pendingRenameLogEntries(index),+ );+ const line = readFileSync(renameLogPath(shadowDir), 'utf-8');+ expect(Buffer.byteLength(line, 'utf-8')).toBeLessThanOrEqual(RENAME_LOG_MAX_LINE_BYTES);+ const reloaded = loadRenameLogIndex(shadowDir).byTo.get('b');+ expect(reloaded?.commitSha).toBe('c'.repeat(40));+ const kept = reloaded?.anchors ?? [];+ expect(kept.length).toBeGreaterThan(0);+ expect(kept).toEqual(anchors.slice(0, kept.length));+ expect(index.byTo.get('b')?.anchors).toEqual(kept);+ const withOneMore = JSON.stringify({+ ...JSON.parse(line),+ anchors: anchors.slice(0, kept.length + 1),+ });+ expect(Buffer.byteLength(`${withOneMore}\n`, 'utf-8')).toBeGreaterThan(+ RENAME_LOG_MAX_LINE_BYTES,+ );+ });});describe('expandPredecessors', () => {@@ -639,6 +674,30 @@ describe('rename-log read primitives (shadow-repo backed)', () => {expect(set.has(sha2)).toBe(true);});+ test('buildSeeds — a writer anchor whose commit is gone is dropped, and the live ones keep their ancestry', async () => {+ const sha1 = await commit('# v1\n', 'a.md', 'WIP: v1');+ const anchor = await commit('# v2\n', 'a.md', 'WIP: v2');+ const renameSha = await commit('# v3\n', 'b.md', 'rename: a -> b');+ const gone = 'f'.repeat(40);+ const seeds = await buildSeeds(shadow, renameSha, 'main', undefined, [gone, anchor]);+ expect(seeds).toContain(renameSha);+ expect(seeds).toContain(anchor);+ expect(seeds).not.toContain(gone);+ const set = await buildAncestorShaSet(shadow, seeds, 'main');+ expect(set.has(sha1)).toBe(true);+ const walked = await logSeededReachable(shadow, ['--format=%H'], seeds, 'content/a.md');+ expect(walked.split('\n')).toContain(sha1);+ });++ test('buildAncestorShaSet — a seed whose object is gone still fails the walk', async () => {+ const sha1 = await commit('# v1\n', 'a.md', 'WIP: v1');+ const set = await buildAncestorShaSet(shadow, [sha1, 'f'.repeat(40)], 'main');+ expect(set.size).toBe(0);+ await expect(+ logSeededReachable(shadow, ['--format=%H'], [sha1, 'f'.repeat(40)], 'content/a.md'),+ ).rejects.toThrow();+ });+test('buildAncestorShaSet — cache hit on identical seeds key', async () => {const sha = await commit('# v1\n', 'a.md', 'WIP: v1');const cache = createAncestorShaSetCache();@@ -1619,6 +1678,21 @@ describe('buildSeeds — SeedsCache (Consider C2)', () => {expect(feature).not.toBe(main);expect(cache.size).toBe(2);});++ test('cache miss when anchors differ for the same rename commit', async () => {+ writeFileSync(resolve(projectRoot, 'content', 'a.md'), '# A\n');+ const firstAnchor = await commitWip(shadow, writer, 'content', 'WIP: a');+ writeFileSync(resolve(projectRoot, 'content', 'a.md'), '# A2\n');+ const secondAnchor = await commitWip(shadow, writer, 'content', 'WIP: a2');+ writeFileSync(resolve(projectRoot, 'content', 'b.md'), '# B\n');+ const sha = await commitWip(shadow, writer, 'content', 'rename: a -> b');+ const cache = createSeedsCache();+ const first = await buildSeeds(shadow, sha, 'main', cache, [firstAnchor]);+ const second = await buildSeeds(shadow, sha, 'main', cache, [secondAnchor]);+ expect(first).toContain(firstAnchor);+ expect(second).toContain(secondAnchor);+ expect(second).not.toContain(firstAnchor);+ });});describe('gcRenameLog concurrency dedup (Finding 4)', () => {diff --git a/packages/server/src/rename-log.ts b/packages/server/src/rename-log.tsindex 887dd37c5..39a9c8408 100644--- a/packages/server/src/rename-log.ts+++ b/packages/server/src/rename-log.ts@@ -47,11 +47,12 @@ export interface RenameLogEntry {writerId: string;displayName: string;};+ anchors?: string[];}export const RENAME_LOG_HARD_CAP_BYTES = 5 * 1024 * 1024;-const RENAME_LOG_MAX_LINE_BYTES = 4 * 1024;+export const RENAME_LOG_MAX_LINE_BYTES = 4 * 1024;const RENAME_LOG_FILENAME = 'renames.jsonl';@@ -85,6 +86,13 @@ function validateEntry(obj: unknown): RenameLogEntry | null {const actor = o.actor as Record<string, unknown>;if (typeof actor.writerId !== 'string' || actor.writerId.length === 0) return null;if (typeof actor.displayName !== 'string') return null;+ let anchors: string[] | undefined;+ if (o.anchors !== undefined) {+ if (!Array.isArray(o.anchors)) return null;+ if (!o.anchors.every((sha) => typeof sha === 'string' && /^[0-9a-f]{40}$/.test(sha)))+ return null;+ anchors = o.anchors as string[];+ }return {v: 1,from: o.from,@@ -95,6 +103,7 @@ function validateEntry(obj: unknown): RenameLogEntry | null {groupId: o.groupId,kind: o.kind,actor: { writerId: actor.writerId, displayName: actor.displayName },+ ...(anchors !== undefined && anchors.length > 0 ? { anchors } : {}),};}@@ -174,6 +183,31 @@ export function loadRenameLogIndex(shadowDir: string): RenameLogIndex {return index;}+function renameLogLineBytes(entry: RenameLogEntry): number {+ return Buffer.byteLength(`${JSON.stringify(entry)}\n`, 'utf-8');+}++function anchorsWithinLineLimit(entry: RenameLogEntry): RenameLogEntry {+ const anchors = entry.anchors;+ if (!anchors || anchors.length === 0) return entry;+ const claimed = entry.commitSha === '' ? { ...entry, commitSha: '0'.repeat(40) } : entry;+ if (renameLogLineBytes(claimed) <= RENAME_LOG_MAX_LINE_BYTES) return entry;+ let bytes = renameLogLineBytes({ ...claimed, anchors: [] });+ const kept: string[] = [];+ for (const anchor of anchors) {+ const added = Buffer.byteLength(JSON.stringify(anchor), 'utf-8') + (kept.length > 0 ? 1 : 0);+ if (bytes + added > RENAME_LOG_MAX_LINE_BYTES) break;+ bytes += added;+ kept.push(anchor);+ }+ log.warn(+ { to: entry.to, kept: kept.length, dropped: anchors.length - kept.length },+ `[rename-log] the entry for ${entry.to} keeps ${kept.length} of ${anchors.length} writer anchors to fit the ${RENAME_LOG_MAX_LINE_BYTES}-byte line limit`,+ );+ const { anchors: _dropped, ...withoutAnchors } = entry;+ return kept.length > 0 ? { ...withoutAnchors, anchors: kept } : withoutAnchors;+}+export function appendRenameLogEntry(shadowDir: string,entry: RenameLogEntry,@@ -184,7 +218,8 @@ export function appendRenameLogEntry(if (!validated) {throw new Error('[rename-log] refusing to append malformed entry');}- const serialized = `${JSON.stringify(validated)}\n`;+ const persisted = anchorsWithinLineLimit(validated);+ const serialized = `${JSON.stringify(persisted)}\n`;if (Buffer.byteLength(serialized, 'utf-8') > RENAME_LOG_MAX_LINE_BYTES) {throw new Error(`[rename-log] entry exceeds max line size (${RENAME_LOG_MAX_LINE_BYTES} bytes)`,@@ -205,7 +240,7 @@ export function appendRenameLogEntry(} catch {}}tracedAppendFileSync(path, serialized, { flag: 'a' });- indexInsert(index, validated);+ indexInsert(index, persisted);liveEntriesGauge().add(1);if (overCap && shadow) {@@ -258,6 +293,7 @@ function parseGitTimeoutMs(): number {interface PredecessorChainEntry {path: string;renameCommit: string | null;+ anchors?: readonly string[];}export const MAX_PREDECESSOR_CHAIN_DEPTH = 100;@@ -299,7 +335,7 @@ export function expandPredecessors(skipped += 1;break;}- chain.push({ path: entry.from, renameCommit: entry.commitSha });+ chain.push({ path: entry.from, renameCommit: entry.commitSha, anchors: entry.anchors });cursor = entry.from;}chain.reverse();@@ -319,15 +355,45 @@ export function createSeedsCache(): SeedsCache {return new Map();}+async function anchorsStillInHistory(+ shadow: ShadowHandle,+ renameCommit: string,+ anchors: readonly string[],+): Promise<string[]> {+ const candidates = [...new Set(anchors)].filter((anchor) => anchor !== renameCommit);+ if (candidates.length === 0) return [];+ let raw: string;+ try {+ raw = await shadowGit(shadow).raw('rev-list', '--no-walk', '--ignore-missing', ...candidates);+ } catch (err) {+ log.warn(+ { renameCommit, anchors: candidates.length, err },+ `[rename-log] WARN: buildSeeds: could not check the writer anchors of rename commit ${renameCommit}; walking without them`,+ );+ return [];+ }+ const present = new Set(raw.split('\n').map((line) => line.trim()));+ const kept = candidates.filter((anchor) => present.has(anchor));+ if (kept.length < candidates.length) {+ log.info(+ { renameCommit, dropped: candidates.length - kept.length },+ `[rename-log] buildSeeds: skipped ${candidates.length - kept.length} writer anchors of rename commit ${renameCommit} whose commits are gone`,+ );+ }+ return kept;+}+export async function buildSeeds(shadow: ShadowHandle,renameCommit: string,branch: string,cache?: SeedsCache,+ anchors: readonly string[] = [],): Promise<string[]> {return withSpan('rename.buildSeeds', undefined, async (span) => {+ const cacheKey = `${branch}:${renameCommit}:${[...anchors].sort().join(',')}`;if (cache) {- const hit = cache.get(`${branch}:${renameCommit}`);+ const hit = cache.get(cacheKey);if (hit) {span.setAttribute('rename.seeds_count', hit.length);span.setAttribute('rename.cache_hit', true);@@ -336,6 +402,7 @@ export async function buildSeeds(}const sg = shadowGit(shadow);+ const liveAnchors = await anchorsStillInHistory(shadow, renameCommit, anchors);let renameAuthorDate: string;try {@@ -345,12 +412,12 @@ export async function buildSeeds({ renameCommit, err },`[rename-log] WARN: buildSeeds: git show failed for rename commit ${renameCommit}; falling back to single-seed`,);- span.setAttribute('rename.seeds_count', 1);- return [renameCommit];+ span.setAttribute('rename.seeds_count', 1 + liveAnchors.length);+ return [renameCommit, ...liveAnchors];}if (!renameAuthorDate) {- span.setAttribute('rename.seeds_count', 1);- return [renameCommit];+ span.setAttribute('rename.seeds_count', 1 + liveAnchors.length);+ return [renameCommit, ...liveAnchors];}let raw: string;@@ -366,11 +433,12 @@ export async function buildSeeds({ branch, err },`[rename-log] WARN: buildSeeds: for-each-ref failed for branch ${branch}; falling back to single-seed`,);- span.setAttribute('rename.seeds_count', 1);- return [renameCommit];+ span.setAttribute('rename.seeds_count', 1 + liveAnchors.length);+ return [renameCommit, ...liveAnchors];}const seeds: string[] = [renameCommit];+ seeds.push(...liveAnchors);for (const line of raw.split('\n')) {const trimmed = line.trim();if (!trimmed) continue;@@ -383,7 +451,7 @@ export async function buildSeeds(if (date < renameAuthorDate) seeds.push(sha);}span.setAttribute('rename.seeds_count', seeds.length);- if (cache) cache.set(`${branch}:${renameCommit}`, seeds);+ if (cache) cache.set(cacheKey, seeds);return seeds;});}@@ -1030,7 +1098,7 @@ export async function resolveDocPathAtCommit(const predecessorAncestors: Array<Set<string> | null> = await Promise.all(chain.map(async (step) => {if (step.renameCommit === null) return null;- const seeds = await buildSeeds(shadow, step.renameCommit, branch, seedsCache);+ const seeds = await buildSeeds(shadow, step.renameCommit, branch, seedsCache, step.anchors);if (seeds.length === 0) return new Set<string>();return buildAncestorShaSet(shadow, seeds, branch, cache);}),diff --git a/packages/server/src/rename-records.ts b/packages/server/src/rename-records.tsnew file mode 100644index 000000000..71bc72f4b--- /dev/null+++ b/packages/server/src/rename-records.ts@@ -0,0 +1,82 @@+import { randomUUID } from 'node:crypto';+import { formatRenameSubject } from '@inkeep/open-knowledge-core/shadow-repo-layout';+import { recordContributor } from './contributor-tracker.ts';+import { stripDocExtension } from './doc-extensions.ts';+import {+ appendRenameLogEntry,+ getOrLoadRenameLogIndex,+ type RenameLogEntry,+} from './rename-log.ts';+import type { ShadowHandle } from './shadow-repo.ts';++type ContributorActor = Parameters<typeof recordContributor>[5];++export interface RenameRecordWriter {+ readonly writerId: string;+ readonly displayName: string;+ readonly colorSeed?: string;+ readonly actor?: ContributorActor;+}++export interface FollowedMove {+ readonly from: string;+ readonly to: string;+ readonly toFile?: string;+}++export interface RenameNoticeSink {+ rename(oldDocName: string, newDocName: string, branch: string, newFile?: string): void;+}++export function followRenameRecords(input: {+ readonly moves: readonly FollowedMove[];+ readonly kind: RenameLogEntry['kind'];+ readonly branch: string;+ readonly writer: RenameRecordWriter;+ readonly shadow: ShadowHandle | null | undefined;+ readonly notices: RenameNoticeSink | undefined;+ readonly anchors?: readonly string[];+}): number {+ for (const { from, to, toFile } of input.moves) {+ if (from !== to) input.notices?.rename(from, to, input.branch, toFile);+ }+ const shadow = input.shadow;+ if (!shadow) return 0;+ const logged = input.moves.filter(+ ({ from, to }) => stripDocExtension(from) !== stripDocExtension(to),+ );+ if (logged.length === 0) return 0;+ const groupId = randomUUID();+ const at = new Date().toISOString();+ const index = getOrLoadRenameLogIndex(shadow.gitDir);+ for (const { from, to } of logged) {+ appendRenameLogEntry(+ shadow.gitDir,+ {+ v: 1,+ from,+ to,+ at,+ commitSha: '',+ branch: input.branch,+ groupId,+ kind: input.kind,+ actor: { writerId: input.writer.writerId, displayName: input.writer.displayName },+ ...(input.anchors && input.anchors.length > 0 ? { anchors: [...input.anchors] } : {}),+ },+ index,+ shadow,+ );+ recordContributor(+ to,+ input.writer.writerId,+ input.writer.displayName,+ input.writer.colorSeed,+ formatRenameSubject(from, to),+ input.writer.actor,+ undefined,+ [{ from, to }],+ );+ }+ return logged.length;+}diff --git a/packages/server/src/server-factory.test.ts b/packages/server/src/server-factory.test.tsindex f9b4da49c..d5feb7134 100644--- a/packages/server/src/server-factory.test.ts+++ b/packages/server/src/server-factory.test.ts@@ -6390,7 +6390,7 @@ describe('createServer() — disk-event reconcile with an absent reconciled base}}, 60_000);- test('a parked WIP restored after a branch round trip is saved by the next store instead of being merged away', async () => {+ test('unsaved WIP survives a branch round trip and is saved by the next store instead of being merged away', async () => {const projectDir = await realpath(mkdtempSync(join(tmpdir(), 'ok-reconcile-park-store-')));const git = simpleGit(projectDir);await git.init(['--initial-branch=main']);@@ -6443,7 +6443,10 @@ describe('createServer() — disk-event reconcile with an absent reconciled baseexpect(source.toString()).toBe(withWip);await git.checkout('feature');- await vi.waitFor(() => expect(source.toString()).toBe(featureContent), {+ const featureWithWip =+ '# Park store target\n\nFeature branch body.\n\nUnsaved WIP.\n\nTail.\n';+ expect(featureWithWip).not.toBe(featureContent);+ await vi.waitFor(() => expect(source.toString()).toBe(featureWithWip), {timeout: 15_000,interval: 25,});@@ -6468,7 +6471,7 @@ describe('createServer() — disk-event reconcile with an absent reconciled base}}, 60_000);- test('a branch-switch reset rescues unflushed WIP on an absent-base doc before overwriting with disk content', async () => {+ test("a branch switch that leaves an absent-base doc's file unchanged keeps its unsaved typing live", async () => {const projectDir = await realpath(mkdtempSync(join(tmpdir(), 'ok-reconcile-bs-rescue-')));const git = simpleGit(projectDir);await git.init(['--initial-branch=main']);@@ -6531,40 +6534,23 @@ describe('createServer() — disk-event reconcile with an absent reconciled baseexpect(wipText).not.toBe(diskContent);const warnSpy = vi.spyOn(getLogger('server'), 'warn');+ const switched = vi.spyOn(server.cc1Broadcaster, 'emitBranchSwitched');try {await git.checkout('feature');+ await vi.waitFor(() => expect(switched).toHaveBeenCalledWith('feature'), {+ timeout: 15_000,+ interval: 25,+ });- await vi.waitFor(- () =>- expect(serverDoc.getText('source').toString()).not.toContain('Unflushed WIP paragraph'),- { timeout: 15_000, interval: 25 },- );- expect(serverDoc.getText('source').toString()).toBe(diskContent);- expect(server.durabilityState.getReconciledBase(docName)).toBe(diskContent);+ expect(serverDoc.getText('source').toString()).toBe(wipText);expect(serverDoc.getMap('lifecycle').get('status')).toBeUndefined();-- await vi.waitFor(- async () => {- const rescues = await listRescueCheckpoints(rig.shadow, 'feature');- const rescue = rescues.find((r) => r.docName === docName);- expect(rescue).toBeDefined();- expect(rescue?.incomingDiskSha).toBe('');- expect(rescue?.size).toBe(wipText.length);- },- { timeout: 10_000, interval: 50 },- );-- const branchSwitchRescue = (await listRescueCheckpoints(rig.shadow, 'feature')).find(- (r) => r.docName === docName,- );- const branchSwitchBody = (- await shadowGit(rig.shadow).raw('log', '-1', '--format=%B', branchSwitchRescue?.sha ?? '')- ).trim();- expect(parseCheckpoint(branchSwitchBody)?.kind).toBe('external-change-rescue');+ const rescues = await listRescueCheckpoints(rig.shadow, 'feature');+ expect(rescues.filter((r) => r.docName === docName)).toEqual([]);const warnTexts = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));expect(warnTexts.some((s) => s.includes('skipped parking'))).toBe(true);} finally {+ switched.mockRestore();warnSpy.mockRestore();}diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex a79f8be7f..f50626826 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -1,7 +1,9 @@import { type SpawnSyncReturns, spawnSync } from 'node:child_process';import { randomUUID } from 'node:crypto';import {+ accessSync,existsSync,+ constants as fsConstants,lstatSync,readFileSync,realpathSync,@@ -9,7 +11,7 @@ import {writeFileSync,} from 'node:fs';import { homedir } from 'node:os';-import { basename, dirname, join, relative, resolve, sep } from 'node:path';+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';import type { Document, Extension } from '@hocuspocus/server';import { Hocuspocus, IncomingMessage, MessageType } from '@hocuspocus/server';import {@@ -144,6 +146,8 @@ import { DocNoticeLedger } from './doc-notices.ts';import {DocumentDurabilityState,type StaleExternalWriteConflict,+ type WrittenThrough,+ writtenThroughOf,} from './document-durability-state.ts';import {createReconnectRefreshExtension,@@ -178,6 +182,7 @@ import {assertNeverDiskEvent,contentHash,type DiskEvent,+ getMarkdownEventFacts,getMarkdownRemovalCurrentness,hasAdmittedMarkdownFile,type NativeWatcherBackend,@@ -252,10 +257,13 @@ import { createMergeHistoryRecorder, type MergeHistoryWriter } from './merge-hisimport {incrementBatch,incrementBranchSwitch,+ incrementBranchSwitchRecheckShortfalls,incrementConflict,incrementDiskAuthoritativeIngest,incrementDiskAuthoritativeIngestApplyFailures,incrementDiskAuthoritativeIngestUnrescued,+ incrementOutsideRenameClaimFailures,+ incrementOutsideRenameRecordFailures,incrementPark,incrementReceiptIntakeSkip,incrementRecentlyRemovedDocsEviction,@@ -265,6 +273,7 @@ import {incrementRescueBufferWriteFailures,incrementRescueCheckpointWriteFailures,incrementUpstreamImport,+ recordVanishOutcome,setRecentlyRemovedDocsSize,} from './metrics.ts';import { destroyParsePool } from './parse-pool.ts';@@ -283,10 +292,12 @@ import { runRemovalRedirectGuard } from './removal-redirect-guard.ts';import { loadRemovedDocsJournal, saveRemovedDocsJournal } from './removed-docs-journal.ts';import {gcRenameLog,+ getOrLoadRenameLogIndex,loadRenameLogIndex,setRenameLogIndex,sweepLazyPopOrphans,} from './rename-log.ts';+import { followRenameRecords } from './rename-records.ts';import {acquireServerAuthority,contentScopeContainsPath,@@ -324,12 +335,12 @@ import {commitUpstreamImport,configureShadowGc,destroyShadowRepo,+ FILE_SYSTEM_WRITER,initShadowRepo,isShadowExcludesDegraded,OK_GENERATOR_WRITER,type ParkableDoc,parkBranch,- readParkedState,SERVICE_WRITER,type ShadowHandle,type ShadowRef,@@ -351,7 +362,15 @@ import { createSyncHandshakeSpanExtension } from './sync-handshake-span-extensioimport { initTelemetry, shutdownTelemetry, withSpan } from './telemetry.ts';import { trustSystemCertificates } from './trust-system-ca.ts';import { cleanupOrphanUploadTempfiles } from './upload-streaming.ts';-import { type WatcherClock, watcherClock } from './watcher-clock.ts';+import {+ type RecentCreate,+ VANISH_HOLD_LIMIT_MS,+ VANISH_OVERDUE_FAULT_LIMIT,+ VANISH_RECHECK_DELAY_MS,+ type VanishedDocument,+ VanishedDocuments,+} from './vanished-documents.ts';+import { type WatcherClock, type WatcherTimer, watcherClock } from './watcher-clock.ts';import { FRESHNESS_BASE_INTERVAL_MS } from './watcher-freshness.ts';export interface ServerOptions {@@ -476,6 +495,10 @@ export function observeShutdownDocumentRetirements(export const SHADOW_FANOUT_WARMUP_MS = 3000;+export const BRANCH_SWITCH_FOLLOW_UP_LIMIT = 3;++export const BRANCH_SWITCH_FOLLOW_UP_DELAY_MS = 5_000;+const PARK_SNAPSHOT_ORIGIN = (() => {const ctx = Object.freeze({ origin: 'park-snapshot', paired: true as const });return Object.freeze({@@ -651,15 +674,29 @@ export function createServer(options: ServerOptions): ServerInstance {const deleteReconciledBase = (docName: string) => durabilityState.deleteReconciledBase(docName);const switchReconciledBaseScope = (branch: string) =>durabilityState.switchReconciledBaseScope(branch);- const setBatchInProgress = (value: boolean) => durabilityState.setBatchInProgress(value);- const setBatchInProgressAndDrain = (value: boolean) => {- setBatchInProgress(value);- if (!value) {- void persistence.flushDeferredStores('within-branch').catch((err) => {- log.error({ err }, '[persistence] deferred store drain failed after batch');- });+ const vanishedDocuments = new VanishedDocuments();+ const holdBatch = (owner: string): void => durabilityState.holdBatch(owner);+ const releaseBatchHold = (owner: string): boolean => durabilityState.releaseBatch(owner);+ const finishBatch = async (): Promise<void> => {+ try {+ await drainEventBuffer();+ } finally {+ disposeBufferedRemovalScopes();}+ await persistence.flushDeferredStores('within-branch');};+ const batchFlagFor =+ (owner: string) =>+ (value: boolean): void => {+ if (value) {+ holdBatch(owner);+ return;+ }+ if (!releaseBatchHold(owner)) return;+ void finishBatch().catch((err: unknown) => {+ log.error({ err, owner }, '[batch] draining after the batch failed');+ });+ };const isBatchInProgress = () => durabilityState.isBatchInProgress();const conflicts = new ConflictAuthority({@@ -1289,6 +1326,7 @@ export function createServer(options: ServerOptions): ServerInstance {getShadow: () => shadowRef?.current,isReady: () => readyForNotices,signal: () => cc1Broadcaster?.signal('sync-status'),+ isHeld: (docName) => vanishedDocuments.has(docName),});const offlineRemovalsReconciled = Promise.withResolvers<void>();@@ -2602,6 +2640,13 @@ export function createServer(options: ServerOptions): ServerInstance {};hocuspocus.configuration.extensions.push(systemDocBroadcastGuard);+ const renameCarryRetirement: Extension = {+ async afterUnloadDocument({ documentName }) {+ durabilityState.endRenameCarry(documentName);+ },+ };+ hocuspocus.configuration.extensions.push(renameCarryRetirement);+const apiExtension = createApiExtension({mergeHistoryWriter: options.mergeHistoryWriter,docNotices,@@ -2690,7 +2735,7 @@ export function createServer(options: ServerOptions): ServerInstance {onAgentWrite: options.onAgentWrite,getSyncEngine: () => syncEngine,conflicts,- setBatchInProgress: setBatchInProgressAndDrain,+ setBatchInProgress: batchFlagFor('conflict-resolve'),refreshDocumentsFromDisk,localOpCliArgs,authStreamHeartbeatMs,@@ -3027,6 +3072,580 @@ export function createServer(options: ServerOptions): ServerInstance {return true;};+ const settledVanishEvents = new WeakSet<DiskEvent>();+ const vanishClock = options.watcherClock ?? watcherClock();+ let vanishRecheckTimer: WatcherTimer | null = null;+ let vanishRecheckRunning = false;++ const holdVanished = (entry: VanishedDocument): void => {+ vanishedDocuments.hold(entry);+ durabilityState.holdStores(entry.docName);+ };++ const reportedUnreadableReturns = new Set<string>();+ const overdueFaults = new Map<string, number>();++ const releaseVanished = (docName: string): void => {+ vanishedDocuments.release(docName);+ overdueFaults.delete(docName);+ reportedUnreadableReturns.delete(docName);+ durabilityState.releaseStores(docName);+ };++ let branchSwitchFollowUpTimer: WatcherTimer | null = null;+ let branchSwitchFollowUpGeneration = 0;++ function supersedeBranchSwitchFollowUps(): void {+ branchSwitchFollowUpGeneration += 1;+ vanishClock.clearTimeout(branchSwitchFollowUpTimer);+ branchSwitchFollowUpTimer = null;+ }++ function followUpBranchSwitchRecheck(branch: string): void {+ supersedeBranchSwitchFollowUps();+ void runBranchSwitchFollowUp(branch, branchSwitchFollowUpGeneration, 1).catch(+ (err: unknown) => {+ log.error({ err, branch }, '[branch-switch] the follow-up re-checks stopped');+ },+ );+ }++ async function runBranchSwitchFollowUp(+ branch: string,+ generation: number,+ attempt: number,+ ): Promise<void> {+ if (!watcher || generation !== branchSwitchFollowUpGeneration) return;+ let result: RecheckResult | undefined;+ try {+ result = await watcher.recheck('full');+ } catch (err) {+ log.warn(+ { err, branch, attempt },+ `[branch-switch] follow-up re-check ${attempt} after switching to ${branch} failed`,+ );+ }+ if (generation !== branchSwitchFollowUpGeneration || result?.status === 'closed') return;+ if (result?.status === 'completed' && !result.partial) {+ log.info(+ { branch, attempt },+ `[branch-switch] follow-up re-check ${attempt} observed the whole tree after switching to ${branch}`,+ );+ return;+ }+ incrementBranchSwitchRecheckShortfalls();+ const details = {+ branch,+ attempt,+ status: result?.status ?? 'failed',+ partial: result?.partial === true,+ };+ if (attempt >= BRANCH_SWITCH_FOLLOW_UP_LIMIT) {+ log.warn(+ details,+ `[branch-switch] ${attempt} follow-up re-checks after switching to ${branch} did not observe the whole tree; open documents may keep text from the previous branch until a later re-check observes it`,+ );+ return;+ }+ log.warn(+ details,+ `[branch-switch] follow-up re-check ${attempt} after switching to ${branch} did not observe the whole tree; trying again in ${BRANCH_SWITCH_FOLLOW_UP_DELAY_MS / 1000} s`,+ );+ branchSwitchFollowUpTimer = vanishClock.setTimeout(() => {+ branchSwitchFollowUpTimer = null;+ void runBranchSwitchFollowUp(branch, generation, attempt + 1).catch((err: unknown) => {+ log.error({ err, branch }, '[branch-switch] the follow-up re-checks stopped');+ });+ }, BRANCH_SWITCH_FOLLOW_UP_DELAY_MS);+ branchSwitchFollowUpTimer.unref();+ }++ const scheduleVanishRecheck = (): void => {+ if (vanishRecheckTimer || vanishRecheckRunning || vanishedDocuments.size === 0) return;+ vanishRecheckTimer = vanishClock.setTimeout(() => {+ vanishRecheckTimer = null;+ void runVanishRecheck().catch((err: unknown) => {+ log.error({ err }, '[reconcile] the re-check loop for vanished documents failed');+ });+ }, VANISH_RECHECK_DELAY_MS);+ vanishRecheckTimer.unref();+ };++ async function runVanishRecheck(): Promise<void> {+ if (!watcher) return;+ vanishRecheckRunning = true;+ let result: RecheckResult | undefined;+ try {+ result = await watcher.recheck('metadata');+ } catch (err) {+ log.warn({ err }, '[reconcile] the re-check for vanished documents failed');+ } finally {+ vanishRecheckRunning = false;+ }+ try {+ if (vanishedDocuments.size > 0 && (result?.status !== 'completed' || result.partial)) {+ log.info(+ { status: result?.status ?? 'failed', partial: result?.partial === true },+ `[reconcile] the re-check for ${vanishedDocuments.size} vanished document(s) did not observe the whole tree; trying again`,+ );+ }+ await resolveOverdueVanishedDocuments();+ } finally {+ scheduleVanishRecheck();+ }+ }++ function pathIsOccupied(path: string): boolean {+ try {+ lstatSync(path);+ return true;+ } catch (err) {+ const code = errnoCode(err);+ if (code === 'ENOENT' || code === 'ENOTDIR') return false;+ log.warn({ err, path }, '[reconcile] could not tell whether a vanished file is gone');+ return true;+ }+ }++ type MarkdownFileProbe =+ | { readonly kind: 'present'; readonly path: string; readonly content: string }+ | { readonly kind: 'absent' }+ | { readonly kind: 'refused' }+ | { readonly kind: 'unreadable'; readonly code: string };++ function probeMarkdownFile(docName: string, path: string): MarkdownFileProbe {+ const unreadable = (err: unknown): MarkdownFileProbe => {+ const code = errnoCode(err);+ if (code === 'ENOENT' || code === 'ENOTDIR') return { kind: 'absent' };+ return { kind: 'unreadable', code: code ?? 'unknown' };+ };+ try {+ lstatSync(path);+ accessSync(path, fsConstants.R_OK);+ } catch (err) {+ const probe = unreadable(err);+ if (probe.kind === 'absent' || errnoCode(err) !== 'ELOOP') return probe;+ }+ if (!hasAdmittedMarkdownFile(docName, path, contentDir, contentFilter))+ return { kind: 'refused' };+ try {+ return { kind: 'present', path, content: readFileSync(path, 'utf-8') };+ } catch (err) {+ return unreadable(err);+ }+ }++ function probeVanishedFile(entry: VanishedDocument): MarkdownFileProbe {+ const path =+ watcher?.getFileIndex().get(entry.docName)?.canonicalPath ??+ resolveDocFilePath(entry.docName) ??+ entry.path;+ return probeMarkdownFile(entry.docName, path);+ }++ async function holdVanishedDocument(+ event: Extract<DiskEvent, { kind: 'delete' }>,+ ): Promise<boolean> {+ if (!watcher || pathIsOccupied(event.path)) return false;+ const facts = getMarkdownEventFacts(event);+ const base = getReconciledBase(event.docName);+ const hashes = new Set<string>();+ if (facts.lastHash !== undefined) hashes.add(facts.lastHash);+ if (base !== undefined) hashes.add(contentHash(base));+ const vanished = {+ docName: event.docName,+ path: event.path,+ identity: facts.identity,+ size: facts.size,+ modified: facts.modified,+ hashes,+ text: base ?? serializeDoc(event.docName) ?? undefined,+ };+ const readRecentCreate = (create: RecentCreate): string | undefined => {+ const probe = probeMarkdownFile(create.docName, create.path);+ return probe.kind === 'present' ? probe.content : undefined;+ };+ const recent = vanishedDocuments.matchRecentCreate(+ vanished,+ vanishClock.now(),+ readRecentCreate,+ );+ if (recent) {+ const probe = probeMarkdownFile(recent.create.docName, recent.create.path);+ if (probe.kind === 'present') {+ recordVanishOutcome(recent.by === 'identity' ? 'paired-identity' : 'paired-hash');+ await handleDiskEvent({+ kind: 'rename',+ oldPath: event.path,+ newPath: recent.create.path,+ oldDocName: event.docName,+ newDocName: recent.create.docName,+ content: probe.content,+ });+ return true;+ }+ log.info(+ { docName: event.docName, create: recent.create.docName, probe: probe.kind },+ `[reconcile] ${event.docName}: a recent create could not be read; holding the document instead`,+ );+ }+ holdVanished({+ ...vanished,+ afterPass: watcher.recoveryPassesStarted(),+ heldAt: vanishClock.now(),+ });+ recordVanishOutcome('pending');+ log.info(+ { docName: event.docName },+ `[reconcile] ${event.docName}: its file vanished; it stays open until a re-check of the whole tree, in case it was moved`,+ );+ scheduleVanishRecheck();+ return true;+ }++ const flushReleasedStores = (): void => {+ if (isBatchInProgress()) return;+ void persistence.flushDeferredStores('within-branch').catch((err: unknown) => {+ log.error(+ { err },+ '[persistence] deferred store drain failed after a vanished file resolved',+ );+ });+ };++ async function takeReturnedFile(+ entry: VanishedDocument,+ probe: Extract<MarkdownFileProbe, { kind: 'present' }>,+ ): Promise<void> {+ releaseVanished(entry.docName);+ try {+ recordVanishOutcome('recreated');+ log.info(+ { docName: entry.docName },+ `[reconcile] ${entry.docName}: its file is back; taking it in as an update`,+ );+ await onDiskEvent({+ kind: 'update',+ path: probe.path,+ docName: entry.docName,+ content: probe.content,+ });+ } finally {+ flushReleasedStores();+ }+ }++ async function standVanishedDelete(+ entry: VanishedDocument,+ outcome: 'deleted' | 'unconfirmed',+ ): Promise<void> {+ persistence.discardDeferredStore(entry.docName, { kind: 'deleted-outside' });+ releaseVanished(entry.docName);+ recordVanishOutcome(outcome);+ const deleteEvent: DiskEvent = { kind: 'delete', path: entry.path, docName: entry.docName };+ settledVanishEvents.add(deleteEvent);+ await onDiskEvent(deleteEvent);+ }++ function keepUnreadableHeld(entry: VanishedDocument, code: string): void {+ if (reportedUnreadableReturns.has(entry.docName)) return;+ reportedUnreadableReturns.add(entry.docName);+ log.warn(+ { docName: entry.docName, code },+ `[reconcile] ${entry.docName}: a file is at its path but cannot be read (${code}); it stays held until it can be read or the hold limit passes`,+ );+ }++ interface VanishStep {+ action: string;+ }++ function reportVanishFault(+ entry: VanishedDocument,+ step: VanishStep,+ err: unknown,+ overdueAttempt?: number,+ ): void {+ const stillHeld = vanishedDocuments.has(entry.docName);+ const attempt =+ overdueAttempt === undefined+ ? ''+ : ` (attempt ${overdueAttempt} of ${VANISH_OVERDUE_FAULT_LIMIT} past the hold limit)`;+ log.error(+ { err, docName: entry.docName, action: step.action, stillHeld, overdueAttempt },+ stillHeld+ ? `[reconcile] ${entry.docName}: ${step.action} failed with an internal error${attempt}; it is still held`+ : `[reconcile] ${entry.docName}: ${step.action} failed with an internal error${attempt}; its hold had already ended`,+ );+ }++ function endHoldAfterOverdueFaults(entry: VanishedDocument, attempts: number): void {+ releaseVanished(entry.docName);+ flushReleasedStores();+ log.error(+ { docName: entry.docName, attempts },+ `[reconcile] ${entry.docName}: ended its hold after ${attempts} failed attempts past the hold limit; its deferred saves were released to run as normal saves`,+ );+ }++ async function settleVanishedDocuments(pass: number, whole: boolean): Promise<void> {+ if (!whole) return;+ for (const entry of vanishedDocuments.dueAfter(pass)) {+ const step: VanishStep = { action: 'checking its path' };+ try {+ await settleVanishedDocument(entry, step);+ } catch (err) {+ reportVanishFault(entry, step, err);+ }+ }+ }++ async function settleVanishedDocument(entry: VanishedDocument, step: VanishStep): Promise<void> {+ const probe = probeVanishedFile(entry);+ switch (probe.kind) {+ case 'present':+ step.action = 'taking its returned file in';+ await takeReturnedFile(entry, probe);+ return;+ case 'unreadable':+ keepUnreadableHeld(entry, probe.code);+ return;+ case 'absent':+ case 'refused':+ step.action = 'applying the delete';+ log.info(+ { docName: entry.docName, probe: probe.kind },+ `[reconcile] ${entry.docName}: no move found after a re-check of the whole tree; the delete stands`,+ );+ await standVanishedDelete(entry, 'deleted');+ return;+ default: {+ const unhandled: never = probe;+ throw new Error(`unhandled file probe: ${JSON.stringify(unhandled)}`);+ }+ }+ }++ async function resolveOverdueVanishedDocuments(): Promise<void> {+ for (const entry of vanishedDocuments.heldBefore(vanishClock.now() - VANISH_HOLD_LIMIT_MS)) {+ const step: VanishStep = { action: 'resolving its hold at the limit' };+ try {+ await resolveOverdueVanishedDocument(entry, step);+ } catch (err) {+ if (!vanishedDocuments.has(entry.docName)) {+ reportVanishFault(entry, step, err);+ continue;+ }+ const attempts = (overdueFaults.get(entry.docName) ?? 0) + 1;+ overdueFaults.set(entry.docName, attempts);+ reportVanishFault(entry, step, err, attempts);+ if (attempts >= VANISH_OVERDUE_FAULT_LIMIT) endHoldAfterOverdueFaults(entry, attempts);+ }+ }+ }++ async function resolveOverdueVanishedDocument(+ entry: VanishedDocument,+ step: VanishStep,+ ): Promise<void> {+ const limit = `${VANISH_HOLD_LIMIT_MS / 1000} s`;+ let probe: MarkdownFileProbe | undefined;+ try {+ probe = probeVanishedFile(entry);+ } catch (err) {+ log.error(+ { err, docName: entry.docName, limitMs: VANISH_HOLD_LIMIT_MS },+ `[reconcile] ${entry.docName}: checking its path at the hold limit failed with an internal error; the delete stands as at any hold limit`,+ );+ }+ switch (probe?.kind) {+ case undefined:+ break;+ case 'present':+ step.action = 'taking its returned file in';+ await takeReturnedFile(entry, probe);+ return;+ case 'absent':+ log.warn(+ { docName: entry.docName, probe: probe.kind, limitMs: VANISH_HOLD_LIMIT_MS },+ `[reconcile] ${entry.docName}: its file is gone and no re-check observed the whole tree within ${limit}; the delete stands and unsaved typing is in its history`,+ );+ break;+ case 'unreadable':+ log.warn(+ {+ docName: entry.docName,+ probe: probe.kind,+ code: probe.code,+ limitMs: VANISH_HOLD_LIMIT_MS,+ },+ `[reconcile] ${entry.docName}: a file at its path still cannot be read (${probe.code}) after ${limit}; the hold ends, the document closes and unsaved typing is in its history`,+ );+ break;+ case 'refused':+ log.warn(+ { docName: entry.docName, probe: probe.kind, limitMs: VANISH_HOLD_LIMIT_MS },+ `[reconcile] ${entry.docName}: the entry at its path is still not an admitted Markdown file after ${limit}; the hold ends, the document closes and unsaved typing is in its history`,+ );+ break;+ default: {+ const unhandled: never = probe;+ throw new Error(`unhandled file probe: ${JSON.stringify(unhandled)}`);+ }+ }+ step.action = 'applying the delete at the hold limit';+ await standVanishedDelete(entry, 'unconfirmed');+ }++ function followRecordsAcrossRename(+ oldDocName: string,+ newDocName: string,+ newPath: string,+ ): void {+ const branch = getStorageBranch() ?? 'main';+ const move = { from: oldDocName, to: newDocName, toFile: `${newDocName}${extname(newPath)}` };+ const writer = {+ writerId: FILE_SYSTEM_WRITER.id,+ displayName: FILE_SYSTEM_WRITER.name,+ colorSeed: FILE_SYSTEM_WRITER.id,+ };+ followRenameRecords({+ moves: [move],+ kind: 'file',+ branch,+ writer,+ shadow: undefined,+ notices: docNotices,+ });+ const shadow = shadowRef.current;+ if (!shadow) return;+ void recordOutsideRenameInHistory(shadow, branch, move, writer);+ }++ async function readWriterHeads(shadow: ShadowHandle, branch: string): Promise<string[]> {+ try {+ const raw = await shadowGit(shadow).raw(+ 'for-each-ref',+ '--sort=-committerdate',+ '--format=%(objectname)',+ `refs/wip/${branch}/`,+ );+ return raw+ .split('\n')+ .map((line) => line.trim())+ .filter((sha) => /^[0-9a-f]{40}$/.test(sha));+ } catch (err) {+ log.warn(+ { err, branch },+ "[reconcile] rename: could not read the writers' history heads; the move is recorded without them",+ );+ return [];+ }+ }++ async function recordOutsideRenameInHistory(+ shadow: ShadowHandle,+ branch: string,+ move: { from: string; to: string; toFile: string },+ writer: { writerId: string; displayName: string; colorSeed: string },+ ): Promise<void> {+ const anchors = await readWriterHeads(shadow, branch);+ let appended: number;+ try {+ appended = followRenameRecords({+ moves: [move],+ kind: 'file',+ branch,+ writer,+ shadow,+ notices: undefined,+ anchors,+ });+ } catch (err) {+ incrementOutsideRenameRecordFailures();+ log.warn(+ { err, oldDocName: move.from, newDocName: move.to },+ `[reconcile] rename: could not write the rename-log entry for ${move.from} -> ${move.to}; history before the move will not show under the new name`,+ );+ return;+ }+ if (appended === 0) return;+ let flushError: unknown;+ try {+ await persistence.flushContributors();+ } catch (err) {+ flushError = err;+ }+ const recorded = getOrLoadRenameLogIndex(shadow.gitDir).byTo.get(move.to);+ if (recorded !== undefined && recorded.commitSha === '') {+ incrementOutsideRenameClaimFailures();+ log.warn(+ { err: flushError, oldDocName: move.from, newDocName: move.to },+ `[reconcile] rename: wrote the rename-log entry for ${move.from} -> ${move.to}, but no commit claimed it yet; a later commit by the file-system writer claims it, and the next start drops it if none does`,+ );+ return;+ }+ if (flushError !== undefined) {+ log.warn(+ { err: flushError, oldDocName: move.from, newDocName: move.to },+ '[reconcile] rename: the commit after recording the move failed',+ );+ }+ }++ async function carryLiveTextAcrossRename(+ newDocName: string,+ newPath: string,+ base: string,+ live: string,+ diskContent: string,+ ): Promise<boolean> {+ let connection: Awaited<ReturnType<Hocuspocus['openDirectConnection']>> | undefined;+ try {+ connection = await hocuspocus.openDirectConnection(newDocName);+ applyToDoc(newDocName, live);+ setReconciledBase(newDocName, base);+ if (diskContent !== base) {+ await handleDiskEvent({+ kind: 'update',+ path: newPath,+ docName: newDocName,+ content: diskContent,+ });+ }+ log.info({ newDocName }, `[reconcile] rename: unsaved typing carried into ${newDocName}`);+ return true;+ } catch (err) {+ log.error(+ { err, newDocName },+ `[reconcile] rename: could not carry unsaved typing into ${newDocName}; it is in the rename checkpoint`,+ );+ return false;+ } finally {+ await connection?.disconnect();+ }+ }++ function tombstoneResidentsResolvingIntoPrivateState(branch: string): void {+ for (const [docName, document] of hocuspocus.documents) {+ if (isReservedForUserTree(docName)) continue;+ if (document.getMap('lifecycle').get('status') !== undefined) continue;+ try {+ const filePath = safeContentPath(docName, contentDir);+ if (!existsSync(filePath)) continue;+ if (!canonicalContentPathIsRefused(filePath, realpathSync(filePath), contentDir)) continue;+ rescueUnflushedEditsBeforeTeardown(docName, branch, 'branch-switch');+ document.getMap('lifecycle').set('status', 'deleted-upstream');+ log.warn(+ { docName, branch },+ `[branch-switch] tombstone: ${docName} resolves outside the content dir or into private state on ${branch}`,+ );+ } catch (err) {+ log.error({ err, docName }, `[branch-switch] could not check where ${docName} resolves`);+ }+ }+ }+const rescueUnflushedEditsBeforeTeardown = (docName: string,branch: string,@@ -3387,6 +4006,63 @@ export function createServer(options: ServerOptions): ServerInstance {try {switch (event.kind) {case 'create': {+ const facts = getMarkdownEventFacts(event);+ const createdHash = contentHash(event.content);+ const paired = vanishedDocuments.matchCreate({+ docName: event.docName,+ identity: facts.identity,+ size: facts.size,+ modified: facts.modified,+ hash: createdHash,+ content: event.content,+ });+ if (paired) {+ releaseVanished(paired.vanished.docName);+ if (paired.by === 'same-name') {+ recordVanishOutcome('recreated');+ log.info(+ { docName: event.docName },+ `[reconcile] ${event.docName}: its file came back; taking it in as an update`,+ );+ await handleDiskEvent({+ kind: 'update',+ path: event.path,+ docName: event.docName,+ content: event.content,+ });+ flushReleasedStores();+ break;+ }+ const carry = durabilityState.beginRenameCarry(paired.vanished.docName);+ try {+ persistence.discardDeferredStore(paired.vanished.docName, {+ kind: 'renamed-outside',+ to: event.docName,+ carry,+ });+ recordVanishOutcome(paired.by === 'identity' ? 'paired-identity' : 'paired-hash');+ await handleDiskEvent({+ kind: 'rename',+ oldPath: paired.vanished.path,+ newPath: event.path,+ oldDocName: paired.vanished.docName,+ newDocName: event.docName,+ content: event.content,+ });+ } finally {+ durabilityState.abandonRenameCarry(paired.vanished.docName);+ }+ break;+ }+ vanishedDocuments.rememberCreate({+ docName: event.docName,+ path: event.path,+ identity: facts.identity,+ size: facts.size,+ modified: facts.modified,+ hash: createdHash,+ at: vanishClock.now(),+ });log.info({ docName: event.docName }, `[reconcile] create: ${event.docName}`);reviveFrozenResident(event.docName, event.content);await derivedDocumentIndex.recordDiskUpsert(event.docName, event.content);@@ -3416,6 +4092,15 @@ export function createServer(options: ServerOptions): ServerInstance {);return;}+ if (+ namespaceCurrent &&+ residentCurrent &&+ removal.document &&+ !settledVanishEvents.has(event) &&+ (await holdVanishedDocument(event))+ ) {+ return;+ }if (namespaceCurrent) {dissolveNonGitConflicts(docName);commentDocHooksRef.current?.deleted(docName);@@ -3430,7 +4115,10 @@ export function createServer(options: ServerOptions): ServerInstance {true,): false;- if (residentCurrent) document?.getMap('lifecycle').set('status', 'deleted-upstream');+ if (residentCurrent) {+ document?.getMap('lifecycle').set('status', 'deleted-upstream');+ durabilityState.endRenameCarry(docName);+ }if (namespaceCurrent) deleteReconciledBase(docName);if (namespaceCurrent) await derivedDocumentIndex.recordDiskDelete(docName);if (!removal.namespaceCurrent() && !removal.residentCurrent()) {@@ -3487,8 +4175,16 @@ export function createServer(options: ServerOptions): ServerInstance {const removal =preparedRemoval ?? beginRemoval(oldDocName, getMarkdownRemovalCurrentness(event));bufferedRemovalScopes.delete(event);+ durabilityState.beginRenameCarry(oldDocName);+ let carriedThrough: WrittenThrough | null = null;try {const document = removal.document;+ const residentBeforeRename = removal.residentCurrent() && document ? document : null;+ const liveBeforeRename = residentBeforeRename ? serializeDoc(oldDocName) : null;+ const textBeforeRename = residentBeforeRename+ ? writtenThroughOf(residentBeforeRename)+ : null;+ const baseBeforeRename = getReconciledBase(oldDocName);const freezeAsRenamed = (doc: Document): void => {const lifecycle = doc.getMap('lifecycle');lifecycle.set('status', 'renamed');@@ -3535,6 +4231,21 @@ export function createServer(options: ServerOptions): ServerInstance {if (lateResident) freezeAsRenamed(lateResident);reviveFrozenResident(newDocName, content);scheduleIndexRegeneration(newDocName);+ if (removal.namespaceCurrent()) {+ followRecordsAcrossRename(oldDocName, newDocName, event.newPath);+ }+ if (liveBeforeRename !== null && baseBeforeRename !== undefined) {+ const carried =+ liveBeforeRename === baseBeforeRename ||+ (await carryLiveTextAcrossRename(+ newDocName,+ event.newPath,+ baseBeforeRename,+ liveBeforeRename,+ content,+ ));+ if (carried) carriedThrough = textBeforeRename;+ }const retired = removal.residentCurrent() && document ? document : lateResident;if (retired) {const closedConnections = retired.getConnectionsCount();@@ -3576,6 +4287,7 @@ export function createServer(options: ServerOptions): ServerInstance {);scheduleIndexRegenerationAfterRemoval(oldDocName);} finally {+ durabilityState.settleRenameCarry(oldDocName, carriedThrough);removal.dispose();}break;@@ -3663,18 +4375,34 @@ export function createServer(options: ServerOptions): ServerInstance {),);}- if (isBatchInProgress()) {+ if (isBatchInProgress() || draining !== null) {eventBuffer.push(event);return;}await handleDiskEvent(event);}- async function drainEventBuffer(): Promise<void> {- const events = eventBuffer.splice(0, eventBuffer.length);- for (const event of events) {- await handleDiskEvent(event);- }+ let draining: Promise<void> | null = null;++ function drainEventBuffer(): Promise<void> {+ if (draining) return draining;+ if (eventBuffer.length === 0) return Promise.resolve();+ const done = Promise.withResolvers<void>();+ draining = done.promise;+ void (async () => {+ try {+ while (eventBuffer.length > 0) {+ const events = eventBuffer.splice(0, eventBuffer.length);+ for (const event of events) await handleDiskEvent(event);+ }+ done.resolve();+ } catch (err) {+ done.reject(err);+ } finally {+ draining = null;+ }+ })();+ return done.promise;}function disposeBufferedRemovalScopes(): void {@@ -3994,6 +4722,24 @@ export function createServer(options: ServerOptions): ServerInstance {phaseErrors.push({ phase: 'mutation-drain', error: String(err) });log.error({ err }, '[server] shutdown mutation drain failed');}+ vanishClock.clearTimeout(vanishRecheckTimer);+ vanishRecheckTimer = null;+ supersedeBranchSwitchFollowUps();+ for (const entry of vanishedDocuments.all()) {+ persistence.discardDeferredStore(entry.docName, { kind: 'shutdown' });+ rescueUnflushedEditsBeforeTeardown(+ entry.docName,+ getStorageBranch() ?? 'main',+ 'delete',+ true,+ );+ recordVanishOutcome('shutdown');+ durabilityState.releaseStores(entry.docName);+ }+ vanishedDocuments.clear();+ durabilityState.endAllRenameCarries();+ reportedUnreadableReturns.clear();+ overdueFaults.clear();documentAdmissionClosed = true;disposeBufferedRemovalScopes();for (const removals of activeRemovals.values()) {@@ -4838,6 +5584,7 @@ export function createServer(options: ServerOptions): ServerInstance {startWatcher(canonicalContentDir, onDiskEvent, contentFilter, {onRawBatch,onRecoveryComplete: () => derivedDocumentIndex.recordInventoryReconciled(),+ onRecoveryPassCompleted: (pass, whole) => settleVanishedDocuments(pass, whole),nativeBackend: options.watcherBackend,clock: options.watcherClock,freshnessIntervalMs:@@ -4950,7 +5697,7 @@ export function createServer(options: ServerOptions): ServerInstance {hocuspocus.flushPendingStores();await persistence.flushPendingGitCommit();- setBatchInProgress(true);+ holdBatch('head-watcher');releaseHeadBatchAdmission();releaseHeadBatchAdmission = durabilityState.holdWriteAdmission();@@ -5016,7 +5763,6 @@ export function createServer(options: ServerOptions): ServerInstance {);if (info.batchKind === 'within-branch') {- setBatchInProgress(false);try {try {await drainEventBuffer();@@ -5047,7 +5793,7 @@ export function createServer(options: ServerOptions): ServerInstance {}} finally {try {- await persistence.flushDeferredStores('within-branch');+ if (releaseBatchHold('head-watcher')) await finishBatch();} finally {releaseHeadBatchAdmission();}@@ -5059,9 +5805,9 @@ export function createServer(options: ServerOptions): ServerInstance {}} else {incrementBranchSwitch();- eventBuffer.splice(0, eventBuffer.length);- disposeBufferedRemovalScopes();- let deferredStoresFlushed = false;+ supersedeBranchSwitchFollowUps();+ let batchReleased = false;+ let switchPassFellShort = false;let branchTransition: DerivedDocumentIndexBranchTransition | undefined;try {switchReconciledBaseScope(newBranch);@@ -5102,58 +5848,6 @@ export function createServer(options: ServerOptions): ServerInstance {);}- for (const [docName, document] of hocuspocus.documents) {- if (isReservedForUserTree(docName)) continue;- try {- const filePath = safeContentPath(docName, contentDir);- if (!existsSync(filePath)) {- rescueUnflushedEditsBeforeTeardown(docName, newBranch, 'branch-switch');-- const lifecycleMap = document.getMap('lifecycle');- lifecycleMap.set('status', 'deleted-upstream');- log.info(- { docName, branch: newBranch },- `[branch-switch] tombstone: ${docName} (not on ${newBranch})`,- );- continue;- }-- if (canonicalContentPathIsRefused(filePath, realpathSync(filePath), contentDir)) {- rescueUnflushedEditsBeforeTeardown(docName, newBranch, 'branch-switch');- document.getMap('lifecycle').set('status', 'deleted-upstream');- log.warn(- { docName, branch: newBranch },- `[branch-switch] tombstone: ${docName} resolves outside the content dir or into private state on ${newBranch}`,- );- continue;- }- const diskContent = readFileSync(filePath, 'utf-8');- if (getReconciledBase(docName) === undefined) {- const ours = serializeDoc(docName) ?? '';- if (ours !== '' && ours !== diskContent) {- rescueUnflushedEditsBeforeTeardown(docName, newBranch, 'branch-switch', true);- }- }- const revival = reviveFrozenResident(docName, diskContent);- if (revival === 'failed') {- log.error(- { docName },- `[branch-switch] failed to reset ${docName}: it stays frozen`,- );- continue;- }- if (revival === 'not-frozen') applyToDoc(docName, diskContent);- setReconciledBase(docName, diskContent);- log.info({ docName }, `[branch-switch] reset: ${docName}`);- } catch (e) {- log.error({ err: e, docName }, `[branch-switch] failed to reset ${docName}`);- }- }-- log.info(- { branch: newBranch, docCount: hocuspocus.documents.size },- `[branch-switch] loaded branch ${newBranch} (${hocuspocus.documents.size} docs)`,- );try {await derivedDocumentIndex.settleBranchFromDisk(branchTransition);} catch (err) {@@ -5164,110 +5858,30 @@ export function createServer(options: ServerOptions): ServerInstance {);}- if (shadowRef.current && info.batchKind === 'cross-branch') {- let restoredCount = 0;- for (const [docName] of hocuspocus.documents) {- if (isReservedForUserTree(docName)) continue;- try {- const parked = await readParkedState(- shadowRef.current,- newBranch,- SERVICE_WRITER.id,- docName,- );- if (!parked) continue;- const parkedMarkdown = parked.markdown.trim();- const parkedBase = parked.diskSnapshot.trim();- if (parkedMarkdown === parkedBase) continue;-- const currentDisk = getReconciledBase(docName);- if (!currentDisk) continue;-- const outcome = reconcile({- docName,- base: parkedBase,- ours: parkedMarkdown,- theirs: currentDisk,- });-- reportInsertDedupSkipped(docName, outcome, parkedMarkdown, currentDisk);- reportReconcileCheckFailed(docName, outcome, 'branch-switch');-- switch (outcome.kind) {- case 'merged':- case 'clean':- applyToDoc(docName, outcome.newContent);- setReconciledBase(docName, currentDisk);- restoredCount++;- break;- case 'both-kept': {- applyToDoc(docName, outcome.newContent);- setReconciledBase(docName, currentDisk);- mergeHistory.bothKept(- docName,- { ours: parked.markdown, theirs: currentDisk },- outcome.kept,- );- reportReconcileBothKept(docName, outcome.kept, 'branch-switch');- restoredCount++;- break;- }- case 'noop':- break;- case 'refused': {- const refusal = outcome.reason;- switch (refusal) {- case 'too-large':- case 'check-failed': {- if (- await mergeHistory.keptLive(- docName,- { side: 'ours', bytes: parked.markdown },- refusal,- )- ) {- reportReconcileKeptLive(docName, refusal, 'branch-switch');- break;- }- log.warn(- { docName, reason: refusal, branch: newBranch },- `[branch-switch] parked WIP not restored for ${docName} (reconcile refused: ${refusal}); it stays parked`,- );- break;- }- case 'conflict-markers':- case 'no-base':- log.warn(- { docName, reason: refusal, branch: newBranch },- `[branch-switch] parked WIP not restored for ${docName} (reconcile refused: ${refusal})`,- );- break;- default: {- const unhandled: never = refusal;- log.warn(- { docName, reason: String(unhandled), branch: newBranch },- `[branch-switch] parked WIP not restored for ${docName} (reconcile refused: ${String(unhandled)})`,- );- break;- }- }- break;- }- }- } catch (e) {- log.error(- { err: e, docName },- `[branch-switch] restore WIP failed for ${docName}`,- );- }- }- if (restoredCount > 0) {- log.info(- { count: restoredCount, branch: newBranch },- `[branch-switch] restored ${restoredCount} parked docs on ${newBranch}`,+ try {+ await drainEventBuffer();+ const switchPass = await watcher?.recheck('full');+ if (switchPass && (switchPass.status !== 'completed' || switchPass.partial)) {+ switchPassFellShort = true;+ incrementBranchSwitchRecheckShortfalls();+ log.warn(+ {+ branch: newBranch,+ status: switchPass.status,+ partial: switchPass.partial === true,+ },+ `[branch-switch] the re-check after switching to ${newBranch} did not observe the whole tree; another one runs once the switch ends`,);}+ await drainEventBuffer();+ } finally {+ disposeBufferedRemovalScopes();}+ tombstoneResidentsResolvingIntoPrivateState(newBranch);+ log.info(+ { branch: newBranch, docCount: hocuspocus.documents.size },+ `[branch-switch] loaded branch ${newBranch} (${hocuspocus.documents.size} docs)`,+ );if (info.oldBranch?.startsWith('detached-') && shadowRef.current) {try {@@ -5297,17 +5911,14 @@ export function createServer(options: ServerOptions): ServerInstance {}}- setBatchInProgress(false);- await persistence.flushDeferredStores('discard-stale');- deferredStoresFlushed = true;+ batchReleased = true;+ if (releaseBatchHold('head-watcher')) await finishBatch();cc1Broadcaster?.emitBranchSwitched(newBranch);+ if (switchPassFellShort) followUpBranchSwitchRecheck(newBranch);} finally {try {derivedDocumentIndex.abortBranchSwitch(branchTransition);- if (!deferredStoresFlushed) {- setBatchInProgress(false);- await persistence.flushDeferredStores('discard-stale');- }+ if (!batchReleased && releaseBatchHold('head-watcher')) await finishBatch();} finally {releaseHeadBatchAdmission();}@@ -5408,7 +6019,7 @@ export function createServer(options: ServerOptions): ServerInstance {detectGhAccounts: options.detectGhAccounts,tokenStore: options.tokenStore,checkPushPermissionFn: options.checkPushPermissionFn,- setBatchInProgress: setBatchInProgressAndDrain,+ setBatchInProgress: batchFlagFor('sync-engine'),onStateChange: (state) => {log.info({ state }, `[sync] state → ${state}`);},diff --git a/packages/server/src/timeline-query.ts b/packages/server/src/timeline-query.tsindex 66b0c7e79..f24a70bfc 100644--- a/packages/server/src/timeline-query.ts+++ b/packages/server/src/timeline-query.ts@@ -139,7 +139,7 @@ function matchesAuthor(entry: TimelineEntry, authors: string[]): boolean {*/function filterEntriesByOkActorDocs(entries: ParsedEntry[],- chain: Array<{ path: string; renameCommit: string | null }>,+ chain: Array<{ path: string; renameCommit: string | null; anchors?: readonly string[] }>,predecessorAncestors: Array<Set<string> | null>,): ParsedEntry[] {if (entries.length === 0) return entries;@@ -174,7 +174,7 @@ function filterEntriesByOkActorDocs(async function filterEntriesByChain<E extends { sha: string }>(shadow: ShadowHandle,entries: E[],- chain: Array<{ path: string; renameCommit: string | null }>,+ chain: Array<{ path: string; renameCommit: string | null; anchors?: readonly string[] }>,branch: string,pathCandidatesFor: (name: string) => readonly string[],cache: AncestorShaSetCache,@@ -186,7 +186,7 @@ async function filterEntriesByChain<E extends { sha: string }>(const predecessorAncestors: Array<Set<string> | null> = await Promise.all(chain.map(async (step) => {if (step.renameCommit === null) return null;- const seeds = await buildSeeds(shadow, step.renameCommit, branch, seedsCache);+ const seeds = await buildSeeds(shadow, step.renameCommit, branch, seedsCache, step.anchors);if (seeds.length === 0) return new Set<string>();return buildAncestorShaSet(shadow, seeds, branch, cache);}),@@ -222,7 +222,7 @@ async function filterEntriesByChain<E extends { sha: string }>(async function dropByteIdenticalRows(shadow: ShadowHandle,entries: ParsedEntry[],- chain: Array<{ path: string; renameCommit: string | null }>,+ chain: Array<{ path: string; renameCommit: string | null; anchors?: readonly string[] }>,predecessorAncestors: Array<Set<string> | null>,pathFor: (name: string) => string,): Promise<ParsedEntry[]> {@@ -558,7 +558,13 @@ export async function getDocumentHistory(const step = chain[i];if (step.renameCommit === null) continue;try {- const seeds = await buildSeeds(shadow, step.renameCommit, branch, seedsCache);+ const seeds = await buildSeeds(+ shadow,+ step.renameCommit,+ branch,+ seedsCache,+ step.anchors,+ );if (seeds.length === 0) continue;const predecessorPath = pathFor(step.path);const predRaw = await logSeededReachable(@@ -603,7 +609,13 @@ export async function getDocumentHistory(filterAncestors = await Promise.all(chain.map(async (step) => {if (step.renameCommit === null) return null;- const seeds = await buildSeeds(shadow, step.renameCommit, branch, seedsCache);+ const seeds = await buildSeeds(+ shadow,+ step.renameCommit,+ branch,+ seedsCache,+ step.anchors,+ );if (seeds.length === 0) return new Set<string>();return buildAncestorShaSet(shadow, seeds, branch, ancestorSetCache);}),diff --git a/packages/server/src/vanished-documents.test.ts b/packages/server/src/vanished-documents.test.tsnew file mode 100644index 000000000..b5509a005--- /dev/null+++ b/packages/server/src/vanished-documents.test.ts@@ -0,0 +1,224 @@+import { describe, expect, test } from 'vitest';+import { usableFileIdentity } from './file-watcher.ts';+import {+ type CreateCandidate,+ RECENT_CREATE_WINDOW_MS,+ type RecentCreate,+ sharesMostLines,+ type VanishedDocument,+ VanishedDocuments,+} from './vanished-documents.ts';+import { contentHash } from './version-hash.ts';++const NOTES_TEXT = '# Notes\n\nFirst point.\n\nSecond point.\n';+const NOTES = contentHash(NOTES_TEXT);+const OTHER_TEXT = '# Shopping\n\nMilk.\n\nBread.\n';+const OTHER = contentHash(OTHER_TEXT);+const EMPTY = contentHash('');+const WRITTEN = '2026-10-20T10:00:00.000Z';+const LATER = '2026-10-20T10:05:00.000Z';++function vanished(docName: string, overrides: Partial<VanishedDocument> = {}): VanishedDocument {+ return {+ docName,+ path: `/content/${docName}.md`,+ identity: undefined,+ size: NOTES_TEXT.length,+ modified: WRITTEN,+ hashes: new Set([NOTES]),+ text: NOTES_TEXT,+ afterPass: 0,+ heldAt: 0,+ ...overrides,+ };+}++function created(docName: string, overrides: Partial<CreateCandidate> = {}): CreateCandidate {+ return {+ docName,+ identity: undefined,+ size: OTHER_TEXT.length,+ modified: LATER,+ hash: OTHER,+ content: OTHER_TEXT,+ ...overrides,+ };+}++function recent(docName: string, overrides: Partial<RecentCreate> = {}): RecentCreate {+ return {+ docName,+ path: `/content/${docName}.md`,+ identity: undefined,+ size: OTHER_TEXT.length,+ modified: LATER,+ hash: OTHER,+ at: 1_000,+ ...overrides,+ };+}++describe('pairing a create with a vanished document', () => {+ test('a create at the same name is the file coming back', () => {+ const pending = new VanishedDocuments();+ pending.hold(vanished('notes', { identity: '1:10' }));++ const match = pending.matchCreate(created('notes', { identity: '1:99' }));+ expect(match?.by).toBe('same-name');+ expect(match?.vanished.docName).toBe('notes');+ });++ test('a recycled inode on an unrelated new file does not pair', () => {+ const pending = new VanishedDocuments();+ pending.hold(vanished('removed', { identity: '1:10' }));++ expect(pending.matchCreate(created('external', { identity: '1:10' }))).toBe(undefined);+ });++ test('the same file, unchanged in size and modification time, pairs by identity', () => {+ const pending = new VanishedDocuments();+ pending.hold(vanished('moved', { identity: '1:10' }));++ const match = pending.matchCreate(+ created('elsewhere/moved', {+ identity: '1:10',+ size: NOTES_TEXT.length,+ modified: WRITTEN,+ hash: contentHash('different bytes of the same size'),+ content: 'different bytes of the same size',+ }),+ );+ expect(match).toEqual({+ vanished: expect.objectContaining({ docName: 'moved' }),+ by: 'identity',+ });+ });++ test('the same file moved and edited pairs by identity when it keeps most of its lines', () => {+ const pending = new VanishedDocuments();+ pending.hold(vanished('moved', { identity: '1:10' }));+ const edited = `${NOTES_TEXT}\nThird point, added outside.\n`;++ const match = pending.matchCreate(+ created('archive/moved', {+ identity: '1:10',+ size: edited.length,+ hash: contentHash(edited),+ content: edited,+ }),+ );+ expect(match?.by).toBe('identity');+ });++ test('content pairs only when exactly one vanished document has those non-empty bytes', () => {+ const pending = new VanishedDocuments();+ pending.hold(vanished('first'));+ expect(pending.matchCreate(created('renamed', { hash: NOTES, content: NOTES_TEXT }))?.by).toBe(+ 'hash',+ );++ pending.hold(vanished('second'));+ expect(pending.matchCreate(created('renamed', { hash: NOTES, content: NOTES_TEXT }))).toBe(+ undefined,+ );++ pending.hold(vanished('blank', { hashes: new Set([EMPTY]) }));+ expect(pending.matchCreate(created('renamed', { hash: EMPTY, content: '' }))).toBe(undefined);+ });++ test('a vanished document is due once a pass that started after it has completed, and its hold age is known', () => {+ const pending = new VanishedDocuments();+ pending.hold(vanished('notes', { afterPass: 3, heldAt: 5_000 }));++ expect(pending.dueAfter(3)).toEqual([]);+ expect(pending.dueAfter(4).map((entry) => entry.docName)).toEqual(['notes']);+ expect(pending.heldBefore(4_999)).toEqual([]);+ expect(pending.heldBefore(5_000).map((entry) => entry.docName)).toEqual(['notes']);+ expect(pending.has('notes')).toBe(true);+ pending.release('notes');+ expect(pending.has('notes')).toBe(false);+ expect(pending.size).toBe(0);+ });+});++describe('pairing a delete with a create that arrived first', () => {+ test('a recent create of the same, unchanged file pairs by identity and is used once', () => {+ const pending = new VanishedDocuments();+ pending.rememberCreate(+ recent('renamed', { identity: '1:10', size: NOTES_TEXT.length, modified: WRITTEN }),+ );+ const read = () => {+ throw new Error('an unchanged file is not read');+ };++ const match = pending.matchRecentCreate(vanished('notes', { identity: '1:10' }), 2_000, read);+ expect(match?.by).toBe('identity');+ expect(match?.create.docName).toBe('renamed');+ expect(pending.matchRecentCreate(vanished('notes', { identity: '1:10' }), 2_000, read)).toBe(+ undefined,+ );+ });++ test('a recent create on a recycled inode with unrelated content does not pair', () => {+ const pending = new VanishedDocuments();+ pending.rememberCreate(recent('external', { identity: '1:10' }));++ expect(+ pending.matchRecentCreate(vanished('removed', { identity: '1:10' }), 2_000, () => OTHER_TEXT),+ ).toBe(undefined);+ });++ test('a recent create whose content cannot be read pairs only by identity with unchanged facts', () => {+ const pending = new VanishedDocuments();+ pending.rememberCreate(recent('renamed', { identity: '1:10' }));++ expect(+ pending.matchRecentCreate(vanished('notes', { identity: '1:10' }), 2_000, () => undefined),+ ).toBe(undefined);+ });++ test('a recent create pairs by content only when it is the one create with those bytes', () => {+ const pending = new VanishedDocuments();+ pending.rememberCreate(recent('copy-a', { hash: NOTES }));+ expect(+ pending.matchRecentCreate(vanished('notes'), 1_500, () => NOTES_TEXT)?.create.docName,+ ).toBe('copy-a');++ pending.rememberCreate(recent('copy-b', { hash: NOTES }));+ pending.rememberCreate(recent('copy-c', { hash: NOTES }));+ expect(pending.matchRecentCreate(vanished('notes'), 1_500, () => NOTES_TEXT)).toBe(undefined);+ });++ test('a create at the same name or older than the window does not pair', () => {+ const pending = new VanishedDocuments();+ const unchanged = { identity: '1:10', size: NOTES_TEXT.length, modified: WRITTEN, hash: NOTES };+ pending.rememberCreate(recent('notes', unchanged));+ expect(+ pending.matchRecentCreate(vanished('notes', { identity: '1:10' }), 1_500, () => NOTES_TEXT),+ ).toBe(undefined);++ pending.rememberCreate(recent('renamed', unchanged));+ expect(+ pending.matchRecentCreate(+ vanished('notes', { identity: '1:10' }),+ 1_000 + RECENT_CREATE_WINDOW_MS + 1,+ () => NOTES_TEXT,+ ),+ ).toBe(undefined);+ });+});++describe('what counts as the same file', () => {+ test('an empty or zero inode number is no identity', () => {+ expect(usableFileIdentity('16777232:4512')).toBe('16777232:4512');+ expect(usableFileIdentity('16777232:0')).toBe(undefined);+ expect(usableFileIdentity('')).toBe(undefined);+ expect(usableFileIdentity(undefined)).toBe(undefined);+ });++ test('two texts share most lines when at least half of the longer one is shared', () => {+ expect(sharesMostLines(NOTES_TEXT, `${NOTES_TEXT}\nOne more line.\n`)).toBe(true);+ expect(sharesMostLines(NOTES_TEXT, OTHER_TEXT)).toBe(false);+ expect(sharesMostLines('', '')).toBe(false);+ });+});diff --git a/packages/server/src/vanished-documents.ts b/packages/server/src/vanished-documents.tsnew file mode 100644index 000000000..8b233a542--- /dev/null+++ b/packages/server/src/vanished-documents.ts@@ -0,0 +1,190 @@+import { contentHash } from './version-hash.ts';++const EMPTY_CONTENT_HASH = contentHash('');++export const RECENT_CREATE_WINDOW_MS = 10_000;+export const VANISH_RECHECK_DELAY_MS = 1_000;++export const VANISH_OVERDUE_FAULT_LIMIT = 3;+export const VANISH_HOLD_LIMIT_MS = 30_000;+const RECENT_CREATE_LIMIT = 256;+const SHARED_LINE_FRACTION = 0.5;++interface FileFacts {+ readonly identity: string | undefined;+ readonly size: number | undefined;+ readonly modified: string | undefined;+}++export interface VanishedDocument extends FileFacts {+ readonly docName: string;+ readonly path: string;+ readonly hashes: ReadonlySet<string>;+ readonly text: string | undefined;+ readonly afterPass: number;+ readonly heldAt: number;+}++export interface RecentCreate extends FileFacts {+ readonly docName: string;+ readonly path: string;+ readonly hash: string;+ readonly at: number;+}++export interface CreateCandidate extends FileFacts {+ readonly docName: string;+ readonly hash: string;+ readonly content: string;+}++export type VanishPairing = 'same-name' | 'identity' | 'hash';+export type RecentCreatePairing = Exclude<VanishPairing, 'same-name'>;++function uniqueByHash<T>(entries: readonly T[], hasHash: (entry: T) => boolean): T | undefined {+ const found = entries.filter(hasHash);+ return found.length === 1 ? found[0] : undefined;+}++function nonBlankLines(text: string): Set<string> {+ const lines = new Set<string>();+ for (const line of text.split('\n')) {+ const trimmed = line.trim();+ if (trimmed !== '') lines.add(trimmed);+ }+ return lines;+}++export function sharesMostLines(left: string, right: string): boolean {+ const a = nonBlankLines(left);+ const b = nonBlankLines(right);+ let shared = 0;+ for (const line of a) if (b.has(line)) shared++;+ return shared > 0 && shared >= Math.max(a.size, b.size) * SHARED_LINE_FRACTION;+}++function unchangedFile(vanished: FileFacts, created: FileFacts): boolean {+ return (+ vanished.size !== undefined &&+ vanished.modified !== undefined &&+ created.size === vanished.size &&+ created.modified === vanished.modified+ );+}++function corroboratesIdentity(+ vanished: Pick<VanishedDocument, 'identity' | 'size' | 'modified' | 'text'>,+ created: FileFacts,+ content: string | undefined,+): boolean {+ if (vanished.identity === undefined || created.identity !== vanished.identity) return false;+ if (unchangedFile(vanished, created)) return true;+ return (+ vanished.text !== undefined && content !== undefined && sharesMostLines(vanished.text, content)+ );+}++export class VanishedDocuments {+ private readonly pending = new Map<string, VanishedDocument>();+ private readonly recentCreates = new Map<string, RecentCreate>();++ get size(): number {+ return this.pending.size;+ }++ hold(entry: VanishedDocument): void {+ this.pending.set(entry.docName, entry);+ }++ has(docName: string): boolean {+ return this.pending.has(docName);+ }++ release(docName: string): VanishedDocument | undefined {+ const entry = this.pending.get(docName);+ this.pending.delete(docName);+ return entry;+ }++ all(): VanishedDocument[] {+ return [...this.pending.values()];+ }++ matchCreate(+ candidate: CreateCandidate,+ ): { readonly vanished: VanishedDocument; readonly by: VanishPairing } | undefined {+ const sameName = this.pending.get(candidate.docName);+ if (sameName) return { vanished: sameName, by: 'same-name' };+ for (const entry of this.pending.values()) {+ if (corroboratesIdentity(entry, candidate, candidate.content)) {+ return { vanished: entry, by: 'identity' };+ }+ }+ if (candidate.hash === EMPTY_CONTENT_HASH) return undefined;+ const byHash = uniqueByHash([...this.pending.values()], (entry) =>+ entry.hashes.has(candidate.hash),+ );+ return byHash ? { vanished: byHash, by: 'hash' } : undefined;+ }++ dueAfter(pass: number): VanishedDocument[] {+ return this.all().filter((entry) => entry.afterPass < pass);+ }++ heldBefore(cutoff: number): VanishedDocument[] {+ return this.all().filter((entry) => entry.heldAt <= cutoff);+ }++ rememberCreate(create: RecentCreate): void {+ this.forgetCreatesBefore(create.at - RECENT_CREATE_WINDOW_MS);+ this.recentCreates.delete(create.docName);+ this.recentCreates.set(create.docName, create);+ for (const docName of this.recentCreates.keys()) {+ if (this.recentCreates.size <= RECENT_CREATE_LIMIT) break;+ this.recentCreates.delete(docName);+ }+ }++ private forgetCreatesBefore(cutoff: number): void {+ for (const [docName, create] of this.recentCreates) {+ if (create.at < cutoff) this.recentCreates.delete(docName);+ }+ }++ matchRecentCreate(+ vanished: Pick<+ VanishedDocument,+ 'docName' | 'identity' | 'hashes' | 'size' | 'modified' | 'text'+ >,+ now: number,+ readContent: (create: RecentCreate) => string | undefined,+ ): { readonly create: RecentCreate; readonly by: RecentCreatePairing } | undefined {+ this.forgetCreatesBefore(now - RECENT_CREATE_WINDOW_MS);+ const candidates = [...this.recentCreates.values()].filter(+ (create) => create.docName !== vanished.docName,+ );+ let found: { create: RecentCreate; by: RecentCreatePairing } | undefined;+ for (const create of candidates) {+ if (vanished.identity === undefined || create.identity !== vanished.identity) continue;+ const content = unchangedFile(vanished, create) ? undefined : readContent(create);+ if (corroboratesIdentity(vanished, create, content)) {+ found = { create, by: 'identity' };+ break;+ }+ }+ if (!found) {+ const byHash = uniqueByHash(+ candidates.filter((create) => create.hash !== EMPTY_CONTENT_HASH),+ (create) => vanished.hashes.has(create.hash),+ );+ if (byHash) found = { create: byHash, by: 'hash' };+ }+ if (found) this.recentCreates.delete(found.create.docName);+ return found;+ }++ clear(): void {+ this.pending.clear();+ this.recentCreates.clear();+ }+}