Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): prevent overlapping server content ownership (PRD-8206) (#5674)

Andrew Mikofalvy95f65064f989
diff --git a/.changeset/nested-project-write-scope.md b/.changeset/nested-project-write-scope.md
new file mode 100644
index 000000000..e10ef279b
--- /dev/null
+++ b/.changeset/nested-project-write-scope.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Overlapping projects and previews now refuse to start rather than write the same files. Close overlapping previews before opening a project, restart existing servers after updating, and restart the parent after creating a nested project.
diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdx
index 22419a3bc..fa0118baa 100644
--- a/docs/content/features/editor.mdx
+++ b/docs/content/features/editor.mdx
@@ -16,6 +16,8 @@ ok ./specs/foo/SPEC.md # a file inside a project opens that project, focused on
When the file is inside an existing OpenKnowledge project, this opens that project focused on the doc. When it's a loose file, it opens an **ephemeral single-file session**: a throwaway editor scoped to just that one file, with no project scaffolding, no agents, and no git. Your edits save straight back to the original file, and **nothing is written into the file's directory** — all session state lives in a temporary directory that's removed when you close the window. Opening a file you don't edit leaves it byte-for-byte unchanged.
+Single-file sessions own only the selected file. Different-file previews can coexist, but an enclosing project cannot start until its overlapping preview closes. File uploads and project-wide configuration changes require opening a project; they cannot create files beside a loose preview. Appearance settings and document comments remain available. See [overlapping projects and previews](/docs/reference/cli#overlapping-projects-and-previews) for nested-project boundaries and restart requirements.
+
It opens in the desktop app when it's installed, and falls back to your browser otherwise (press Ctrl-C in the terminal to end a browser session). Single-file sessions show just the file and the editor — no sidebar, tabs, or project switcher. Discover it any time with `ok --help`.
On Windows, you can also open `.md` and `.mdx` files from Explorer with **Open With → OpenKnowledge**, or double-click them when OpenKnowledge is their default app. With the desktop app installed, these actions open a project or a standalone file using the same rules as `ok <file>`; see [Windows file associations and changing the default app](/docs/reference/what-open-knowledge-writes#installing-and-launching-the-app).
diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdx
index 447a6e3f0..8b3345b8a 100644
--- a/docs/content/reference/cli.mdx
+++ b/docs/content/reference/cli.mdx
@@ -48,7 +48,7 @@ Once you have initialized your project, launch the app in your browser:
ok start
```
-One server on one port serves everything — the editor, the API, the MCP endpoint, and real-time collaboration — and the editor opens in your browser automatically (pass `--no-open-browser` to skip that). Running `ok start` again while a server is already up prints the running server's URL and exits.
+One server on one port serves everything — the editor, the API, the MCP endpoint, and real-time collaboration — and the editor opens in your browser automatically (pass `--no-open-browser` to skip that). Running `ok start` again for the same project while its server is already up prints the running server's URL and exits.
`ok start` also takes `-p/--port` and `--bind` to pick the address, `--idle-shutdown` (`off` or a duration like `30m`) to control when an unused server exits, `--only server` to run without the editor UI, and `--mode app` to hand off to the desktop app instead of running a server in the terminal (with the desktop app installed).
@@ -56,6 +56,20 @@ Idle shutdown is on by default at 30 minutes — a server with no connected clie
For a complete list of every file OpenKnowledge creates or changes — during install, at runtime, and in the desktop app — see [What OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).
+### Overlapping projects and previews
+
+A second project or single-file preview cannot start over content already owned by another server. A verified refusal names the existing live session; close it before opening the overlapping project or preview. An unverified refusal protects only overlapping content. A failed lease probe names the affected content, lease path and underlying failure; an unsupported ownership protocol instead names the compatibility problem. Check access and retry a temporary read failure; unsupported ownership protocols require compatible runtimes, not deleting another runtime's record. In particular, close a loose-file preview before turning its containing folder into an OpenKnowledge project. [Single-file sessions](/docs/features/editor#open-a-single-file) otherwise remain independent when they edit different files.
+
+A nested project marked by its own `.ok/config.yml` belongs to its own server. The parent cannot read or write the nested project's documents; explicit API requests return 403. If a nested project is created while the parent is running, restart the parent before opening the child. Removing a nested project's marker does not expand a running parent's scope either: restart the parent to adopt that content.
+
+Restart all existing OpenKnowledge servers after updating so every runtime uses the same ownership protection. The protection is local to one OS account and requires a writable home registered for that account; changing `HOME` or a project's config does not select a separate ownership registry.
+
+### Ownership registry recovery
+
+If startup reports a registry version mismatch, update all OpenKnowledge runtimes to compatible versions. For a permissions error, make the OS account's home writable; protection is never silently disabled. The shared registry must be on a local filesystem that honors SQLite file locks. Network-mounted homes and filesystems with broken locks do not provide this protection.
+
+After a server crashes, is forcibly terminated or the computer restarts, its released filesystem lease lets the next server recover ownership automatically on macOS, Windows and Linux. Recovery never depends on a PID, hostname or timeout. A missing or damaged lease leaves only its recorded content protected; disjoint projects can still open. A corrupt registry or a retired, nonempty pre-release format affects the whole registry and needs manual recovery. Run `ok stop all` and confirm **every OpenKnowledge server under that OS account** has exited, including desktop, terminal, MCP-spawned and preview sessions. Then back up and remove the registry file named in the error (`~/.ok/local/server-authority.sqlite`) together with its `-journal` sidecar if present, keeping them together as one backup, and restart the desired projects. Never remove or replace the registry while a server is running: doing so would discard its ownership claim.
+
## Open a doc, folder, or file
`ok open` takes a doc name, a folder, or a path to a Markdown file.
@@ -166,7 +180,7 @@ The rest of the CLI exists mostly for tooling and automation. Your AI editor spa
`ok deinit [path]` reverses `ok init` for one project (the current project when `path` is omitted): it removes the project's `.ok/` directory, OpenKnowledge's editor MCP entries, its own git-exclude lines, and shadow repo, leaving your markdown untouched. Shared editor settings and their symlinks are preserved; ignore rules for shared config files stay while those files still exist.
-`ok uninstall` removes the global footprint: running servers, credentials, the PATH shim, OpenKnowledge's editor MCP entries and bundled skills, app data, and `~/.ok`. It keeps the `~/.ok` entries every product shares: `~/.ok/machine-id`, the user skills store `~/.ok/skills`, `~/.ok/skills-lock.json`, and the Global-scope skill bookkeeping in `~/.ok/local/installed-skills.json`, `~/.ok/local/skill-placements.json`, and `~/.ok/local/skill-move-retained.json`. It removes only the running product's footprint: `ok-beta uninstall` removes `~/.ok-beta` and Beta's credentials and leaves Stable's `~/.ok` alone. No product's uninstall removes `~/.ok/machine-id`. With `--purge-content`, either product also removes the shared `~/.ok/skills`, unless an earlier uninstall step failed. See [Stable and Beta home folders](/docs/reference/what-open-knowledge-writes#stable-and-beta-home-folders). Your markdown and other skills in your editors' skill directories stay. An interactive run lets you select projects to deinitialize; `--yes` removes only the global footprint unless you also pass `--all-projects`, which covers current, recent, and discovered running projects. The CLI binary stays installed; the command ends by printing how to remove it (`npm uninstall -g @inkeep/open-knowledge` for the install above).
+`ok uninstall` removes the global footprint: running servers, credentials, the PATH shim, OpenKnowledge's editor MCP entries and bundled skills, app data, and `~/.ok`. It keeps the `~/.ok` entries every product shares: `~/.ok/machine-id`, the user skills store `~/.ok/skills`, `~/.ok/skills-lock.json`, the Global-scope skill bookkeeping in `~/.ok/local/installed-skills.json`, `~/.ok/local/skill-placements.json`, and `~/.ok/local/skill-move-retained.json`, plus the shared ownership registry `~/.ok/local/server-authority.sqlite`, its `-journal` file, and `~/.ok/local/server-authority-leases/`. These coordination files stay even with `--purge-content`. It removes only the running product's footprint: `ok-beta uninstall` removes `~/.ok-beta` and Beta's credentials and leaves Stable's `~/.ok` alone. No product's uninstall removes `~/.ok/machine-id`. With `--purge-content`, either product also removes the shared `~/.ok/skills`, unless an earlier uninstall step failed. See [Stable and Beta home folders](/docs/reference/what-open-knowledge-writes#stable-and-beta-home-folders). Your markdown and other skills in your editors' skill directories stay. An interactive run lets you select projects to deinitialize; `--yes` removes only the global footprint unless you also pass `--all-projects`, which covers current, recent, and discovered running projects. The CLI binary stays installed; the command ends by printing how to remove it (`npm uninstall -g @inkeep/open-knowledge` for the install above).
Both `ok deinit` and `ok uninstall` wait for servers to exit before deleting their state. If a server cannot be safely stopped or an integration cannot be cleaned up, the command reports the problem and retains state needed for repair and retry. Applied cleanup exits `1` when anything remains unresolved. With `--yes --json`, inspect `failed[]` for those items and their reasons; `skipped[]` covers intentionally preserved entries. Repair the reported problem and rerun the command.
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index 6eab6fe44..cacf1817a 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -25,6 +25,7 @@ Writes fall into two buckets, and each table's **Scope** column tells you which:
Every `~/.ok/` path on this page belongs to Stable, except the shared entries listed below. OpenKnowledge Beta, and the `ok-beta` CLI, write the other files under `~/.ok-beta/` instead, and keep credentials in the OS credential store under the service `open-knowledge-beta` rather than `open-knowledge`. These entries stay under `~/.ok/` for both products:
- `~/.ok/machine-id`, a random id that identifies this machine to project server locks.
+- `~/.ok/local/server-authority.sqlite`, its SQLite rollback journal `~/.ok/local/server-authority.sqlite-journal`, and `~/.ok/local/server-authority-leases/`, created when a server starts to prevent overlapping projects or previews from writing the same content. The registry and lease files are owner-only (`0600`); Stable and Beta share them. A lease is held while its server owns the content and removed on successful shutdown or crash recovery. Uninstall keeps these shared coordination files. Never delete them while a server is running; see [Ownership registry recovery](./cli.mdx#ownership-registry-recovery).
- `~/.ok/skills/`, the user skills store.
- `~/.ok/skills-lock.json`, provenance for skills imported at Global scope.
- `~/.ok/local/installed-skills.json`, `~/.ok/local/skill-placements.json`, and `~/.ok/local/skill-move-retained.json`, the install markers, placement records (where each copy of a skill was written, and whether as a copy or a link), and unfinished-scope-move bookkeeping for Global-scope skills.
diff --git a/packages/app/src/components/PageHeaderWidgets.tsx b/packages/app/src/components/PageHeaderWidgets.tsx
index 6b114be15..c870d5e91 100644
--- a/packages/app/src/components/PageHeaderWidgets.tsx
+++ b/packages/app/src/components/PageHeaderWidgets.tsx
@@ -11,6 +11,7 @@ import { Button } from '@/components/ui/button';
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
import { UploadFailedError } from '@/editor/image-upload/upload-failure';
import { uploadFile } from '@/editor/image-upload/upload-file';
+import { useSingleFileMode } from '@/lib/single-file-mode';
import { cn } from '@/lib/utils';
export function PageIconWidget({ keyName, value, onCommit }: CommonWidgetProps<string>) {
@@ -92,6 +93,7 @@ export function PageIconWidget({ keyName, value, onCommit }: CommonWidgetProps<s
export function PageCoverWidget({ keyName, value, onCommit }: CommonWidgetProps<string>) {
const { t } = useLingui();
+ const singleFile = useSingleFileMode();
const [draft, setDraft] = useState(value);
const [uploadError, setUploadError] = useState<string | null>(null);
const [uploading, setUploading] = useState(false);
@@ -116,7 +118,7 @@ export function PageCoverWidget({ keyName, value, onCommit }: CommonWidgetProps<
setUploadError(null);
setUploading(true);
try {
- const result = await uploadFile(file, ALLOWED_IMAGE_MIME_TYPES);
+ const result = await uploadFile(file, ALLOWED_IMAGE_MIME_TYPES, { singleFile });
if (!mountedRef.current) return;
setDraft(result.url);
onCommit(result.url);
diff --git a/packages/app/src/editor/TiptapEditor.tsx b/packages/app/src/editor/TiptapEditor.tsx
index 24505a70d..73e5e2a95 100644
--- a/packages/app/src/editor/TiptapEditor.tsx
+++ b/packages/app/src/editor/TiptapEditor.tsx
@@ -48,6 +48,7 @@ import { anchorFromHash } from '@/lib/doc-hash';
import { claimNoteWindowInitialFocus } from '@/lib/note-window-focus';
import { mark } from '@/lib/perf';
import { wrapExtensionsWithTiming } from '@/lib/perf/cold-mount-instrumentation';
+import { useSingleFileMode } from '@/lib/single-file-mode';
import { useIdentity } from '../presence/identity';
import { registerEditor, unregisterEditor } from './active-editor';
import { changedRangeIsOnScreen } from './agent-follow-scroll';
@@ -67,7 +68,7 @@ import { useDocumentContext } from './DocumentContext';
import { isUserIntentOrigin } from './extensions/autonomous-fragment-edit.ts';
import { createBareHtmlImageDecoration } from './extensions/bare-html-image-decoration';
import { setEditorDocName } from './extensions/doc-context.ts';
-import { setEditorSourceMode } from './extensions/editor-mode-context.ts';
+import { setEditorSingleFileMode, setEditorSourceMode } from './extensions/editor-mode-context.ts';
import { FrozenTableHeaders } from './extensions/frozen-table-headers.ts';
import { MarkdownLintDecorations } from './extensions/markdown-lint-decorations.ts';
import { sharedExtensions } from './extensions/shared.ts';
@@ -493,6 +494,7 @@ const TiptapEditorChrome: FC<TiptapEditorChromeProps> = ({
portalTarget,
}) => {
const portalSlotRef = useRef<HTMLDivElement | null>(null);
+ const singleFile = useSingleFileMode();
const [editorContentRevision, setEditorContentRevision] = useState(0);
useLayoutEffect(() => {
const slot = portalSlotRef.current;
@@ -1174,6 +1176,11 @@ const TiptapEditorChrome: FC<TiptapEditorChromeProps> = ({
};
}, [editor, isSourceMode]);
+ useLayoutEffect(() => {
+ setEditorSingleFileMode(editor, singleFile);
+ return () => setEditorSingleFileMode(editor, false);
+ }, [editor, singleFile]);
+
return (
<div
ref={wrapperRef}
diff --git a/packages/app/src/editor/components/PropPanel.dom.test.tsx b/packages/app/src/editor/components/PropPanel.dom.test.tsx
index ba02fe417..fee2c44b3 100644
--- a/packages/app/src/editor/components/PropPanel.dom.test.tsx
+++ b/packages/app/src/editor/components/PropPanel.dom.test.tsx
@@ -1,6 +1,9 @@
import { ALLOWED_IMAGE_MIME_TYPES, type PropDef } from '@inkeep/open-knowledge-core';
import { cleanup, fireEvent, render } from '@testing-library/react';
+import { toast } from 'sonner';
import { afterEach, describe, expect, test, vi } from 'vitest';
+import { PageCoverWidget } from '@/components/PageHeaderWidgets';
+import { SingleFileModeProvider } from '@/lib/single-file-mode';
import type { JsxComponentDescriptor } from '../registry/types.ts';
type GlobalShims = typeof globalThis & {
@@ -66,6 +69,64 @@ function makeDescriptor(props: PropDef[]): JsxComponentDescriptor {
};
}
+test.each(['cover', 'property'] as const)(
+ 'the %s picker uses preview mode from the shared provider before uploading',
+ async (surface) => {
+ const bridge = window.okDesktop;
+ const hash = window.location.hash;
+ const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+ new Response(
+ JSON.stringify({
+ ok: true,
+ src: 'photo.png',
+ path: 'photo.png',
+ deduped: false,
+ }),
+ { headers: { 'content-type': 'application/json' } },
+ ),
+ );
+ const error = vi.spyOn(toast, 'error');
+ const onChange = vi.fn();
+ (window as { okDesktop?: unknown }).okDesktop = { config: { singleFile: true } };
+ window.location.hash = '#/preview';
+ try {
+ const view = render(
+ <SingleFileModeProvider>
+ {surface === 'cover' ? (
+ <PageCoverWidget keyName="cover" value="" onCommit={onChange} />
+ ) : (
+ <PropPanel
+ descriptor={makeDescriptor([
+ { name: 'src', type: 'string', required: true, accept: ALLOWED_IMAGE_MIME_TYPES },
+ ])}
+ values={{ src: '' }}
+ onChange={onChange}
+ />
+ )}
+ </SingleFileModeProvider>,
+ );
+ const input = view.container.querySelector('input[type="file"]');
+ if (input === null) throw new Error('Upload picker absent');
+ fireEvent.change(input, {
+ target: { files: [new File(['asset'], 'photo.png', { type: 'image/png' })] },
+ });
+ const message = 'Close this preview, then open the folder to upload files';
+ await vi.waitFor(() => {
+ if (surface === 'cover') expect(view.getByText(message)).toBeDefined();
+ else expect(error).toHaveBeenCalledWith(message);
+ });
+ expect(fetch).not.toHaveBeenCalled();
+ expect(onChange).not.toHaveBeenCalled();
+ } finally {
+ cleanup();
+ window.okDesktop = bridge;
+ window.location.hash = hash;
+ fetch.mockRestore();
+ error.mockRestore();
+ }
+ },
+);
+
describe('PropPanel — Enter on a single-line string input dismisses', () => {
test('Enter on a plain string Input (no autocomplete) calls onDismiss', () => {
const onDismiss = vi.fn(() => {});
diff --git a/packages/app/src/editor/components/PropPanel.tsx b/packages/app/src/editor/components/PropPanel.tsx
index 368898b8c..9540c3831 100644
--- a/packages/app/src/editor/components/PropPanel.tsx
+++ b/packages/app/src/editor/components/PropPanel.tsx
@@ -34,6 +34,7 @@ import {
mediaUrlValidationMessage,
validateMediaUrl,
} from '@/editor/utils/validate-media-url.ts';
+import { useSingleFileMode } from '@/lib/single-file-mode';
import { CodeMirrorPropInput } from './CodeMirrorPropInput.tsx';
function advancedOpenStateKey(descriptorName: string): string {
@@ -73,9 +74,10 @@ async function runUpload(
file: File,
accept: readonly string[],
onUploaded: (url: string) => void,
+ singleFile: boolean,
): Promise<void> {
try {
- const { url } = await uploadFile(file, accept);
+ const { url } = await uploadFile(file, accept, { singleFile });
onUploaded(url);
} catch (err) {
if (err instanceof UploadFailedError) {
@@ -473,6 +475,7 @@ function PropUploadButton({
accept: readonly string[];
onUploaded: (url: string) => void;
}) {
+ const singleFile = useSingleFileMode();
const [uploading, setUploading] = useState(false);
const inputRef = useRef<HTMLInputElement>(null);
return (
@@ -488,7 +491,7 @@ function PropUploadButton({
if (!file) return;
setUploading(true);
try {
- await runUpload(file, accept, onUploaded);
+ await runUpload(file, accept, onUploaded, singleFile);
} catch {}
setUploading(false);
if (inputRef.current) inputRef.current.value = '';
diff --git a/packages/app/src/editor/extensions/editor-mode-context.ts b/packages/app/src/editor/extensions/editor-mode-context.ts
index f6c1208f4..3a3dba6e1 100644
--- a/packages/app/src/editor/extensions/editor-mode-context.ts
+++ b/packages/app/src/editor/extensions/editor-mode-context.ts
@@ -1,6 +1,7 @@
import type { Editor } from '@tiptap/core';
const editorSourceMode = new WeakMap<Editor, boolean>();
+const editorSingleFileMode = new WeakMap<Editor, boolean>();
export function setEditorSourceMode(editor: Editor, isSourceMode: boolean): void {
editorSourceMode.set(editor, isSourceMode);
@@ -9,3 +10,11 @@ export function setEditorSourceMode(editor: Editor, isSourceMode: boolean): void
export function getEditorSourceMode(editor: Editor): boolean {
return editorSourceMode.get(editor) ?? false;
}
+
+export function setEditorSingleFileMode(editor: Editor, singleFile: boolean): void {
+ editorSingleFileMode.set(editor, singleFile);
+}
+
+export function getEditorSingleFileMode(editor: Editor): boolean {
+ return editorSingleFileMode.get(editor) ?? false;
+}
diff --git a/packages/app/src/editor/extensions/shared.ts b/packages/app/src/editor/extensions/shared.ts
index 1d28a6e24..4648a1f5c 100644
--- a/packages/app/src/editor/extensions/shared.ts
+++ b/packages/app/src/editor/extensions/shared.ts
@@ -4,7 +4,7 @@ import FileHandler from '@tiptap/extension-file-handler';
import { KeyboardNav } from '../block-ux/keyboard-nav';
import { TiptapFindReplace } from '../find-replace/tiptap-find-replace-extension';
import { GfmAutolink } from '../gfm-autolink-plugin';
-import { uploadAndInsert } from '../image-upload/index.ts';
+import { admitAssetUpload, uploadAndInsert } from '../image-upload/index.ts';
import { InlineLinkInputRule } from '../inline-link-input-rule';
import { MathInputRule } from '../math-input-rule';
import { LandingFlash } from '../plugins/landing-flash-wysiwyg';
@@ -82,11 +82,13 @@ export const sharedExtensions = [
TabFocusTrap,
FileHandler.configure({
onDrop(editor, files, pos) {
+ if (!admitAssetUpload(editor)) return;
for (const file of files) {
uploadAndInsert(file, editor, pos);
}
},
onPaste(editor, files, _html) {
+ if (!admitAssetUpload(editor)) return;
for (const file of files) {
uploadAndInsert(file, editor, editor.state.selection.from);
}
diff --git a/packages/app/src/editor/image-upload/index.ts b/packages/app/src/editor/image-upload/index.ts
index 4557218e2..8af777057 100644
--- a/packages/app/src/editor/image-upload/index.ts
+++ b/packages/app/src/editor/image-upload/index.ts
@@ -21,8 +21,10 @@ import { NodeSelection, Plugin, PluginKey } from '@tiptap/pm/state';
import { Decoration, DecorationSet } from '@tiptap/pm/view';
import { toast } from 'sonner';
import { getEditorDocName } from '../extensions/doc-context.ts';
+import { getEditorSingleFileMode } from '../extensions/editor-mode-context.ts';
import { buildUnresolvedWikiLinkAttrs } from '../extensions/wiki-link-helpers.ts';
import { HttpResponseParseError } from '../http-client.ts';
+import { singleFileUploadMessage } from './upload-admission.ts';
import { reportUploadFailure, type UploadFailureReport } from './upload-failure.ts';
const uploadPluginKey = new PluginKey<UploadPluginState>('imageUpload');
@@ -209,11 +211,18 @@ export function pickInsertShape(filename: string): InsertShape {
return { kind: 'markdown-link', ext };
}
+export function admitAssetUpload(editor: Editor): boolean {
+ if (!getEditorSingleFileMode(editor)) return true;
+ toast.error(singleFileUploadMessage());
+ return false;
+}
+
export async function uploadAndInsert(
file: File,
editor: Editor,
insertPos: number,
): Promise<void> {
+ if (!admitAssetUpload(editor)) return;
const docName = docNameFromEditor(editor);
const parentDocName = docName ? `${docName}.md` : '';
if (!parentDocName) {
diff --git a/packages/app/src/editor/image-upload/single-file-upload.test.ts b/packages/app/src/editor/image-upload/single-file-upload.test.ts
new file mode 100644
index 000000000..7ea53b973
--- /dev/null
+++ b/packages/app/src/editor/image-upload/single-file-upload.test.ts
@@ -0,0 +1,26 @@
+import type { Editor } from '@tiptap/core';
+import { toast } from 'sonner';
+import { afterEach, expect, test, vi } from 'vitest';
+import { setEditorSingleFileMode } from '../extensions/editor-mode-context.ts';
+import { admitAssetUpload, uploadAndInsert } from './index.ts';
+
+afterEach(() => vi.restoreAllMocks());
+
+test('single-file paste/drop admission refuses before editor mutation or upload', async () => {
+ const editor = {} as Editor;
+ setEditorSingleFileMode(editor, true);
+ const notify = vi.spyOn(toast, 'error').mockImplementation(() => 'notice');
+ const fetch = vi.spyOn(globalThis, 'fetch');
+ expect(admitAssetUpload(editor)).toBe(false);
+ await uploadAndInsert(new File(['image'], 'photo.png'), editor, 0);
+ expect(fetch).not.toHaveBeenCalled();
+ expect(notify).toHaveBeenCalledTimes(2);
+});
+
+test('project editors retain upload admission after leaving single-file mode', () => {
+ const editor = {} as Editor;
+ expect(admitAssetUpload(editor)).toBe(true);
+ setEditorSingleFileMode(editor, true);
+ setEditorSingleFileMode(editor, false);
+ expect(admitAssetUpload(editor)).toBe(true);
+});
diff --git a/packages/app/src/editor/image-upload/upload-admission.ts b/packages/app/src/editor/image-upload/upload-admission.ts
new file mode 100644
index 000000000..37987a68a
--- /dev/null
+++ b/packages/app/src/editor/image-upload/upload-admission.ts
@@ -0,0 +1,5 @@
+import { t } from '@lingui/core/macro';
+
+export function singleFileUploadMessage(): string {
+ return t`Close this preview, then open the folder to upload files`;
+}
diff --git a/packages/app/src/editor/image-upload/upload-failure.ts b/packages/app/src/editor/image-upload/upload-failure.ts
index f985a84b0..471d21e15 100644
--- a/packages/app/src/editor/image-upload/upload-failure.ts
+++ b/packages/app/src/editor/image-upload/upload-failure.ts
@@ -1,6 +1,7 @@
import { t } from '@lingui/core/macro';
+import { singleFileUploadMessage } from './upload-admission.ts';
-export type UploadFailureKind = 'file-unreadable' | 'network';
+export type UploadFailureKind = 'file-unreadable' | 'network' | 'single-file-mode';
const PROBE_TIMEOUT_MS = 1000;
@@ -57,6 +58,7 @@ export function classifyUploadFailure(probe: FileReadProbe): UploadFailureKind {
}
export function uploadFailureMessage(kind: UploadFailureKind, fileName: string): string {
+ if (kind === 'single-file-mode') return singleFileUploadMessage();
return kind === 'file-unreadable'
? t`Couldn't read ${fileName}. It may have been moved, deleted, or not finished downloading. Try adding it again.`
: t`Couldn't reach the Open Knowledge server to upload ${fileName}.`;
diff --git a/packages/app/src/editor/image-upload/upload-file.test.ts b/packages/app/src/editor/image-upload/upload-file.test.ts
index a52238625..728601ac8 100644
--- a/packages/app/src/editor/image-upload/upload-file.test.ts
+++ b/packages/app/src/editor/image-upload/upload-file.test.ts
@@ -1,7 +1,18 @@
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
import { UploadFailedError } from './upload-failure.ts';
import { uploadFile } from './upload-file.ts';
+test('shared cover/property upload admission refuses a preview before network', async () => {
+ const fetch = vi.fn<typeof globalThis.fetch>();
+ const pending = uploadFile(new File(['asset'], 'photo.png'), [], {
+ docName: 'note.md',
+ fetch,
+ singleFile: true,
+ });
+ await expect(pending).rejects.toMatchObject({ kind: 'single-file-mode' });
+ expect(fetch).not.toHaveBeenCalled();
+});
+
interface FetchCall {
url: string;
init: RequestInit | undefined;
diff --git a/packages/app/src/editor/image-upload/upload-file.ts b/packages/app/src/editor/image-upload/upload-file.ts
index 25b1f3f43..019c3a9c7 100644
--- a/packages/app/src/editor/image-upload/upload-file.ts
+++ b/packages/app/src/editor/image-upload/upload-file.ts
@@ -4,6 +4,7 @@ import {
} from '@inkeep/open-knowledge-core/schemas/api';
import { HttpResponseParseError } from '../http-client.ts';
import { getCurrentDocName } from './current-doc-name.ts';
+import { singleFileUploadMessage } from './upload-admission.ts';
import {
reportUploadFailure,
UploadFailedError,
@@ -19,6 +20,7 @@ const UPLOAD_ENDPOINT = '/api/upload';
interface UploadFileDeps {
fetch?: typeof fetch;
docName?: string | null;
+ singleFile?: boolean;
}
export async function uploadFile(
@@ -27,6 +29,7 @@ export async function uploadFile(
accept: readonly string[],
deps: UploadFileDeps = {},
): Promise<UploadFileResult> {
+ if (deps.singleFile) throw new UploadFailedError(singleFileUploadMessage(), 'single-file-mode');
const fetchImpl = deps.fetch ?? globalThis.fetch;
const sizeAtPick = file.size;
diff --git a/packages/app/src/editor/slash-command/component-items.tsx b/packages/app/src/editor/slash-command/component-items.tsx
index 1776bf219..0f389632c 100644
--- a/packages/app/src/editor/slash-command/component-items.tsx
+++ b/packages/app/src/editor/slash-command/component-items.tsx
@@ -6,7 +6,7 @@ import { CopyPlus, ExternalLink, FileUp, Hash, Link2 } from 'lucide-react';
import type { ReactNode } from 'react';
import { setPendingLinkEdit } from '../extensions/link-edit-autoopen';
import { findMarkIdAt } from '../extensions/mark-identity';
-import { uploadAndInsert } from '../image-upload/index.ts';
+import { admitAssetUpload, uploadAndInsert } from '../image-upload/index.ts';
import { getInteractionLayer } from '../interaction-layer-host';
import { resolveIcon } from '../registry/icons.ts';
import { getDescriptor, getRegisteredDescriptors } from '../registry/index.ts';
@@ -482,6 +482,7 @@ export function getComponentItems(): SlashCommandItem[] {
}
function openFilePickerAndUpload({ editor }: SlashCommandContext): void {
+ if (!admitAssetUpload(editor)) return;
const input = document.createElement('input');
input.type = 'file';
input.accept = '*/*';
diff --git a/packages/app/src/locales/ar/messages.json b/packages/app/src/locales/ar/messages.json
index cd45aa8d8..c8225678b 100644
--- a/packages/app/src/locales/ar/messages.json
+++ b/packages/app/src/locales/ar/messages.json
@@ -4969,6 +4969,7 @@
"jSg1tA": ["مزيد من الإجراءات (", ["syncAttentionLabel"], ")"],
"jTLWxh": ["ضمّن صفحة خارجية في إطار مضمَّن (مستندات، عروض، Figma، CodeSandbox)."],
"jTUxaN": ["تفعيل تلقائي (سحب فقط)"],
+ "jTVuAv": ["أغلق هذه المعاينة، ثم افتح المجلد لرفع الملفات"],
"jVe0gf": ["إرفاق التعليقات: ", ["count"]],
"jWwQo6": ["دفعة"],
"jWzDfC": ["جارٍ التحقق من أدوات الذكاء الاصطناعي المتوفّرة لديك"],
diff --git a/packages/app/src/locales/ar/messages.po b/packages/app/src/locales/ar/messages.po
index 81b242264..dd421bc45 100644
--- a/packages/app/src/locales/ar/messages.po
+++ b/packages/app/src/locales/ar/messages.po
@@ -3329,6 +3329,10 @@ msgstr "إغلاق الطرفية"
msgid "Close this chat's tab to delete it"
msgstr "أغلق علامة تبويب هذه المحادثة لحذفها"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "أغلق هذه المعاينة، ثم افتح المجلد لرفع الملفات"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "إغلاق النافذة"
diff --git a/packages/app/src/locales/bn/messages.json b/packages/app/src/locales/bn/messages.json
index b20c99605..f3d232d25 100644
--- a/packages/app/src/locales/bn/messages.json
+++ b/packages/app/src/locales/bn/messages.json
@@ -4190,6 +4190,7 @@
"jSg1tA": ["আরও ক্রিয়া (", ["syncAttentionLabel"], ")"],
"jTLWxh": ["একটি বাইরের পাতা ইনলাইন iframe-এ এমবেড করুন (নথি, ডেমো, Figma, CodeSandbox)।"],
"jTUxaN": ["স্বয়ংক্রিয় (শুধু টানুন) চালু করুন"],
+ "jTVuAv": ["এই পূর্বরূপ বন্ধ করুন, তারপর ফাইল আপলোড করতে ফোল্ডারটি খুলুন"],
"jVe0gf": ["মন্তব্য সংযুক্ত করুন: ", ["count"]],
"jWwQo6": ["ব্যাচ"],
"jWzDfC": ["আপনার কোন AI টুল আছে তা যাচাই করা হচ্ছে"],
diff --git a/packages/app/src/locales/bn/messages.po b/packages/app/src/locales/bn/messages.po
index c13df17d5..519b63a03 100644
--- a/packages/app/src/locales/bn/messages.po
+++ b/packages/app/src/locales/bn/messages.po
@@ -3325,6 +3325,10 @@ msgstr "টার্মিনাল বন্ধ করুন"
msgid "Close this chat's tab to delete it"
msgstr "এটি মুছতে এই চ্যাটের ট্যাব বন্ধ করুন"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "এই পূর্বরূপ বন্ধ করুন, তারপর ফাইল আপলোড করতে ফোল্ডারটি খুলুন"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "উইন্ডো বন্ধ করুন"
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 3736c40f9..6794c93ac 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -4328,6 +4328,7 @@
"jSg1tA": ["More actions (", ["syncAttentionLabel"], ")"],
"jTLWxh": ["Embed an external page in an inline iframe (docs, demos, Figma, CodeSandbox)."],
"jTUxaN": ["Enable Auto (Pull only)"],
+ "jTVuAv": ["Close this preview, then open the folder to upload files"],
"jVe0gf": ["Attach comments: ", ["count"]],
"jWwQo6": ["batch"],
"jWzDfC": ["Checking which AI tools you have"],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index 5442b6076..1da319910 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -3329,6 +3329,10 @@ msgstr "Close terminal"
msgid "Close this chat's tab to delete it"
msgstr "Close this chat's tab to delete it"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "Close this preview, then open the folder to upload files"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "Close window"
diff --git a/packages/app/src/locales/es/messages.json b/packages/app/src/locales/es/messages.json
index 842fe6194..24dc74d7d 100644
--- a/packages/app/src/locales/es/messages.json
+++ b/packages/app/src/locales/es/messages.json
@@ -5012,6 +5012,7 @@
"Incrusta una página externa en un iframe en línea (documentación, demos, Figma, CodeSandbox)."
],
"jTUxaN": ["Activar Automático (solo Pull)"],
+ "jTVuAv": ["Cierra esta vista previa y abre la carpeta para subir archivos"],
"jVe0gf": ["Adjuntar comentarios: ", ["count"]],
"jWwQo6": ["lote"],
"jWzDfC": ["Comprobando qué herramientas de IA tienes"],
diff --git a/packages/app/src/locales/es/messages.po b/packages/app/src/locales/es/messages.po
index 13c5e3a67..1ce84fbaf 100644
--- a/packages/app/src/locales/es/messages.po
+++ b/packages/app/src/locales/es/messages.po
@@ -3329,6 +3329,10 @@ msgstr "Cerrar terminal"
msgid "Close this chat's tab to delete it"
msgstr "Cierra la pestaña de este chat para eliminarlo"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "Cierra esta vista previa y abre la carpeta para subir archivos"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "Cerrar ventana"
diff --git a/packages/app/src/locales/fr/messages.json b/packages/app/src/locales/fr/messages.json
index 7c6b771cc..b68d8910d 100644
--- a/packages/app/src/locales/fr/messages.json
+++ b/packages/app/src/locales/fr/messages.json
@@ -5053,6 +5053,7 @@
"Intègre une page externe dans une iframe en ligne (docs, démos, Figma, CodeSandbox)."
],
"jTUxaN": ["Activer Auto (Tirer seulement)"],
+ "jTVuAv": ["Fermez cet aperçu, puis ouvrez le dossier pour envoyer des fichiers"],
"jVe0gf": ["Joindre des commentaires : ", ["count"]],
"jWwQo6": ["lot"],
"jWzDfC": ["Vérification des outils IA dont vous disposez"],
diff --git a/packages/app/src/locales/fr/messages.po b/packages/app/src/locales/fr/messages.po
index ba9de0d53..5a057c9f2 100644
--- a/packages/app/src/locales/fr/messages.po
+++ b/packages/app/src/locales/fr/messages.po
@@ -3329,6 +3329,10 @@ msgstr "Fermer le terminal"
msgid "Close this chat's tab to delete it"
msgstr "Fermez l'onglet de ce chat pour le supprimer"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "Fermez cet aperçu, puis ouvrez le dossier pour envoyer des fichiers"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "Fermer la fenêtre"
diff --git a/packages/app/src/locales/hi/messages.json b/packages/app/src/locales/hi/messages.json
index d5f2e330f..196831dbd 100644
--- a/packages/app/src/locales/hi/messages.json
+++ b/packages/app/src/locales/hi/messages.json
@@ -4185,6 +4185,7 @@
"jSg1tA": ["और क्रियाएँ (", ["syncAttentionLabel"], ")"],
"jTLWxh": ["एक बाहरी पेज को इनलाइन iframe में एम्बेड करें (दस्तावेज़, डेमो, Figma, CodeSandbox)।"],
"jTUxaN": ["स्वचालित (केवल खींचें) चालू करें"],
+ "jTVuAv": ["यह प्रीव्यू बंद करें, फिर फ़ाइलें अपलोड करने के लिए फ़ोल्डर खोलें"],
"jVe0gf": ["टिप्पणियाँ संलग्न करें: ", ["count"]],
"jWwQo6": ["बैच"],
"jWzDfC": ["जाँच रहे हैं कि आपके पास कौन-से AI टूल हैं"],
diff --git a/packages/app/src/locales/hi/messages.po b/packages/app/src/locales/hi/messages.po
index 1a3516b7f..6f4019ef4 100644
--- a/packages/app/src/locales/hi/messages.po
+++ b/packages/app/src/locales/hi/messages.po
@@ -3325,6 +3325,10 @@ msgstr "टर्मिनल बंद करें"
msgid "Close this chat's tab to delete it"
msgstr "इसे हटाने के लिए इस चैट का टैब बंद करें"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "यह प्रीव्यू बंद करें, फिर फ़ाइलें अपलोड करने के लिए फ़ोल्डर खोलें"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "विंडो बंद करें"
diff --git a/packages/app/src/locales/id/messages.json b/packages/app/src/locales/id/messages.json
index 1fea3ddef..fa583e9ad 100644
--- a/packages/app/src/locales/id/messages.json
+++ b/packages/app/src/locales/id/messages.json
@@ -4344,6 +4344,7 @@
"Menyematkan halaman eksternal dalam iframe sebaris (dokumentasi, demo, Figma, CodeSandbox)."
],
"jTUxaN": ["Aktifkan Otomatis (hanya Pull)"],
+ "jTVuAv": ["Tutup pratinjau ini, lalu buka folder untuk mengunggah file"],
"jVe0gf": ["Lampirkan komentar: ", ["count"]],
"jWwQo6": ["batch"],
"jWzDfC": ["Memeriksa alat AI yang Anda miliki"],
diff --git a/packages/app/src/locales/id/messages.po b/packages/app/src/locales/id/messages.po
index 79966b976..1d66af6bb 100644
--- a/packages/app/src/locales/id/messages.po
+++ b/packages/app/src/locales/id/messages.po
@@ -3325,6 +3325,10 @@ msgstr "Tutup terminal"
msgid "Close this chat's tab to delete it"
msgstr "Tutup tab obrolan ini untuk menghapusnya"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "Tutup pratinjau ini, lalu buka folder untuk mengunggah file"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "Tutup jendela"
diff --git a/packages/app/src/locales/ko/messages.json b/packages/app/src/locales/ko/messages.json
index 843724b0b..a54fbff9d 100644
--- a/packages/app/src/locales/ko/messages.json
+++ b/packages/app/src/locales/ko/messages.json
@@ -4158,6 +4158,7 @@
"외부 페이지를 인라인 iframe에 삽입합니다. 문서, 데모, Figma, CodeSandbox를 지원합니다."
],
"jTUxaN": ["자동(풀만) 활성화"],
+ "jTVuAv": ["이 미리보기를 닫고 폴더를 열어 파일을 업로드하세요"],
"jVe0gf": ["댓글 첨부: ", ["count"]],
"jWwQo6": ["배치"],
"jWzDfC": ["보유한 AI 도구를 확인하는 중"],
diff --git a/packages/app/src/locales/ko/messages.po b/packages/app/src/locales/ko/messages.po
index 85be0e82b..82651d7c9 100644
--- a/packages/app/src/locales/ko/messages.po
+++ b/packages/app/src/locales/ko/messages.po
@@ -3329,6 +3329,10 @@ msgstr "터미널 닫기"
msgid "Close this chat's tab to delete it"
msgstr "삭제할 채팅 탭 닫기"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "이 미리보기를 닫고 폴더를 열어 파일을 업로드하세요"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "창 닫기"
diff --git a/packages/app/src/locales/pl/messages.json b/packages/app/src/locales/pl/messages.json
index 53276ad2c..a64dd39ff 100644
--- a/packages/app/src/locales/pl/messages.json
+++ b/packages/app/src/locales/pl/messages.json
@@ -5124,6 +5124,7 @@
"Osadź zewnętrzną stronę we wbudowanym iframe (dokumentacja, demo, Figma, CodeSandbox)."
],
"jTUxaN": ["Włącz Auto (tylko pobieranie)"],
+ "jTVuAv": ["Zamknij ten podgląd, a następnie otwórz folder, aby przesłać pliki"],
"jVe0gf": ["Dołącz komentarze: ", ["count"]],
"jWwQo6": ["wsad"],
"jWzDfC": ["Sprawdzanie, jakie narzędzia AI masz"],
diff --git a/packages/app/src/locales/pl/messages.po b/packages/app/src/locales/pl/messages.po
index c133b8a7a..4b53f14aa 100644
--- a/packages/app/src/locales/pl/messages.po
+++ b/packages/app/src/locales/pl/messages.po
@@ -3329,6 +3329,10 @@ msgstr "Zamknij terminal"
msgid "Close this chat's tab to delete it"
msgstr "Zamknij kartę tego czatu, aby go usunąć"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "Zamknij ten podgląd, a następnie otwórz folder, aby przesłać pliki"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "Zamknij okno"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 01701bb85..1115684e9 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -4328,6 +4328,7 @@
"jSg1tA": ["Ḿōŕē àćţĩōńś (", ["syncAttentionLabel"], ")"],
"jTLWxh": ["Ēḿƀēď àń ēxţēŕńàĺ ƥàĝē ĩń àń ĩńĺĩńē ĩƒŕàḿē (ďōćś, ďēḿōś, Ƒĩĝḿà, ĆōďēŚàńďƀōx)."],
"jTUxaN": ["Ēńàƀĺē Àũţō (Ƥũĺĺ ōńĺŷ)"],
+ "jTVuAv": ["Ćĺōśē ţĥĩś ƥŕēvĩēŵ, ţĥēń ōƥēń ţĥē ƒōĺďēŕ ţō ũƥĺōàď ƒĩĺēś"],
"jVe0gf": ["Àţţàćĥ ćōḿḿēńţś: ", ["count"]],
"jWwQo6": ["ƀàţćĥ"],
"jWzDfC": ["Ćĥēćķĩńĝ ŵĥĩćĥ ÀĨ ţōōĺś ŷōũ ĥàvē"],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index b8e454439..fbc32e363 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -3325,6 +3325,10 @@ msgstr ""
msgid "Close this chat's tab to delete it"
msgstr ""
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr ""
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr ""
diff --git a/packages/app/src/locales/pt-BR/messages.json b/packages/app/src/locales/pt-BR/messages.json
index d89fe94ec..4dc202fd8 100644
--- a/packages/app/src/locales/pt-BR/messages.json
+++ b/packages/app/src/locales/pt-BR/messages.json
@@ -4913,6 +4913,7 @@
"Incorpora uma página externa em um iframe embutido (documentação, demos, Figma, CodeSandbox)."
],
"jTUxaN": ["Ativar Automático (somente Pull)"],
+ "jTVuAv": ["Feche esta prévia e abra a pasta para enviar arquivos"],
"jVe0gf": ["Anexar comentários: ", ["count"]],
"jWwQo6": ["lote"],
"jWzDfC": ["Verificando quais ferramentas de IA você tem"],
diff --git a/packages/app/src/locales/pt-BR/messages.po b/packages/app/src/locales/pt-BR/messages.po
index c104035f1..68969d2f0 100644
--- a/packages/app/src/locales/pt-BR/messages.po
+++ b/packages/app/src/locales/pt-BR/messages.po
@@ -3325,6 +3325,10 @@ msgstr "Fechar terminal"
msgid "Close this chat's tab to delete it"
msgstr "Feche a aba deste chat para excluí-lo"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "Feche esta prévia e abra a pasta para enviar arquivos"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "Fechar janela"
diff --git a/packages/app/src/locales/ur/messages.json b/packages/app/src/locales/ur/messages.json
index f17de6f8b..b5b93d8ea 100644
--- a/packages/app/src/locales/ur/messages.json
+++ b/packages/app/src/locales/ur/messages.json
@@ -4411,6 +4411,7 @@
"کوئی بیرونی صفحہ اِن لائن iframe میں شامل کریں (دستاویزات، ڈیمو، Figma، CodeSandbox)۔"
],
"jTUxaN": ["خودکار (صرف کھینچیں) فعال کریں"],
+ "jTVuAv": ["یہ پیش نظارہ بند کریں، پھر فائلیں اپ لوڈ کرنے کے لیے فولڈر کھولیں"],
"jVe0gf": ["تبصرے منسلک کریں: ", ["count"]],
"jWwQo6": ["بیچ"],
"jWzDfC": ["دیکھا جا رہا ہے کہ آپ کے پاس کون سے AI ٹولز ہیں"],
diff --git a/packages/app/src/locales/ur/messages.po b/packages/app/src/locales/ur/messages.po
index 57c3ae8ce..387923e49 100644
--- a/packages/app/src/locales/ur/messages.po
+++ b/packages/app/src/locales/ur/messages.po
@@ -3329,6 +3329,10 @@ msgstr "ٹرمینل بند کریں"
msgid "Close this chat's tab to delete it"
msgstr "اسے حذف کرنے کے لیے اس چیٹ کا ٹیب بند کریں"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "یہ پیش نظارہ بند کریں، پھر فائلیں اپ لوڈ کرنے کے لیے فولڈر کھولیں"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "ونڈو بند کریں"
diff --git a/packages/app/src/locales/zh-Hans/messages.json b/packages/app/src/locales/zh-Hans/messages.json
index a2fac9752..5c744afef 100644
--- a/packages/app/src/locales/zh-Hans/messages.json
+++ b/packages/app/src/locales/zh-Hans/messages.json
@@ -3772,6 +3772,7 @@
"jSg1tA": ["更多操作(", ["syncAttentionLabel"], ")"],
"jTLWxh": ["用内联 iframe 嵌入外部页面(文档、演示、Figma、CodeSandbox)。"],
"jTUxaN": ["启用自动(仅拉取)"],
+ "jTVuAv": ["关闭此预览,然后打开文件夹以上传文件"],
"jVe0gf": ["附加评论:", ["count"]],
"jWwQo6": ["批次"],
"jWzDfC": ["正在检查你安装了哪些 AI 工具"],
diff --git a/packages/app/src/locales/zh-Hans/messages.po b/packages/app/src/locales/zh-Hans/messages.po
index 58828e0d2..1b7047546 100644
--- a/packages/app/src/locales/zh-Hans/messages.po
+++ b/packages/app/src/locales/zh-Hans/messages.po
@@ -3329,6 +3329,10 @@ msgstr "关闭终端"
msgid "Close this chat's tab to delete it"
msgstr "关闭此对话的标签页后才能删除"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "关闭此预览,然后打开文件夹以上传文件"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "关闭窗口"
diff --git a/packages/app/src/locales/zh-Hant/messages.json b/packages/app/src/locales/zh-Hant/messages.json
index fade19580..eca2cdda2 100644
--- a/packages/app/src/locales/zh-Hant/messages.json
+++ b/packages/app/src/locales/zh-Hant/messages.json
@@ -3792,6 +3792,7 @@
"jSg1tA": ["更多動作(", ["syncAttentionLabel"], ")"],
"jTLWxh": ["用行內 iframe 嵌入外部頁面(說明文件、示範、Figma、CodeSandbox)。"],
"jTUxaN": ["啟用自動(僅拉取)"],
+ "jTVuAv": ["關閉此預覽,然後開啟資料夾以上傳檔案"],
"jVe0gf": ["附加註解:", ["count"]],
"jWwQo6": ["批次"],
"jWzDfC": ["正在檢查你安裝了哪些 AI 工具"],
diff --git a/packages/app/src/locales/zh-Hant/messages.po b/packages/app/src/locales/zh-Hant/messages.po
index 71c4909a0..c8c266462 100644
--- a/packages/app/src/locales/zh-Hant/messages.po
+++ b/packages/app/src/locales/zh-Hant/messages.po
@@ -3329,6 +3329,10 @@ msgstr "關閉終端機"
msgid "Close this chat's tab to delete it"
msgstr "關閉此對話的分頁後才能刪除"
+#: src/editor/image-upload/upload-admission.ts
+msgid "Close this preview, then open the folder to upload files"
+msgstr "關閉此預覽,然後開啟資料夾以上傳檔案"
+
#: src/components/NoteWindowDeletedState.tsx
msgid "Close window"
msgstr "關閉視窗"
diff --git a/packages/app/tests/integration/asset-move-rerenders-embeds.test.ts b/packages/app/tests/integration/asset-move-rerenders-embeds.test.ts
index 409a5b1ee..66c21eed5 100644
--- a/packages/app/tests/integration/asset-move-rerenders-embeds.test.ts
+++ b/packages/app/tests/integration/asset-move-rerenders-embeds.test.ts
@@ -7,7 +7,7 @@ import { yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterEach, describe, expect, test } from 'vitest';
import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';
import { ProviderPool } from '../../src/editor/provider-pool';
-import { createRestartableServer, getServerState, pollUntil, schema } from './test-harness';
+import { createInspectableServer, getServerState, pollUntil, schema } from './test-harness';
interface PmJsonNode {
type?: string;
@@ -53,7 +53,7 @@ describe('asset-move embed re-resolution — head-watcher-independent fallback',
await ensureProjectGit(contentDir);
configureTestGitRepository(contentDir);
- const server = await createRestartableServer({
+ const server = await createInspectableServer({
contentDir,
keepContentDir: false,
gitEnabled: true,
@@ -137,7 +137,7 @@ describe('asset-move embed re-resolution — head-watcher-independent fallback',
await ensureProjectGit(contentDir);
configureTestGitRepository(contentDir);
- const server = await createRestartableServer({
+ const server = await createInspectableServer({
contentDir,
keepContentDir: false,
gitEnabled: true,
diff --git a/packages/app/tests/integration/branch-switch-live-client.test.ts b/packages/app/tests/integration/branch-switch-live-client.test.ts
index a9b263c66..819b7171b 100644
--- a/packages/app/tests/integration/branch-switch-live-client.test.ts
+++ b/packages/app/tests/integration/branch-switch-live-client.test.ts
@@ -13,7 +13,7 @@ import { ProviderPool } from '../../src/editor/provider-pool';
import { parseCC1BranchSwitched, SYSTEM_DOC_NAME } from '../../src/lib/cc1';
import {
clientIdsInDoc,
- createRestartableServer,
+ createInspectableServer,
pollDiskContentStable,
pollUntil,
seedPoolServerInstanceId,
@@ -82,7 +82,7 @@ describe('T5: Branch switch while tab open', () => {
const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-branch-switch-')));
await setupGitRepoWithBranches(contentDir, 'test-doc', CONTENT_A, CONTENT_B);
- const server = await createRestartableServer({
+ const server = await createInspectableServer({
contentDir,
keepContentDir: false,
gitEnabled: true,
diff --git a/packages/app/tests/integration/branch-switch-private-state-link.test.ts b/packages/app/tests/integration/branch-switch-private-state-link.test.ts
index 5f578d6e4..8360ce32c 100644
--- a/packages/app/tests/integration/branch-switch-private-state-link.test.ts
+++ b/packages/app/tests/integration/branch-switch-private-state-link.test.ts
@@ -6,7 +6,7 @@ import { setTimeout as wait } from 'node:timers/promises';
import { ensureProjectGit } from '@inkeep/open-knowledge-server';
import { afterEach, describe, expect, test } from 'vitest';
import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';
-import { createRestartableServer, createTestClient, pollUntil } from './test-harness';
+import { createInspectableServer, createTestClient, pollUntil } from './test-harness';
const cleanups: Array<() => Promise<void> | void> = [];
@@ -56,7 +56,7 @@ describe('branch switch with a document that became a link into private state',
git(contentDir, 'commit -m feature');
git(contentDir, 'checkout main');
- const server = await createRestartableServer({
+ const server = await createInspectableServer({
contentDir,
keepContentDir: true,
gitEnabled: true,
diff --git a/packages/app/tests/integration/branch-switched-with-stale-embed-resolution.test.ts b/packages/app/tests/integration/branch-switched-with-stale-embed-resolution.test.ts
index fbbeb82a5..0bb35623e 100644
--- a/packages/app/tests/integration/branch-switched-with-stale-embed-resolution.test.ts
+++ b/packages/app/tests/integration/branch-switched-with-stale-embed-resolution.test.ts
@@ -8,7 +8,7 @@ import { yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterEach, describe, expect, test } from 'vitest';
import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';
import { ProviderPool } from '../../src/editor/provider-pool';
-import { createRestartableServer, getServerState, pollUntil, schema } from './test-harness';
+import { createInspectableServer, getServerState, pollUntil, schema } from './test-harness';
interface PmJsonNode {
type?: string;
@@ -81,7 +81,7 @@ describe('T17: branch switch with `![[photo.png]]` doc — reseed-before-reset',
git(contentDir, 'commit -m feature-state');
git(contentDir, 'checkout main');
- const server = await createRestartableServer({
+ const server = await createInspectableServer({
contentDir,
keepContentDir: false,
gitEnabled: true,
diff --git a/packages/app/tests/integration/config-doc-server-instance-recovery.test.ts b/packages/app/tests/integration/config-doc-server-instance-recovery.test.ts
index d6ed836d9..ec9fce8ca 100644
--- a/packages/app/tests/integration/config-doc-server-instance-recovery.test.ts
+++ b/packages/app/tests/integration/config-doc-server-instance-recovery.test.ts
@@ -52,7 +52,7 @@ describe('PRD-6881: config-doc server-instance recovery', () => {
cleanups.push(() => server.shutdown());
writeFileSync(join(server.contentDir, '.okignore'), 'foo\n', 'utf-8');
- const instanceA = server.instance.serverInstanceId;
+ const instanceA = server.serverInstanceId;
const doc = new Y.Doc();
const provider = new HocuspocusProvider({
url: `ws://127.0.0.1:${server.port}/collab`,
diff --git a/packages/app/tests/integration/delete-durability.test.ts b/packages/app/tests/integration/delete-durability.test.ts
index ce215130c..ab7bff9af 100644
--- a/packages/app/tests/integration/delete-durability.test.ts
+++ b/packages/app/tests/integration/delete-durability.test.ts
@@ -318,7 +318,7 @@ describe('delete durability — across server restart with a stale client', () =
}
const restarting = rs.killAndRestartOnSamePort({ downtimeMs: 900 });
- await wait(250);
+ await rs.exited;
unlinkSync(filePath);
rs = await restarting;
diff --git a/packages/app/tests/integration/managed-rename-loaded-doc.test.ts b/packages/app/tests/integration/managed-rename-loaded-doc.test.ts
index 895b0fd6a..550e3f4c4 100644
--- a/packages/app/tests/integration/managed-rename-loaded-doc.test.ts
+++ b/packages/app/tests/integration/managed-rename-loaded-doc.test.ts
@@ -8,7 +8,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { afterEach, describe, expect, test } from 'vitest';
-import { createMultiClientContext, createRestartableServer, pollUntil } from './test-harness';
+import { createInspectableServer, createMultiClientContext, pollUntil } from './test-harness';
const cleanups: Array<() => Promise<void> | void> = [];
@@ -20,7 +20,7 @@ afterEach(async () => {
describe('Managed rename — loaded-Y.Doc rewrite path (QA-040 / QA-008)', () => {
test('open editor on doc with [[old]] link → file rename → Y.Text observably becomes [[new]]', async () => {
- const server = await createRestartableServer();
+ const server = await createInspectableServer();
cleanups.push(() => server.shutdown());
writeFileSync(join(server.contentDir, 'old.md'), '# Old doc\n', 'utf-8');
diff --git a/packages/app/tests/integration/managed-rename-populated-target.test.ts b/packages/app/tests/integration/managed-rename-populated-target.test.ts
index d04d8b978..6b4876ed2 100644
--- a/packages/app/tests/integration/managed-rename-populated-target.test.ts
+++ b/packages/app/tests/integration/managed-rename-populated-target.test.ts
@@ -2,7 +2,7 @@ import { writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { afterEach, describe, expect, test } from 'vitest';
-import { createMultiClientContext, createRestartableServer, pollUntil } from './test-harness';
+import { createInspectableServer, createMultiClientContext, pollUntil } from './test-harness';
const SOURCE_CONTENT = `# Source Doc
@@ -28,7 +28,7 @@ afterEach(async () => {
describe('T8: Managed-rename with populated target', () => {
test('API refuses rename when destination exists; no Y.Doc mutation occurs', async () => {
- const server = await createRestartableServer();
+ const server = await createInspectableServer();
cleanups.push(() => server.shutdown());
writeFileSync(join(server.contentDir, 'source-doc.md'), SOURCE_CONTENT, 'utf-8');
diff --git a/packages/app/tests/integration/mcp-move-real-roundtrip.test.ts b/packages/app/tests/integration/mcp-move-real-roundtrip.test.ts
index da902ed1c..f3abd6abd 100644
--- a/packages/app/tests/integration/mcp-move-real-roundtrip.test.ts
+++ b/packages/app/tests/integration/mcp-move-real-roundtrip.test.ts
@@ -4,7 +4,7 @@ import { ConfigSchema } from '@inkeep/open-knowledge-server';
import { afterEach, describe, expect, test } from 'vitest';
import { register as registerMove } from '../../../server/src/mcp/tools/move';
import type { ServerInstance } from '../../../server/src/mcp/tools/shared';
-import { awaitFileWatcherIndexed, createRestartableServer } from './test-harness';
+import { awaitFileWatcherIndexed, createInspectableServer } from './test-harness';
interface ToolResult {
content: Array<{ type: 'text'; text: string }>;
@@ -49,7 +49,7 @@ afterEach(async () => {
describe('MCP move tool — real roundtrip against live OK server (QA-004 / QA-005)', () => {
test('QA-004: move (folder) posts to live /api/rename-path → folder + backlinks rewrite on disk', async () => {
- const server = await createRestartableServer();
+ const server = await createInspectableServer();
cleanups.push(() => server.shutdown());
mkdirSync(join(server.contentDir, 'articles'), { recursive: true });
@@ -108,7 +108,7 @@ describe('MCP move tool — real roundtrip against live OK server (QA-004 / QA-0
}, 60_000);
test('QA-005: move (document) posts to live /api/rename-path with kind:file → backlinks rewrite', async () => {
- const server = await createRestartableServer();
+ const server = await createInspectableServer();
cleanups.push(() => server.shutdown());
writeFileSync(join(server.contentDir, 'auth.md'), '# Auth\n', 'utf-8');
diff --git a/packages/app/tests/integration/provider-pool-multi-client-restart.test.ts b/packages/app/tests/integration/provider-pool-multi-client-restart.test.ts
index afd9658bf..90544a4dd 100644
--- a/packages/app/tests/integration/provider-pool-multi-client-restart.test.ts
+++ b/packages/app/tests/integration/provider-pool-multi-client-restart.test.ts
@@ -8,6 +8,7 @@ import {
clientIdsInDoc,
createMultiClientContext,
createRestartableServer,
+ createTestClient,
pollDiskContentStable,
pollUntil,
} from './test-harness';
@@ -115,8 +116,8 @@ describe('T2: Multi-client fast restart', () => {
expect(afterSectionB).toBe(baselineSectionB);
expect(afterSibling).toBe(baselineSibling);
- const serverDoc = server.instance.hocuspocus.documents.get(docName);
- if (!serverDoc) throw new Error('server doc missing post-restart');
+ const serverPeer = await createTestClient(server.port, docName);
+ cleanups.push(() => serverPeer.cleanup());
for (let i = 0; i < ctx.pools.length; i++) {
const entry = ctx.pools[i].getActive();
if (!entry) throw new Error(`pool[${i}] has no active entry during post-restart assertion`);
@@ -136,7 +137,7 @@ describe('T2: Multi-client fast restart', () => {
},
cleanup: async () => {},
},
- serverDoc,
+ serverPeer.doc,
`client ${i}`,
);
}
diff --git a/packages/app/tests/integration/provider-pool-reconnect.test.ts b/packages/app/tests/integration/provider-pool-reconnect.test.ts
index 74a7a3375..248de28bc 100644
--- a/packages/app/tests/integration/provider-pool-reconnect.test.ts
+++ b/packages/app/tests/integration/provider-pool-reconnect.test.ts
@@ -6,7 +6,9 @@ import { afterEach, describe, expect, test } from 'vitest';
import { ProviderPool } from '../../src/editor/provider-pool';
import {
assertNoClientIdDrift,
+ createInspectableServer,
createRestartableServer,
+ createTestClient,
pollDiskContentStable,
pollUntil,
type RestartableServer,
@@ -81,7 +83,7 @@ async function seedAndSyncSingleClient(
describe('ProviderPool reconnects', () => {
test('browser reload against same server keeps server Y.Doc loaded and avoids IDB duplication', async () => {
- const server = await createRestartableServer();
+ const server = await createInspectableServer();
cleanups.push(() => server.shutdown());
const docName = 'reload-doc';
@@ -269,8 +271,8 @@ describe('ProviderPool reconnects', () => {
expect(afterHeadings).toBe(baselineHeadings);
expect(afterAsdfLinks).toBe(baselineAsdfLinks);
- const serverDoc = server.instance.hocuspocus.documents.get('test-doc');
- if (!serverDoc) throw new Error('server doc missing post-restart');
+ const serverPeer = await createTestClient(server.port, 'test-doc');
+ cleanups.push(() => serverPeer.cleanup());
const activeEntry = pool.getActive();
if (!activeEntry) throw new Error('pool has no active entry after reconnect');
assertNoClientIdDrift(
@@ -288,12 +290,12 @@ describe('ProviderPool reconnects', () => {
},
cleanup: async () => {},
},
- serverDoc,
+ serverPeer.doc,
'post fast-restart',
);
}, 30_000);
- test('REPRO: unsynced local changes during restart preserve edit and avoid duplication', async () => {
+ test('acknowledged local changes survive graceful restart without duplication', async () => {
let server = await createRestartableServer();
cleanups.push(() => server.shutdown());
@@ -313,12 +315,11 @@ describe('ProviderPool reconnects', () => {
doc.getXmlFragment('default').push([paragraph]);
await pollUntil(() => firstProvider.unsyncedChanges === 0, 180, 10);
- server.killNetwork();
- await wait(100);
-
- expect(pool.getActive()?.syncState).toBe('disconnected');
-
- server = await server.killAndRestartOnSamePort({ downtimeMs: 400 });
+ const previousServer = server;
+ server = await server.shutdownAndRestartOnSamePort({ downtimeMs: 400 });
+ expect(await previousServer.exited).toEqual({ code: 0, signal: null });
+ expect(server.pid).not.toBe(previousServer.pid);
+ expect(server.serverInstanceId).not.toBe(previousServer.serverInstanceId);
cleanups.unshift(() => server.shutdown());
await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);
diff --git a/packages/app/tests/integration/provider-pool-transport-drop.test.ts b/packages/app/tests/integration/provider-pool-transport-drop.test.ts
index 6c9856769..48aed3118 100644
--- a/packages/app/tests/integration/provider-pool-transport-drop.test.ts
+++ b/packages/app/tests/integration/provider-pool-transport-drop.test.ts
@@ -5,9 +5,9 @@ import { setTimeout as wait } from 'node:timers/promises';
import { afterEach, describe, expect, test } from 'vitest';
import { ProviderPool } from '../../src/editor/provider-pool';
import {
- createRestartableServer,
+ createInspectableServer,
+ type InspectableServer,
pollUntil,
- type RestartableServer,
seedPoolServerInstanceId,
} from './test-harness';
@@ -24,7 +24,7 @@ afterEach(async () => {
}
}, 30_000);
-async function openSynced(server: RestartableServer, pool: ProviderPool, docName: string) {
+async function openSynced(server: InspectableServer, pool: ProviderPool, docName: string) {
writeFileSync(join(server.contentDir, `${docName}.md`), FIXTURE, 'utf-8');
pool.open(docName);
pool.setActive(docName);
@@ -33,7 +33,7 @@ async function openSynced(server: RestartableServer, pool: ProviderPool, docName
await wait(150);
}
-function dropTransport(server: RestartableServer, docName: string): number {
+function dropTransport(server: InspectableServer, docName: string): number {
const document = server.instance.hocuspocus.documents.get(docName);
if (!document) return 0;
let dropped = 0;
@@ -48,7 +48,7 @@ function dropTransport(server: RestartableServer, docName: string): number {
describe('ProviderPool transport drop recovery', () => {
test('a synced doc re-syncs after an abrupt transport drop, and later server changes land', async () => {
- const server = await createRestartableServer();
+ const server = await createInspectableServer();
cleanups.push(() => server.shutdown());
const docName = `test-${crypto.randomUUID()}`;
@@ -77,7 +77,7 @@ describe('ProviderPool transport drop recovery', () => {
}, 60_000);
test('a drop landing mid-churn (many concurrent disk writes) still recovers', async () => {
- const server = await createRestartableServer();
+ const server = await createInspectableServer();
cleanups.push(() => server.shutdown());
const docName = `test-${crypto.randomUUID()}`;
@@ -114,7 +114,7 @@ describe('ProviderPool transport drop recovery', () => {
}, 60_000);
test('two consecutive drops in quick succession still recover', async () => {
- const server = await createRestartableServer();
+ const server = await createInspectableServer();
cleanups.push(() => server.shutdown());
const docName = `test-${crypto.randomUUID()}`;
diff --git a/packages/app/tests/integration/replay-outbox-durable.test.ts b/packages/app/tests/integration/replay-outbox-durable.test.ts
index b110f64d8..2dd884d03 100644
--- a/packages/app/tests/integration/replay-outbox-durable.test.ts
+++ b/packages/app/tests/integration/replay-outbox-durable.test.ts
@@ -54,15 +54,16 @@ describe('durable replay outbox across server-instance-mismatch', () => {
const marker = 'DURABLE-OUTBOX-MARKER-7b21';
const firstProvider = pool.getActive()?.provider;
if (!firstProvider) throw new Error('expected active provider');
+ server.killNetwork();
+ expect(await server.exited).toEqual({ code: null, signal: 'SIGKILL' });
+ await pollUntil(() => pool.getActive()?.syncState === 'disconnected', 5_000, 25);
const paragraph = new Y.XmlElement('paragraph');
const xmlText = new Y.XmlText();
xmlText.applyDelta([{ insert: marker }]);
paragraph.insert(0, [xmlText]);
firstProvider.document.getXmlFragment('default').push([paragraph]);
- await pollUntil(() => firstProvider.unsyncedChanges === 0, 180, 10);
- server.killNetwork();
- await pollUntil(() => pool.getActive()?.syncState === 'disconnected', 5_000, 25);
+ expect(firstProvider.unsyncedChanges).toBeGreaterThan(0);
server = await server.killAndRestartOnSamePort({ downtimeMs: 400 });
cleanups.unshift(() => server.shutdown());
diff --git a/packages/app/tests/integration/restart-with-embed-doc.test.ts b/packages/app/tests/integration/restart-with-embed-doc.test.ts
index 7a90440ef..225c59b5d 100644
--- a/packages/app/tests/integration/restart-with-embed-doc.test.ts
+++ b/packages/app/tests/integration/restart-with-embed-doc.test.ts
@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
@@ -7,7 +7,7 @@ import { afterEach, describe, expect, test } from 'vitest';
import { ProviderPool } from '../../src/editor/provider-pool';
import {
createRestartableServer,
- getServerState,
+ createTestClient,
pollUntil,
schema,
seedPoolServerInstanceId,
@@ -57,8 +57,7 @@ describe('restart-with-embed-doc: server restart preserves single PM image with
await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);
await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 10_000, 50);
- const preState = getServerState(server, 'test-doc');
- if (!preState) throw new Error('server has no test-doc loaded pre-restart');
+ const preState = await createTestClient(server.port, 'test-doc', { resetOnCleanup: false });
const preJson = yXmlFragmentToProseMirrorRootNode(
preState.fragment,
schema,
@@ -70,12 +69,53 @@ describe('restart-with-embed-doc: server restart preserves single PM image with
const prePropsRecord = preEmbeds[0]?.attrs?.props as Record<string, unknown> | undefined;
expect(prePropsRecord?.src).toBe('/photo.png');
expect(prePropsRecord?.target).toBe('photo.png');
+ await preState.cleanup();
await wait(500);
+ const previousProvider = pool.getActive()?.provider;
server = await server.killAndRestartOnSamePort({ downtimeMs: 400 });
cleanups.unshift(() => server.shutdown());
- await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);
+ await pollUntil(() => pool.getActive()?.provider !== previousProvider, 15_000, 50);
+ try {
+ await pollUntil(
+ () => {
+ const active = pool.getActive();
+ if (active?.provider.isSynced !== true) return false;
+ const json = yXmlFragmentToProseMirrorRootNode(
+ active.provider.document.getXmlFragment('default'),
+ schema,
+ ).toJSON() as PmJsonNode;
+ const embeds = collectNodes(json, 'jsxComponent').filter(
+ (node) => node.attrs?.componentName === 'WikiEmbedImage',
+ );
+ const props = embeds[0]?.attrs?.props as Record<string, unknown> | undefined;
+ return embeds.length === 1 && props?.src === '/photo.png';
+ },
+ 15_000,
+ 50,
+ );
+ } catch (cause) {
+ const active = pool.getActive();
+ throw new Error(
+ `Restarted embed failed to settle: ${JSON.stringify({
+ disk: readFileSync(join(contentDir, 'test-doc.md'), 'utf8'),
+ source: pool.getActive()?.provider.document.getText('source').toString(),
+ fragment: pool.getActive()?.provider.document.getXmlFragment('default').toJSON(),
+ isSynced: pool.getActive()?.provider.isSynced,
+ freshProvider: pool.getActive()?.provider !== previousProvider,
+ epoch: server.serverInstanceId,
+ pm:
+ active === undefined
+ ? null
+ : yXmlFragmentToProseMirrorRootNode(
+ active.provider.document.getXmlFragment('default'),
+ schema,
+ ).toJSON(),
+ })}`,
+ { cause },
+ );
+ }
await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 15_000, 50);
const entry = pool.getActive();
@@ -95,8 +135,8 @@ describe('restart-with-embed-doc: server restart preserves single PM image with
const clientSource = entry.provider.document.getText('source').toString();
expect((clientSource.match(/!\[\[photo\.png\]\]/g) ?? []).length).toBe(1);
- const postState = getServerState(server, 'test-doc');
- if (!postState) throw new Error('server has no test-doc loaded post-restart');
+ const postState = await createTestClient(server.port, 'test-doc');
+ cleanups.push(() => postState.cleanup());
const postJson = yXmlFragmentToProseMirrorRootNode(
postState.fragment,
schema,
diff --git a/packages/app/tests/integration/restartable-server-worker.test-helper.ts b/packages/app/tests/integration/restartable-server-worker.test-helper.ts
new file mode 100644
index 000000000..520a1a3f6
--- /dev/null
+++ b/packages/app/tests/integration/restartable-server-worker.test-helper.ts
@@ -0,0 +1,67 @@
+import type { RestartWorkerOptions } from './restartable-server.test-helper.ts';
+
+let booting: Promise<import('@inkeep/open-knowledge-server').BootedServer> | undefined;
+let stopping: Promise<void> | undefined;
+function stop(code: number): Promise<void> {
+ stopping ??= (async () => {
+ try {
+ const server = await booting;
+ await server?.destroy();
+ } catch (error) {
+ code = 1;
+ if (process.connected) process.send?.({ status: 'error', message: String(error) });
+ else process.stderr.write(`${String(error)}\n`);
+ } finally {
+ process.exit(code);
+ }
+ })();
+ return stopping;
+}
+
+process.once('disconnect', () => {
+ void stop(1);
+});
+
+const { bootServer, ConfigSchema }: typeof import('@inkeep/open-knowledge-server') = await import(
+ process.env.OK_TEST_RESTART_SERVER_MODULE ?? '@inkeep/open-knowledge-server'
+);
+
+process.once('message', async (options: RestartWorkerOptions) => {
+ try {
+ booting = bootServer({
+ authorityRegistryPath: options.authorityRegistryPath,
+ contentDir: options.contentDir,
+ configHomedirOverride: options.configHomedirOverride,
+ config: ConfigSchema.parse({}),
+ host: '127.0.0.1',
+ port: options.port,
+ quiet: true,
+ debounce: options.debounce,
+ maxDebounce: options.maxDebounce,
+ gitEnabled: options.gitEnabled,
+ commitDebounceMs: options.commitDebounceMs,
+ keepaliveGraceMs: options.keepaliveGraceMs,
+ enableTestRoutes: true,
+ idleShutdownMs: null,
+ });
+ const server = await booting;
+ await server.ready;
+ if (!process.connected) {
+ await stop(1);
+ return;
+ }
+ process.on('message', async (command) => {
+ if (command !== 'shutdown') return;
+ await stop(0);
+ });
+ process.send?.({
+ status: 'ready',
+ port: server.port,
+ pid: process.pid,
+ serverInstanceId: server.serverInstance.serverInstanceId,
+ });
+ } catch (error) {
+ if (process.connected) process.send?.({ status: 'error', message: String(error) });
+ await stop(1);
+ }
+});
diff --git a/packages/app/tests/integration/restartable-server.test-helper.ts b/packages/app/tests/integration/restartable-server.test-helper.ts
new file mode 100644
index 000000000..62514f82e
--- /dev/null
+++ b/packages/app/tests/integration/restartable-server.test-helper.ts
@@ -0,0 +1,218 @@
+import { type SpawnOptions, spawn } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { ensureProjectGit } from '@inkeep/open-knowledge-server';
+import { z } from 'zod';
+import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';
+import { testAuthorityRegistryPath } from '../../../../test-support/server-authority-registry.test-helper.ts';
+import { withHiddenWindowsConsole } from '../../../server/src/child-process-windows-hide.ts';
+import { getFreePort } from '../free-port.test-helper.ts';
+import { removeAllStrictDuringTeardown } from '../stress/_helpers/teardown-fs.ts';
+import type { CreateTestServerOptions } from './test-harness.ts';
+
+export interface RestartableServer {
+ port: number;
+ contentDir: string;
+ pid: number;
+ serverInstanceId: string;
+ exited: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+ killNetwork(): void;
+ disconnectOwner(): void;
+ shutdown(): Promise<void>;
+ killAndRestartOnSamePort(opts: { downtimeMs: number }): Promise<RestartableServer>;
+ shutdownAndRestartOnSamePort(opts: { downtimeMs: number }): Promise<RestartableServer>;
+}
+
+export interface CreateRestartableServerOptions extends CreateTestServerOptions {
+ port?: number;
+}
+
+export interface RestartWorkerOptions {
+ authorityRegistryPath: string;
+ contentDir: string;
+ configHomedirOverride: string;
+ port: number;
+ debounce: number;
+ maxDebounce: number;
+ gitEnabled: boolean;
+ commitDebounceMs: number;
+ keepaliveGraceMs?: number;
+}
+
+const receiptSchema = z.discriminatedUnion('status', [
+ z.object({
+ status: z.literal('ready'),
+ port: z.number().int().positive(),
+ pid: z.number().int().positive(),
+ serverInstanceId: z.string().min(1),
+ }),
+ z.object({ status: z.literal('error'), message: z.string() }),
+]);
+
+export async function createRestartableServer(
+ options: CreateRestartableServerOptions = {},
+): Promise<RestartableServer> {
+ const contentDir = realpathSync.native(
+ options.contentDir ?? mkdtempSync(join(tmpdir(), 'ok-restartable-')),
+ );
+ const home = options.configHomedirOverride ?? mkdtempSync(join(tmpdir(), 'ok-restart-home-'));
+ mkdirSync(join(contentDir, '.ok'), { recursive: true });
+ if (options.contentDir === undefined) {
+ writeFileSync(join(contentDir, 'test-doc.md'), '');
+ }
+ if (!existsSync(join(contentDir, '.ok', 'config.yml'))) {
+ writeFileSync(join(contentDir, '.ok', 'config.yml'), options.seedProjectConfigYml ?? '');
+ }
+ writeFileSync(join(contentDir, '.ok', '.gitignore'), '*\n');
+ await ensureProjectGit(contentDir);
+ configureTestGitRepository(contentDir);
+ const port = options.port ?? (await getFreePort());
+ const child = spawn(
+ process.execPath,
+ [
+ '--import',
+ 'tsx',
+ fileURLToPath(new URL('./restartable-server-worker.test-helper.ts', import.meta.url)),
+ ],
+ withHiddenWindowsConsole({
+ cwd: fileURLToPath(new URL('../..', import.meta.url)),
+ stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+ env: { ...process.env, HOME: home, USERPROFILE: home },
+ } satisfies SpawnOptions),
+ );
+ let diagnostics = '';
+ const capture = (chunk: Buffer): void => {
+ diagnostics = (diagnostics + chunk.toString()).slice(-16_384);
+ };
+ child.stdout?.on('data', capture);
+ child.stderr?.on('data', capture);
+ const ready = Promise.withResolvers<z.infer<typeof receiptSchema>>();
+ child.on('message', (message) => {
+ const parsed = receiptSchema.safeParse(message);
+ if (parsed.success) ready.resolve(parsed.data);
+ else ready.reject(parsed.error);
+ });
+ child.on('error', ready.reject);
+ const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {
+ child.once('exit', (code, signal) => {
+ child.stdout?.destroy();
+ child.stderr?.destroy();
+ resolve({ code, signal });
+ });
+ });
+ const kill = (): void => {
+ if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+ };
+ let startupTimer: ReturnType<typeof setTimeout> | undefined;
+ let receipt: Extract<z.infer<typeof receiptSchema>, { status: 'ready' }>;
+ try {
+ child.send({
+ authorityRegistryPath: options.authorityRegistryPath ?? testAuthorityRegistryPath,
+ contentDir,
+ configHomedirOverride: home,
+ port,
+ debounce: options.debounce ?? 200,
+ maxDebounce: options.maxDebounce ?? 1000,
+ gitEnabled: options.gitEnabled ?? false,
+ commitDebounceMs: options.commitDebounceMs ?? 200,
+ keepaliveGraceMs: options.keepaliveGraceMs,
+ } satisfies RestartWorkerOptions);
+ const result = await Promise.race([
+ ready.promise,
+ exited.then(({ code, signal }) => {
+ throw new Error(`Restart server exited before ready (${code}, ${signal})\n${diagnostics}`);
+ }),
+ new Promise<never>((_, reject) => {
+ startupTimer = setTimeout(
+ () => reject(new Error(`Restart server startup timed out\n${diagnostics}`)),
+ 30_000,
+ );
+ }),
+ ]);
+ if (result.status === 'error') throw new Error(`${result.message}\n${diagnostics}`);
+ if (result.pid !== child.pid || result.port !== port) {
+ throw new Error('Restart server receipt does not match its owned child and port');
+ }
+ receipt = result;
+ } catch (error) {
+ kill();
+ await exited;
+ if (options.configHomedirOverride === undefined) removeAllStrictDuringTeardown(home);
+ if (options.contentDir === undefined) removeAllStrictDuringTeardown(contentDir);
+ throw error;
+ } finally {
+ if (startupTimer !== undefined) clearTimeout(startupTimer);
+ }
+ let restarted = false;
+ let shutdownPromise: Promise<void> | undefined;
+ const shutdown = (): Promise<void> => {
+ shutdownPromise ??= (async () => {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ if (child.exitCode === null && child.signalCode === null) child.send('shutdown');
+ const result = await Promise.race([
+ exited,
+ new Promise<never>((_, reject) => {
+ timer = setTimeout(() => {
+ kill();
+ reject(new Error(`Restart server shutdown timed out\n${diagnostics}`));
+ }, 15_000);
+ }),
+ ]);
+ if (result.code !== 0 && result.signal !== 'SIGKILL') {
+ throw new Error(
+ `Restart server shutdown failed (${result.code}, ${result.signal})\n${diagnostics}`,
+ );
+ }
+ } finally {
+ if (timer !== undefined) clearTimeout(timer);
+ kill();
+ await exited;
+ if (options.configHomedirOverride === undefined) removeAllStrictDuringTeardown(home);
+ if (!options.keepContentDir && !restarted) removeAllStrictDuringTeardown(contentDir);
+ }
+ })();
+ return shutdownPromise;
+ };
+ const restart = async (
+ mode: 'crash' | 'graceful',
+ downtimeMs: number,
+ ): Promise<RestartableServer> => {
+ restarted = true;
+ try {
+ if (mode === 'crash') {
+ kill();
+ await exited;
+ }
+ await shutdown();
+ await wait(downtimeMs);
+ return await createRestartableServer({ ...options, contentDir, port });
+ } catch (error) {
+ try {
+ await shutdown();
+ } finally {
+ if (!options.keepContentDir) removeAllStrictDuringTeardown(contentDir);
+ }
+ throw error;
+ }
+ };
+ return {
+ port,
+ contentDir,
+ pid: receipt.pid,
+ serverInstanceId: receipt.serverInstanceId,
+ exited,
+ killNetwork: kill,
+ disconnectOwner: () => child.disconnect(),
+ shutdown,
+ killAndRestartOnSamePort({ downtimeMs }) {
+ return restart('crash', downtimeMs);
+ },
+ shutdownAndRestartOnSamePort({ downtimeMs }) {
+ return restart('graceful', downtimeMs);
+ },
+ };
+}
diff --git a/packages/app/tests/integration/restartable-server.test.ts b/packages/app/tests/integration/restartable-server.test.ts
new file mode 100644
index 000000000..0d8d0ba40
--- /dev/null
+++ b/packages/app/tests/integration/restartable-server.test.ts
@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { expect, test } from 'vitest';
+import { createRestartableServer } from './restartable-server.test-helper.ts';
+
+test('the server process exits when its owning IPC channel closes without losing a persisted doc', async () => {
+ const server = await createRestartableServer();
+ try {
+ const write = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ docName: 'test-doc',
+ markdown: 'Owned paragraph\n',
+ position: 'replace',
+ agentId: 'owner',
+ }),
+ });
+ expect(write.status).toBe(200);
+ expect(readFileSync(join(server.contentDir, 'test-doc.md'), 'utf8')).toBe('Owned paragraph\n');
+ server.disconnectOwner();
+ expect(await server.exited).toEqual({ code: 1, signal: null });
+ expect(readFileSync(join(server.contentDir, 'test-doc.md'), 'utf8')).toBe('Owned paragraph\n');
+ } finally {
+ await expect(server.shutdown()).rejects.toThrow(/shutdown failed/);
+ }
+}, 30_000);
+
+test('process crash releases ownership only after exit and replacement uses a fresh epoch', async () => {
+ let server = await createRestartableServer();
+ const initial = server;
+ try {
+ await expect(createRestartableServer({ contentDir: initial.contentDir })).rejects.toThrow(
+ /already running|content ownership is already held/,
+ );
+ const info = await fetch(`http://127.0.0.1:${initial.port}/api/server-info`);
+ expect((await info.json()).serverInstanceId).toBe(initial.serverInstanceId);
+ server = await initial.killAndRestartOnSamePort({ downtimeMs: 0 });
+ expect(await initial.exited).toEqual({ code: null, signal: 'SIGKILL' });
+ expect(server.pid).not.toBe(initial.pid);
+ expect(server.serverInstanceId).not.toBe(initial.serverInstanceId);
+ const write = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ docName: 'test-doc',
+ markdown: 'Replacement owner\n',
+ position: 'replace',
+ agentId: 'replacement-owner',
+ }),
+ });
+ expect(write.status).toBe(200);
+ expect(readFileSync(join(server.contentDir, 'test-doc.md'), 'utf8')).toBe(
+ 'Replacement owner\n',
+ );
+ } finally {
+ await server.shutdown();
+ await initial.shutdown();
+ }
+}, 30_000);
diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.ts
index e930ae06f..c60cd145f 100644
--- a/packages/app/tests/integration/test-harness.ts
+++ b/packages/app/tests/integration/test-harness.ts
@@ -51,6 +51,7 @@ import { getSchema } from '@tiptap/core';
import { yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import * as Y from 'yjs';
import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';
+import { testAuthorityRegistryPath } from '../../../../test-support/server-authority-registry.test-helper.ts';
import {
ORIGIN_TEXT_TO_TREE,
ORIGIN_TREE_TO_TEXT,
@@ -82,6 +83,7 @@ export interface TestServer {
}
export interface CreateTestServerOptions {
+ authorityRegistryPath?: string;
ingressPolicy?: ServerOptions['ingressPolicy'];
debounce?: ServerOptions['debounce'];
maxDebounce?: ServerOptions['maxDebounce'];
@@ -155,6 +157,7 @@ export async function createTestServer(options: CreateTestServerOptions = {}): P
const port = await getFreePort();
const srv = createServer({
+ authorityRegistryPath: options.authorityRegistryPath ?? testAuthorityRegistryPath,
contentDir,
projectDir,
ingressPolicy: options.ingressPolicy,
@@ -257,6 +260,7 @@ export interface TestClient {
export interface CreateTestClientOptions {
skipInvariantWatcher?: boolean;
syncControl?: boolean;
+ resetOnCleanup?: boolean;
}
export async function createTestClient(
@@ -325,9 +329,11 @@ export async function createTestClient(
cleanup: async () => {
watcherDetach?.();
observerCleanup();
- try {
- await testReset(port, resolvedDocName);
- } catch {}
+ if (options?.resetOnCleanup !== false) {
+ try {
+ await testReset(port, resolvedDocName);
+ } catch {}
+ }
provider.destroy();
doc.destroy();
},
@@ -1018,20 +1024,21 @@ export async function assertAllConverged(
throw new ClientConvergenceError(details);
}
-export interface RestartableServer {
+export type { RestartableServer } from './restartable-server.test-helper.ts';
+export { createRestartableServer } from './restartable-server.test-helper.ts';
+
+export interface InspectableServer {
port: number;
contentDir: string;
instance: ServerInstance;
killNetwork(): void;
shutdown(): Promise<void>;
- killAndRestartOnSamePort(opts: { downtimeMs: number }): Promise<RestartableServer>;
}
-export interface CreateRestartableServerOptions extends CreateTestServerOptions {
+export interface CreateInspectableServerOptions extends CreateTestServerOptions {
port?: number;
gitEnabled?: boolean;
commitDebounceMs?: number;
- _retired?: RestartableServer[];
}
export async function waitForPortFree(port: number, timeoutMs = 2500): Promise<void> {
@@ -1058,9 +1065,9 @@ export async function waitForPortFree(port: number, timeoutMs = 2500): Promise<v
);
}
-export async function createRestartableServer(
- options: CreateRestartableServerOptions = {},
-): Promise<RestartableServer> {
+export async function createInspectableServer(
+ options: CreateInspectableServerOptions = {},
+): Promise<InspectableServer> {
const contentDir =
options.contentDir !== undefined
? realpathSync(options.contentDir)
@@ -1075,6 +1082,7 @@ export async function createRestartableServer(
const port = options.port ?? (await getFreePort());
const srv = createServer({
+ authorityRegistryPath: options.authorityRegistryPath ?? testAuthorityRegistryPath,
contentDir,
quiet: true,
debounce: options.debounce ?? 200,
@@ -1141,7 +1149,6 @@ export async function createRestartableServer(
};
await listenWithRetry();
- const retired: RestartableServer[] = [...(options._retired ?? [])];
let networkKilled = false;
const killNetwork = (): void => {
@@ -1174,34 +1181,17 @@ export async function createRestartableServer(
} catch (err) {
console.warn('[restartable-server] srv.destroy() failed:', err);
}
- for (const prev of retired) {
- try {
- await prev.shutdown();
- } catch {}
- }
if (!options.keepContentDir) {
removeAllStrictDuringTeardown(contentDir);
}
};
- const handle: RestartableServer = {
+ const handle: InspectableServer = {
port,
contentDir,
instance: srv,
killNetwork,
shutdown,
- killAndRestartOnSamePort: async ({ downtimeMs }) => {
- killNetwork();
- await wait(downtimeMs);
- await waitForPortFree(port, Math.max(2500, downtimeMs + 500));
- return createRestartableServer({
- ...options,
- port,
- contentDir,
- keepContentDir: true,
- _retired: [handle, ...retired],
- });
- },
};
return handle;
@@ -1319,7 +1309,7 @@ export interface MultiClientContext {
}
export async function createMultiClientContext(opts: {
- server: RestartableServer;
+ server: { port: number };
docName: string;
clientCount: number;
recycleDebounceMs?: number;
diff --git a/packages/app/tests/integration/wysiwyg-x20-cold-reopen.test.ts b/packages/app/tests/integration/wysiwyg-x20-cold-reopen.test.ts
index e9a80e697..3f5beed39 100644
--- a/packages/app/tests/integration/wysiwyg-x20-cold-reopen.test.ts
+++ b/packages/app/tests/integration/wysiwyg-x20-cold-reopen.test.ts
@@ -45,9 +45,7 @@ describe('WYSIWYG &#x20; literal after close + cold reopen (the reported bug)',
const client = await createTestClient(server.port, docName);
try {
- await pollUntil(() => serverFragment(server, docName) !== undefined, 10_000, 50);
- const fragment = serverFragment(server, docName);
- if (!fragment) throw new Error('doc not loaded on server after cold restart');
+ const fragment = client.fragment;
const shown = fragmentVisibleText(fragment);
expect(shown).not.toContain('&#x20;');
diff --git a/packages/cli/src/commands/removal-plan.test.ts b/packages/cli/src/commands/removal-plan.test.ts
index 654c5abf1..1072c863b 100644
--- a/packages/cli/src/commands/removal-plan.test.ts
+++ b/packages/cli/src/commands/removal-plan.test.ts
@@ -1353,7 +1353,7 @@ describe('uninstall owns only its own channel', () => {
expect(globalOp).toMatchObject({
path: join(home, '.ok'),
label:
- 'Remove ~/.ok (keeping ~/.ok/machine-id, ~/.ok/skills, ~/.ok/skills-lock.json, ~/.ok/local/installed-skills.json, ~/.ok/local/skill-placements.json, ~/.ok/local/skill-move-retained.json, shared by every channel)',
+ 'Remove ~/.ok (keeping ~/.ok/machine-id, ~/.ok/skills, ~/.ok/skills-lock.json, ~/.ok/local/installed-skills.json, ~/.ok/local/skill-placements.json, ~/.ok/local/skill-move-retained.json, ~/.ok/local/server-authority.sqlite, ~/.ok/local/server-authority.sqlite-journal, ~/.ok/local/server-authority-leases, shared by every channel)',
});
const paths = planPaths(plan.ops);
expect(paths).toContain(join(home, 'Library', 'Application Support', 'OpenKnowledge'));
@@ -1443,6 +1443,9 @@ describe('uninstall owns only its own channel', () => {
['local', 'installed-skills.json'],
['local', 'skill-placements.json'],
['local', 'skill-move-retained.json'],
+ ['local', 'server-authority.sqlite'],
+ ['local', 'server-authority.sqlite-journal'],
+ ['local', 'server-authority-leases', 'holder.sqlite'],
];
test.each([false, true])(
diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.ts
index 6748214f5..53ec2ceeb 100644
--- a/packages/cli/src/commands/start.test.ts
+++ b/packages/cli/src/commands/start.test.ts
@@ -5,6 +5,7 @@ import {
mkdtempSync,
readdirSync,
readFileSync,
+ realpathSync,
rmSync,
symlinkSync,
writeFileSync,
@@ -280,21 +281,49 @@ describe('withIdleShutdownProcessExit (idle-path zombie prevention)', () => {
});
describe('isServerLockCollision (D1/C3 gate)', () => {
+ test('same-project authority refusal is reusable before its discovery record appears', async () => {
+ const mod = await import('@inkeep/open-knowledge-server');
+ const fixture = mkdtempSync(join(tmpdir(), 'ok-reuse-authority-'));
+ const cwd = join(fixture, 'project');
+ const other = join(fixture, 'other-project');
+ const alias = join(fixture, 'alias');
+ mkdirSync(cwd);
+ mkdirSync(other);
+ symlinkSync(cwd, alias, 'junction');
+ const err = new mod.ServerAuthorityCollisionError({
+ projectDir: realpathSync.native(cwd),
+ scope: { kind: 'tree', path: cwd, excluded: [] },
+ pid: process.pid,
+ serverInstanceId: 'starting-holder',
+ });
+ try {
+ expect(isServerLockCollision(err, mod, cwd)).toBe(true);
+ expect(isServerLockCollision(err, mod, alias)).toBe(true);
+ expect(isServerLockCollision(err, mod, other)).toBe(false);
+ const preview = new mod.ServerAuthorityCollisionError({
+ ...err.existing,
+ scope: { kind: 'file', path: join(cwd, 'note.md') },
+ });
+ expect(isServerLockCollision(preview, mod, cwd)).toBe(false);
+ } finally {
+ rmSync(fixture, { recursive: true, force: true });
+ }
+ });
class FakeServerLockErr extends Error {}
const fakeModule = {
ServerLockCollisionError: FakeServerLockErr,
} as unknown as typeof import('@inkeep/open-knowledge-server');
test('true for a ServerLockCollisionError instance', () => {
- expect(isServerLockCollision(new FakeServerLockErr('held'), fakeModule)).toBe(true);
+ expect(isServerLockCollision(new FakeServerLockErr('held'), fakeModule, tmpdir())).toBe(true);
});
test('false for any other error', () => {
- expect(isServerLockCollision(new Error('boom'), fakeModule)).toBe(false);
- expect(isServerLockCollision('not-an-error', fakeModule)).toBe(false);
+ expect(isServerLockCollision(new Error('boom'), fakeModule, tmpdir())).toBe(false);
+ expect(isServerLockCollision('not-an-error', fakeModule, tmpdir())).toBe(false);
});
test('false (never throws) when the module lacks the class export', () => {
const empty = {} as unknown as typeof import('@inkeep/open-knowledge-server');
- expect(isServerLockCollision(new Error('boom'), empty)).toBe(false);
+ expect(isServerLockCollision(new Error('boom'), empty, tmpdir())).toBe(false);
});
});
@@ -1269,6 +1298,17 @@ describe('startCommand — --mode flag wiring', () => {
});
describe('tryDescribeLockCollision', () => {
+ test('overlapping content ownership has an actionable message without a stack', async () => {
+ const serverModule = await import('@inkeep/open-knowledge-server');
+ const err = new serverModule.ServerAuthorityCollisionError({
+ projectDir: '/holder',
+ scope: { kind: 'tree', path: '/content', excluded: [] },
+ pid: process.pid,
+ serverInstanceId: 'holder-instance',
+ });
+ expect(tryDescribeLockCollision(err, '/other', serverModule)).toBe(err.message);
+ expect(err.message).toContain('Close that session');
+ });
function fakeServerModule(opts: {
meta?: { kind?: string; pid?: number; port?: number; hostname?: string } | null;
throwOnRead?: boolean;
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
index 5ed796664..d64b17d85 100644
--- a/packages/cli/src/commands/start.ts
+++ b/packages/cli/src/commands/start.ts
@@ -748,7 +748,7 @@ export async function runStartCommand(configArg: Config, opts: StartCommandOptio
process.exit(1);
}
- if (isServerLockCollision(err, serverModule)) {
+ if (isServerLockCollision(err, serverModule, cwd)) {
const lockDir = serverModule.resolveLockDir(cwd);
let reuse: ServerReuseInfo | null = null;
try {
@@ -927,9 +927,19 @@ export function formatServerReuseNotice(info: ServerReuseInfo): string[] {
export function isServerLockCollision(
err: unknown,
serverModule: typeof import('@inkeep/open-knowledge-server'),
+ cwd: string,
): boolean {
const lockErr = serverModule.ServerLockCollisionError;
- return lockErr !== undefined && err instanceof lockErr;
+ if (lockErr !== undefined && err instanceof lockErr) return true;
+ const authorityErr = serverModule.ServerAuthorityCollisionError;
+ if (authorityErr === undefined || !(err instanceof authorityErr)) return false;
+ try {
+ return (
+ err.existing.scope.kind === 'tree' && realpathSync.native(cwd) === err.existing.projectDir
+ );
+ } catch {
+ return false;
+ }
}
export function tryDescribeLockCollision(
@@ -937,6 +947,10 @@ export function tryDescribeLockCollision(
cwd: string,
serverModule: typeof import('@inkeep/open-knowledge-server'),
): string | null {
+ const authorityErr = serverModule.ServerAuthorityCollisionError;
+ if (authorityErr !== undefined && err instanceof authorityErr) return err.message;
+ const registryErr = serverModule.ServerAuthorityRegistryError;
+ if (registryErr !== undefined && err instanceof registryErr) return err.message;
const lockErr = serverModule.ServerLockCollisionError;
if (lockErr === undefined || !(err instanceof lockErr)) return null;
diff --git a/packages/cli/src/commands/uninstall.test.ts b/packages/cli/src/commands/uninstall.test.ts
index 9154e780d..683fbd87e 100644
--- a/packages/cli/src/commands/uninstall.test.ts
+++ b/packages/cli/src/commands/uninstall.test.ts
@@ -582,7 +582,7 @@ describe('uninstallCommand', () => {
const command = uninstallCommand();
expect(command.description()).toContain('~/.ok (~/.ok-beta on Beta)');
const kept =
- '~/.ok/machine-id, ~/.ok/skills-lock.json, ~/.ok/local/installed-skills.json, ~/.ok/local/skill-placements.json, ~/.ok/local/skill-move-retained.json';
+ '~/.ok/machine-id, ~/.ok/skills-lock.json, ~/.ok/local/installed-skills.json, ~/.ok/local/skill-placements.json, ~/.ok/local/skill-move-retained.json, ~/.ok/local/server-authority.sqlite, ~/.ok/local/server-authority.sqlite-journal, ~/.ok/local/server-authority-leases';
expect(command.description()).toContain(`always keeps ${kept}, shared by every channel.`);
expect(command.options.find((o) => o.long === '--purge-content')?.description).toBe(
`Also remove user-authored content (~/.ok/skills, shared by every channel); still keeps ${kept}`,
diff --git a/packages/core/src/constants/shared-ok-entries.test.ts b/packages/core/src/constants/shared-ok-entries.test.ts
index a1f235fb8..7469f9456 100644
--- a/packages/core/src/constants/shared-ok-entries.test.ts
+++ b/packages/core/src/constants/shared-ok-entries.test.ts
@@ -4,6 +4,8 @@ import { SKILLS_LOCK_REL } from '../skills-catalog/acquire/lockfile.ts';
import { LOCAL_DIR, OK_DIR } from './ok-dir.ts';
import {
MACHINE_ID_FILENAME,
+ SERVER_AUTHORITY_LEASES_DIRNAME,
+ SERVER_AUTHORITY_REGISTRY_FILENAME,
SHARED_OK_ENTRIES,
SKILL_MOVE_RETAINED_FILENAME,
SKILL_PLACEMENTS_FILENAME,
@@ -24,6 +26,9 @@ describe('SHARED_OK_ENTRIES', () => {
'local/installed-skills.json',
'local/skill-placements.json',
'local/skill-move-retained.json',
+ 'local/server-authority.sqlite',
+ 'local/server-authority.sqlite-journal',
+ 'local/server-authority-leases',
]);
expect(SHARED_OK_ENTRIES).toEqual([
MACHINE_ID_FILENAME,
@@ -32,6 +37,9 @@ describe('SHARED_OK_ENTRIES', () => {
okRelative(INSTALLED_SKILLS_REL),
`${LOCAL_DIR}/${SKILL_PLACEMENTS_FILENAME}`,
`${LOCAL_DIR}/${SKILL_MOVE_RETAINED_FILENAME}`,
+ `${LOCAL_DIR}/${SERVER_AUTHORITY_REGISTRY_FILENAME}`,
+ `${LOCAL_DIR}/${SERVER_AUTHORITY_REGISTRY_FILENAME}-journal`,
+ `${LOCAL_DIR}/${SERVER_AUTHORITY_LEASES_DIRNAME}`,
]);
});
});
diff --git a/packages/core/src/constants/shared-ok-entries.ts b/packages/core/src/constants/shared-ok-entries.ts
index 5f79e4b7b..3412f9c48 100644
--- a/packages/core/src/constants/shared-ok-entries.ts
+++ b/packages/core/src/constants/shared-ok-entries.ts
@@ -10,6 +10,10 @@ export const SKILL_PLACEMENTS_FILENAME = 'skill-placements.json';
export const SKILL_MOVE_RETAINED_FILENAME = 'skill-move-retained.json';
+export const SERVER_AUTHORITY_REGISTRY_FILENAME = 'server-authority.sqlite';
+
+export const SERVER_AUTHORITY_LEASES_DIRNAME = 'server-authority-leases';
+
export const SHARED_OK_ENTRIES: readonly string[] = [
MACHINE_ID_FILENAME,
SKILLS_STORE_DIRNAME,
@@ -17,4 +21,7 @@ export const SHARED_OK_ENTRIES: readonly string[] = [
`${LOCAL_DIR}/${INSTALLED_SKILLS_FILENAME}`,
`${LOCAL_DIR}/${SKILL_PLACEMENTS_FILENAME}`,
`${LOCAL_DIR}/${SKILL_MOVE_RETAINED_FILENAME}`,
+ `${LOCAL_DIR}/${SERVER_AUTHORITY_REGISTRY_FILENAME}`,
+ `${LOCAL_DIR}/${SERVER_AUTHORITY_REGISTRY_FILENAME}-journal`,
+ `${LOCAL_DIR}/${SERVER_AUTHORITY_LEASES_DIRNAME}`,
];
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 3340b78a4..4c9385f1c 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -560,6 +560,8 @@ export { isReservedLogDoc } from './constants/reserved-docs.ts';
export { DEFAULT_SERVER_HOST } from './constants/server.ts';
export {
MACHINE_ID_FILENAME,
+ SERVER_AUTHORITY_LEASES_DIRNAME,
+ SERVER_AUTHORITY_REGISTRY_FILENAME,
SHARED_OK_ENTRIES,
SKILL_MOVE_RETAINED_FILENAME,
SKILL_PLACEMENTS_FILENAME,
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index ea72dcef3..2e7dc1e81 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -2150,6 +2150,15 @@ async function openProjectOrFallbackToNavigator(
} else if (kind === 'lock-collision') {
dialogTitle = 'OpenKnowledge is already running for this project';
dialogBody = `${projectPath}\n\n${errorMessage}`;
+ } else if (kind === 'content-ownership') {
+ dialogTitle = 'This content is already open';
+ dialogBody = `${projectPath}\n\n${errorMessage}`;
+ } else if (kind === 'content-ownership-unverified') {
+ dialogTitle = 'OpenKnowledge cannot safely open this content';
+ dialogBody = `${projectPath}\n\n${errorMessage}`;
+ } else if (kind === 'authority-registry') {
+ dialogTitle = 'OpenKnowledge cannot safely open this folder';
+ dialogBody = `${projectPath}\n\n${errorMessage}`;
} else if (kind === 'stale-lock-holder') {
dialogTitle =
staleLockReason === 'lock-not-attachable'
diff --git a/packages/desktop/src/utility/server-entry.test.ts b/packages/desktop/src/utility/server-entry.test.ts
index 77f48bc6d..7200124e1 100644
--- a/packages/desktop/src/utility/server-entry.test.ts
+++ b/packages/desktop/src/utility/server-entry.test.ts
@@ -234,6 +234,27 @@ describe('port pinning + EADDRINUSE fallback', () => {
});
});
+describe('ownership startup errors', () => {
+ test.each([
+ ['ServerAuthorityCollisionError', 'content-ownership'],
+ ['ServerAuthorityCollisionError', 'content-ownership-unverified'],
+ ['ServerAuthorityRegistryError', 'authority-registry'],
+ ])('reports %s without offering an unowned process takeover', async (name, kind) => {
+ const error = new Error('Close the preview before opening this folder');
+ error.name = name;
+ if (kind === 'content-ownership-unverified') Object.assign(error, { verifiedLease: false });
+ const { posted, bootPorts, readyErr } = await driveInit({
+ requestedPort: 24550,
+ boot: () => Promise.reject(error),
+ });
+ expect(readyErr).toBe(error);
+ expect(bootPorts).toEqual([24550]);
+ const message = posted.find((item) => item.type === 'error');
+ expect(message).toMatchObject({ kind, message: error.message });
+ expect(message).not.toHaveProperty('existingLock');
+ });
+});
+
describe('shutdown exit reason', () => {
async function drive() {
return driveInit({
diff --git a/packages/desktop/src/utility/server-entry.ts b/packages/desktop/src/utility/server-entry.ts
index ac1e7745a..3abc4d962 100644
--- a/packages/desktop/src/utility/server-entry.ts
+++ b/packages/desktop/src/utility/server-entry.ts
@@ -5,6 +5,7 @@ import type {
BootedServer,
BootServerOptions,
Config,
+ ServerAuthorityCollisionError,
ServerExitReason,
} from '@inkeep/open-knowledge-server';
import type { UtilityInitCounters, UtilityInitPhase } from '../shared/boot-narration.ts';
@@ -51,7 +52,13 @@ export interface UtilityErrorMessage {
type: 'error';
message: string;
stack?: string;
- kind?: 'lock-collision' | 'mcp-server-stuck' | 'mcp-server-killed';
+ kind?:
+ | 'lock-collision'
+ | 'mcp-server-stuck'
+ | 'mcp-server-killed'
+ | 'content-ownership'
+ | 'content-ownership-unverified'
+ | 'authority-registry';
existingLock?: {
pid: number;
hostname: string;
@@ -316,6 +323,13 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
errMsg.kind = 'lock-collision';
errMsg.existingLock = existing;
}
+ } else if (errName === 'ServerAuthorityCollisionError') {
+ errMsg.kind =
+ (err as ServerAuthorityCollisionError).verifiedLease === false
+ ? 'content-ownership-unverified'
+ : 'content-ownership';
+ } else if (errName === 'ServerAuthorityRegistryError') {
+ errMsg.kind = 'authority-registry';
}
const isGitPreflightFailure =
errName === 'GitNotAvailableError' || errName === 'GitTooOldError';
diff --git a/packages/server/src/agent-sessions.test.ts b/packages/server/src/agent-sessions.test.ts
index b9d8a20ee..0814b8309 100644
--- a/packages/server/src/agent-sessions.test.ts
+++ b/packages/server/src/agent-sessions.test.ts
@@ -89,6 +89,25 @@ afterEach(async () => {
});
describe('getSession — composite key (docName + agentId)', () => {
+ test('rechecks scope admission before returning cached sessions and burst reads', async () => {
+ let admitted = true;
+ manager = new AgentSessionManager(mockHocuspocus as never, {
+ assertDocumentScope: () => {
+ if (!admitted) throw new Error('Scope no longer admitted');
+ },
+ });
+ await manager.getSession('doc.md', 'agent-alice');
+ expect(manager.getLiveSession('doc.md', 'agent-alice')).toBeDefined();
+ admitted = false;
+ await expect(manager.getSession('doc.md', 'agent-alice')).rejects.toThrow(
+ 'Scope no longer admitted',
+ );
+ expect(() => manager.getLiveSession('doc.md', 'agent-alice')).toThrow(
+ 'Scope no longer admitted',
+ );
+ expect(mockHocuspocus.openedDocs).toEqual(['doc.md']);
+ });
+
test('creates a session on first call', async () => {
await manager.getSession('doc.md', 'agent-alice');
expect(manager.hasSession('doc.md', 'agent-alice')).toBe(true);
diff --git a/packages/server/src/agent-sessions.ts b/packages/server/src/agent-sessions.ts
index b0ba82f3f..9ce3289e1 100644
--- a/packages/server/src/agent-sessions.ts
+++ b/packages/server/src/agent-sessions.ts
@@ -567,6 +567,7 @@ export class AgentSessionManager {
private readonly maxSessions: number;
private readonly minEvictableIdleMs: number;
private bridgeLossReporter?: BridgeDeriveLossReporter;
+ private readonly assertDocumentScope?: (docName: string) => void;
private evictions = 0;
constructor(
@@ -575,12 +576,14 @@ export class AgentSessionManager {
maxSessions?: number;
minEvictableIdleMs?: number;
bridgeLossReporter?: BridgeDeriveLossReporter;
+ assertDocumentScope?: (docName: string) => void;
} = {},
) {
this.hocuspocus = hocuspocus;
this.maxSessions = options.maxSessions ?? MAX_AGENT_SESSIONS;
this.minEvictableIdleMs = options.minEvictableIdleMs ?? MIN_EVICTABLE_IDLE_MS;
this.bridgeLossReporter = options.bridgeLossReporter;
+ this.assertDocumentScope = options.assertDocumentScope;
}
public attachBridgeLossReporter(reporter: BridgeDeriveLossReporter): void {
@@ -617,6 +620,7 @@ export class AgentSessionManager {
}
public getLiveSession(docName: string, agentId: string): SessionRecord | undefined {
+ this.assertDocumentScope?.(docName);
const key = this.sessionKey(docName, agentId);
const session = this.sessions.get(key);
if (session) this.touchSession(key, session);
@@ -668,6 +672,7 @@ export class AgentSessionManager {
if (isSystemDoc(docName) || isConfigDoc(docName)) {
throw new Error(`Cannot create agent session for reserved doc: ${docName}`);
}
+ this.assertDocumentScope?.(docName);
const key = this.sessionKey(docName, agentId);
const existing = this.sessions.get(key);
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index e27897e59..bf9831ec9 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -346,12 +346,14 @@ import {
incrementSummariesTruncated,
} from './metrics.ts';
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 { ServerMutationShuttingDownError } from './server-content-policy.ts';
import type { PairedWriteOrigin } from './server-observers.ts';
import { createAssetService } from './services/assets.ts';
import { createFileOpsService, DuplicateNameExhaustedError } from './services/file-ops.ts';
@@ -974,7 +976,11 @@ function requireNonEmptyDocName(
return null;
}
-function resolveContentEntryPath(contentDir: string, kind: ContentEntryKind, path: string): string {
+function resolveUncheckedContentEntryPath(
+ contentDir: string,
+ kind: ContentEntryKind,
+ path: string,
+): string {
if (!isValidRelativeContentPath(path)) {
throw new PathContainmentError('path must be a relative content path');
}
@@ -1074,7 +1080,7 @@ function nextAvailableDuplicateFolderPath(
const { parent, basename } = splitContentPath(sourceFolderPath);
for (let attempt = 1; attempt <= 10_000; attempt += 1) {
const candidate = joinContentPath(parent, duplicateBasename(basename, attempt));
- const fullPath = resolveContentEntryPath(contentDir, 'folder', candidate);
+ const fullPath = resolveUncheckedContentEntryPath(contentDir, 'folder', candidate);
if (!existsSync(fullPath)) return { folderPath: candidate, attempt };
}
throw new DuplicateNameExhaustedError(sourceFolderPath);
@@ -1084,7 +1090,7 @@ function collectMarkdownCopies(
contentDir: string,
folderPath: string,
): Array<{ docName: string; fullPath: string; content: string }> {
- const folderAbs = resolveContentEntryPath(contentDir, 'folder', folderPath);
+ const folderAbs = resolveUncheckedContentEntryPath(contentDir, 'folder', folderPath);
const docs: Array<{ docName: string; fullPath: string; content: string }> = [];
function walk(absDir: string, relDir: string): void {
@@ -1110,7 +1116,7 @@ function collectMarkdownCopies(
}
function collectFolderPaths(contentDir: string, folderPath: string): string[] {
- const folderAbs = resolveContentEntryPath(contentDir, 'folder', folderPath);
+ const folderAbs = resolveUncheckedContentEntryPath(contentDir, 'folder', folderPath);
const folders: string[] = [folderPath];
function walk(absDir: string, relDir: string): void {
@@ -1270,6 +1276,8 @@ interface ApiExtensionBaseOptions {
durabilityState: DocumentDurabilityState;
sessionManager: AgentSessionManager;
contentDir: string;
+ assertContentPath?: (path: string) => void;
+ assertContentSubtree?: (path: string) => void;
getGeneratedIndexSettingsStatus?: () => GeneratedIndexSettingsStatus;
setGeneratedIndexEnabled?: (enabled: boolean) => Promise<GeneratedIndexSettingsStatus>;
ephemeral?: boolean;
@@ -1446,6 +1454,20 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
shutdownLocalOps(): Promise<void>;
} {
const { durabilityState } = options;
+ let closingMutations = false;
+ const pendingMutations = new Set<Promise<void>>();
+ async function dispatchMutation(operation: () => Promise<void>, pathname: string): Promise<void> {
+ if (closingMutations)
+ throw new ServerMutationShuttingDownError(pathname.startsWith('/api/local-op/'));
+ const task = operation();
+ pendingMutations.add(task);
+ try {
+ await task;
+ } finally {
+ pendingMutations.delete(task);
+ }
+ }
+ const assertContentSubtree = options.assertContentSubtree;
const ingressPolicy = options.ingressPolicy ?? buildIngressPolicy({});
const checkLocalOpSecurity = (
req: IncomingMessage,
@@ -1535,6 +1557,11 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
localOpCliArgs,
declaredGitHubHosts,
});
+ function resolveContentEntryPath(dir: string, kind: ContentEntryKind, path: string): string {
+ const resolved = resolveUncheckedContentEntryPath(dir, kind, path);
+ options.assertContentPath?.(resolved);
+ return resolved;
+ }
const catalogCache = createSkillsCatalogCache({ homeDirOverride, log });
const { bumpSkillsCatalogGen, enumerateInstalledSkillsCached, pluginSkillsByName } = catalogCache;
const signalChannel: typeof rawSignalChannel = rawSignalChannel
@@ -2780,6 +2807,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
) {
throw new ManagedRenameSourceTypeMismatchError(kind);
}
+ if (kind === 'folder') {
+ assertProjectContentSubtree(sourcePathRoot, contentDir);
+ assertContentSubtree?.(sourcePathRoot);
+ }
const renamedAssets =
kind === 'folder'
? listRenamedAssetsForFolderMove(sourcePathRoot, fromPath, toPath)
@@ -3975,11 +4006,13 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
const assetService = createAssetService({
contentDir,
+ assertContentPath: options.assertContentPath,
isPathIgnored: (relativePath) => contentFilter?.isPathIgnored(relativePath) ?? false,
getAttachmentFolderPath,
resolveTrackedFile,
});
const fileOpsService = createFileOpsService({
+ assertContentSubtree,
contentDir,
resolveContentEntryPath,
docNameForPath: (relPath) => docNameForFileOperationPath(contentDir, relPath),
@@ -4006,8 +4039,11 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
nextAvailableDuplicateDocName(contentDir, sourceDocName),
nextAvailableDuplicateFolderPath: (sourceFolderPath) =>
nextAvailableDuplicateFolderPath(contentDir, sourceFolderPath),
- resolveDuplicateDocPath: (docName, extension) =>
- resolveDuplicateDocPath(contentDir, docName, extension),
+ resolveDuplicateDocPath: (docName, extension) => {
+ const path = resolveDuplicateDocPath(contentDir, docName, extension);
+ options.assertContentPath?.(path);
+ return path;
+ },
collectMarkdownCopies: (folderPath) => collectMarkdownCopies(contentDir, folderPath),
collectFolderPaths: (folderPath) => collectFolderPaths(contentDir, folderPath),
contentFilter: contentFilter ?? undefined,
@@ -4881,6 +4917,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
policy: ingressPolicy,
ephemeral,
table: apiRouteTable,
+ dispatchMutation,
});
const linkGraphRoutes = createLinkGraphRoutes({
@@ -5402,6 +5439,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
policy: ingressPolicy,
ephemeral,
table: group.table,
+ dispatchMutation,
}),
);
const nativeApi: NativeApiHandle = {
@@ -5433,7 +5471,12 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
const resolveLocalApiNativeDispatch = (pathname: string) => {
for (const table of localApiNativeTables) {
const dispatch = table.resolve(pathname)?.dispatch;
- if (dispatch !== undefined) return dispatch;
+ if (dispatch !== undefined) {
+ return table.isMutating(pathname)
+ ? (req: IncomingMessage, res: ServerResponse) =>
+ dispatchMutation(() => dispatch(req, res), pathname)
+ : dispatch;
+ }
}
return undefined;
};
@@ -5446,7 +5489,11 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
resolve: (pathname) => {
if (!MCP_LOCAL_API_PATHS.has(pathname)) return undefined;
const legacy = routes[pathname];
- if (legacy !== undefined) return legacy;
+ if (legacy !== undefined) {
+ return apiRouteTable.isMutating(pathname)
+ ? (req, res) => dispatchMutation(() => legacy(req, res), pathname)
+ : legacy;
+ }
return resolveLocalApiNativeDispatch(pathname);
},
});
@@ -5458,6 +5505,11 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
},
nativeApi,
localApi,
- shutdownLocalOps: localOpRoutes.shutdown,
+ shutdownLocalOps: async () => {
+ closingMutations = true;
+ const results = await Promise.allSettled([...pendingMutations, localOpRoutes.shutdown()]);
+ const localOps = results.at(-1);
+ if (localOps?.status === 'rejected') throw localOps.reason;
+ },
};
}
diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.ts
index 2727a5d10..13e60a582 100644
--- a/packages/server/src/boot.ts
+++ b/packages/server/src/boot.ts
@@ -136,6 +136,7 @@ export interface BootServerOptions
| 'commitDebounceMs'
| 'wipRef'
| 'destroyTimeoutMs'
+ | 'authorityRegistryPath'
| 'localOpCliArgs'
| 'authStreamHeartbeatMs'
| 'onAgentWrite'
@@ -377,6 +378,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {
let collabClientCounter: CollabClientCounter | null = null;
const serverInstance = createServer({
+ authorityRegistryPath: opts.authorityRegistryPath,
getCollabClientCount: () => collabClientCounter?.getCount() ?? 0,
acpRegistryFetchImpl: opts.acpRegistryFetchImpl,
contentDir: opts.contentDir,
diff --git a/packages/server/src/composition-rig.test-helper.ts b/packages/server/src/composition-rig.test-helper.ts
index a0431aeb7..a8b71141e 100644
--- a/packages/server/src/composition-rig.test-helper.ts
+++ b/packages/server/src/composition-rig.test-helper.ts
@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { Readable } from 'node:stream';
import { OK_DIR } from '@inkeep/open-knowledge-core';
+import { testAuthorityRegistryPath } from '../../../test-support/server-authority-registry.test-helper.ts';
import { type BootedServer, type BootServerOptions, bootServer } from './boot.ts';
import { ConfigSchema } from './config/schema.ts';
@@ -42,6 +43,7 @@ export async function bootCompositionRig(
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
+ authorityRegistryPath: testAuthorityRegistryPath,
...overrides,
configHomedirOverride: ownedHome,
});
diff --git a/packages/server/src/conflict-authority.ts b/packages/server/src/conflict-authority.ts
index afade0f68..3328d7eb6 100644
--- a/packages/server/src/conflict-authority.ts
+++ b/packages/server/src/conflict-authority.ts
@@ -74,6 +74,7 @@ export interface ConflictIo {
export interface ConflictAuthorityOptions {
projectDir: string;
contentDir: string;
+ assertResolutionPath?: (path: string) => void;
branch?: string;
signal?: Pick<CC1Broadcaster, 'signal'> | null;
io: ConflictIo;
@@ -225,6 +226,7 @@ function migrateLedgerEntry(raw: LegacyLedgerEntry, currentBranch: string): Conf
}
export class ConflictAuthority implements ConflictReader {
+ private readonly assertResolutionPath?: (path: string) => void;
private readonly storePath: string;
private readonly projectDir: string;
private readonly contentDir: string;
@@ -236,6 +238,7 @@ export class ConflictAuthority implements ConflictReader {
private branch: string;
constructor(options: ConflictAuthorityOptions) {
+ this.assertResolutionPath = options.assertResolutionPath;
this.projectDir = options.projectDir;
this.contentDir = options.contentDir;
this.io = options.io;
@@ -529,6 +532,7 @@ export class ConflictAuthority implements ConflictReader {
async resolve(file: string, strategy: ResolveStrategy, content?: string): Promise<void> {
const entry = this.byFile.get(file);
if (entry === undefined) throw new NoConflictTrackedError({ file });
+ this.assertResolutionPath?.(resolve(this.projectDir, file));
if (strategy === 'content') requireConflictResolutionContent(file, content);
diff --git a/packages/server/src/content-filter.test.ts b/packages/server/src/content-filter.test.ts
index 02abd1334..266431a85 100644
--- a/packages/server/src/content-filter.test.ts
+++ b/packages/server/src/content-filter.test.ts
@@ -1,8 +1,8 @@
import { execFileSync } from 'node:child_process';
-import { mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { mkdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, sep } from 'node:path';
import { context, metrics, trace } from '@opentelemetry/api';
import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
import {
@@ -40,6 +40,31 @@ describe('ContentFilter', () => {
await rm(xdgDir, { recursive: true, force: true });
});
+ test.each([
+ ['sync', createContentFilter],
+ ['async', createContentFilterAsync],
+ ] as const)(
+ '%s filtering preserves captured exclusions after a nested marker is removed',
+ async (_name, create) => {
+ const child = join(projectDir, 'child');
+ mkdirSync(join(child, '.ok'), { recursive: true });
+ writeFileSync(join(child, '.ok', 'config.yml'), '');
+ writeFileSync(join(child, 'note.md'), '# Child\n');
+ const filter = await create({
+ projectDir,
+ contentDir: projectDir,
+ isContentScopeExcluded: (path) => path === child || path.startsWith(`${child}${sep}`),
+ });
+ unlinkSync(join(child, '.ok', 'config.yml'));
+ await filter.rebuildIgnorePatterns();
+ expect(filter.isExcluded('child/note.md')).toBe(true);
+ expect(filter.isDirExcluded('child')).toBe(true);
+ expect(filter.isExcluded('child/note.md', { bypassFilters: true, showOk: true })).toBe(true);
+ expect(filter.isDirExcluded('child', { syncScope: { pathBase: 'project' } })).toBe(true);
+ expect(filter.isExcluded('own.md')).toBe(false);
+ },
+ );
+
describe('sync-popover open-target admission', () => {
const openable = (filter: ContentFilter, relPath: string): boolean =>
!filter.isExcluded(relPath, { bypassFilters: true, showOk: true });
diff --git a/packages/server/src/content-filter.ts b/packages/server/src/content-filter.ts
index f88201aaa..4646413a3 100644
--- a/packages/server/src/content-filter.ts
+++ b/packages/server/src/content-filter.ts
@@ -394,6 +394,7 @@ function createDescendantProjectGate(
projectDir: string,
contentDir: string,
singleDocRelPath: string | undefined,
+ isContentScopeExcluded?: (absolutePath: string) => boolean,
): {
isInside: (relativePath: string, syncScope?: { pathBase: 'content' | 'project' }) => boolean;
reset: () => void;
@@ -418,6 +419,7 @@ function createDescendantProjectGate(
isInside(relativePath: string, syncScope?: { pathBase: 'content' | 'project' }): boolean {
if (!enabled || relativePath === '') return false;
const base = syncScope?.pathBase === 'project' ? projectDir : contentDir;
+ if (isContentScopeExcluded?.(resolve(base, relativePath))) return true;
let prefix = base;
for (const segment of relativePath.split('/')) {
prefix = join(prefix, segment);
@@ -583,6 +585,7 @@ async function appendExcludeFileIfExistsAsync(
export interface ContentFilterOptions {
projectDir: string;
contentDir: string;
+ isContentScopeExcluded?: (absolutePath: string) => boolean;
singleDocRelPath?: string;
attachmentFolderPath?: string;
inPlaceSkillDirs?: ReadonlySet<string>;
@@ -652,7 +655,12 @@ export function createContentFilter(opts: ContentFilterOptions): ContentFilter {
opts.attachmentFolderPath ?? DEFAULT_ATTACHMENT_FOLDER_PATH,
);
const skillRootPaths: ReadonlySet<string> = opts.skillRootPaths ?? new Set();
- const descendantProjects = createDescendantProjectGate(projectDir, contentDir, singleDocRelPath);
+ const descendantProjects = createDescendantProjectGate(
+ projectDir,
+ contentDir,
+ singleDocRelPath,
+ opts.isContentScopeExcluded,
+ );
const contentRelPrefix = toPosix(relative(projectDir, contentDir));
const contentOutsideProject = contentRelPrefix.startsWith('..');
@@ -1309,7 +1317,12 @@ export async function createContentFilterAsync(opts: ContentFilterOptions): Prom
opts.attachmentFolderPath ?? DEFAULT_ATTACHMENT_FOLDER_PATH,
);
const skillRootPaths: ReadonlySet<string> = opts.skillRootPaths ?? new Set();
- const descendantProjects = createDescendantProjectGate(projectDir, contentDir, singleDocRelPath);
+ const descendantProjects = createDescendantProjectGate(
+ projectDir,
+ contentDir,
+ singleDocRelPath,
+ opts.isContentScopeExcluded,
+ );
const contentRelPrefix = toPosix(relative(projectDir, contentDir));
const contentOutsideProject = contentRelPrefix.startsWith('..');
diff --git a/packages/server/src/content-path.test.ts b/packages/server/src/content-path.test.ts
new file mode 100644
index 000000000..a1daa049c
--- /dev/null
+++ b/packages/server/src/content-path.test.ts
@@ -0,0 +1,60 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, expect, test } from 'vitest';
+import { safeContentPath } from './content-path.ts';
+
+let root: string;
+
+beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), 'ok-content-scope-'));
+});
+
+afterEach(() => {
+ rmSync(root, { recursive: true, force: true });
+});
+
+function markProject(path: string): void {
+ mkdirSync(join(path, '.ok'), { recursive: true });
+ writeFileSync(join(path, '.ok', 'config.yml'), '');
+}
+
+test('refuses existing and new documents owned by a nested project', () => {
+ const child = join(root, 'child');
+ markProject(root);
+ markProject(child);
+ writeFileSync(join(child, 'existing.md'), '# Child\n');
+ expect(() => safeContentPath('child/existing', root)).toThrow(/nested project/i);
+ expect(() => safeContentPath('child/new/deep', root)).toThrow(/nested project/i);
+ expect(safeContentPath('existing', child)).toBe(join(child, 'existing.md'));
+});
+
+test('folder metadata does not split project ownership', () => {
+ mkdirSync(join(root, 'notes', '.ok'), { recursive: true });
+ writeFileSync(join(root, 'notes', '.ok', 'frontmatter.yml'), 'icon: note\n');
+ expect(safeContentPath('notes/new', root)).toBe(join(root, 'notes', 'new.md'));
+});
+
+test('detects a project marker created after an earlier path resolution', () => {
+ expect(safeContentPath('child/new', root)).toBe(join(root, 'child', 'new.md'));
+ markProject(join(root, 'child'));
+ expect(() => safeContentPath('child/new', root)).toThrow(/nested project/i);
+});
+
+test('refuses an alias into a nested project, including a missing destination', () => {
+ const child = join(root, 'child');
+ markProject(child);
+ writeFileSync(join(child, 'existing.md'), '# Child\n');
+ symlinkSync(child, join(root, 'alias'), 'junction');
+ symlinkSync(join(child, 'existing.md'), join(root, 'file-alias.md'), 'file');
+ expect(() => safeContentPath('file-alias', root)).toThrow(/nested project/i);
+ expect(() => safeContentPath('alias/existing', root)).toThrow(/nested project/i);
+ expect(() => safeContentPath('alias/new/deep', root)).toThrow(/nested project/i);
+});
+
+test('a symlink to the current project root does not create a new project', () => {
+ markProject(root);
+ writeFileSync(join(root, 'own.md'), '# Own\n');
+ symlinkSync(root, join(root, 'self'), 'junction');
+ expect(safeContentPath('self/own', root)).toBe(join(root, 'self', 'own.md'));
+});
diff --git a/packages/server/src/content-path.ts b/packages/server/src/content-path.ts
index f4b79f743..6490d3153 100644
--- a/packages/server/src/content-path.ts
+++ b/packages/server/src/content-path.ts
@@ -1,6 +1,7 @@
import { resolve } from 'node:path';
import { docNameToRelativePath } from './doc-extensions.ts';
import { isWithinDir } from './path-utils.ts';
+import { assertProjectContentScope } from './project-content-scope.ts';
export function safeContentPath(documentName: string, contentDir: string): string {
if (documentName.includes('\x00')) {
@@ -11,6 +12,7 @@ export function safeContentPath(documentName: string, contentDir: string): strin
if (!isWithinDir(filePath, contentDir)) {
throw new Error(`Invalid document name: ${documentName}`);
}
+ assertProjectContentScope(filePath, contentDir);
return filePath;
}
diff --git a/packages/server/src/derived-document-index.test.ts b/packages/server/src/derived-document-index.test.ts
index 0499be871..d33b3459b 100644
--- a/packages/server/src/derived-document-index.test.ts
+++ b/packages/server/src/derived-document-index.test.ts
@@ -717,8 +717,8 @@ describe('DerivedDocumentIndex', () => {
const startup = index.beginStartup('main');
+ await expect(startup.offlineDeletionsReady).resolves.toEqual(['stale']);
await expect(startup.backlinksReady).resolves.toEqual({
- deletedDocNames: ['stale'],
backlinkIndexDegraded: false,
});
await index.settleStartupAfterWatcherSeed();
@@ -734,8 +734,8 @@ describe('DerivedDocumentIndex', () => {
new Error('broken tag cache'),
);
const startup = rig.index.beginStartup('main');
+ await expect(startup.offlineDeletionsReady).resolves.toEqual([]);
await expect(startup.backlinksReady).resolves.toEqual({
- deletedDocNames: [],
backlinkIndexDegraded: true,
});
vi.spyOn(TagIndex.prototype, 'reconcileWithDisk').mockRejectedValueOnce(
diff --git a/packages/server/src/derived-document-index.ts b/packages/server/src/derived-document-index.ts
index a960cc916..2008f2625 100644
--- a/packages/server/src/derived-document-index.ts
+++ b/packages/server/src/derived-document-index.ts
@@ -53,7 +53,6 @@ export function isDerivedOrphanMode(value: unknown): value is DerivedOrphanMode
}
export interface DerivedIndexStartupBacklinksResult {
- deletedDocNames: readonly string[];
backlinkIndexDegraded: boolean;
}
@@ -257,7 +256,10 @@ export class DerivedDocumentIndex
this.localTargetFileExistenceTimer.unref?.();
}
- beginStartup(branch: string): { backlinksReady: Promise<DerivedIndexStartupBacklinksResult> } {
+ beginStartup(branch: string): {
+ backlinksReady: Promise<DerivedIndexStartupBacklinksResult>;
+ offlineDeletionsReady: Promise<readonly string[]>;
+ } {
this.assertOpen();
if (this.startupBegun) {
throw new Error('Derived document index startup has already begun');
@@ -267,11 +269,12 @@ export class DerivedDocumentIndex
this.startupBranch = branch;
this.backlinkIndex.switchBranch(branch);
- const backlinksReady = this.initializeBacklinks(branch);
+ const offlineDeletions = Promise.withResolvers<readonly string[]>();
+ const backlinksReady = this.initializeBacklinks(branch, offlineDeletions.resolve);
const tagsWarm = this.warmTags();
this.tail = Promise.all([backlinksReady.then(() => undefined), tagsWarm]).then(() => undefined);
this.startupAdmission.resolve();
- return { backlinksReady };
+ return { backlinksReady, offlineDeletionsReady: offlineDeletions.promise };
}
async settleStartupAfterWatcherSeed(): Promise<DerivedIndexStartupSettlement> {
@@ -727,13 +730,15 @@ export class DerivedDocumentIndex
});
}
- private async initializeBacklinks(branch: string): Promise<DerivedIndexStartupBacklinksResult> {
+ private async initializeBacklinks(
+ branch: string,
+ resolveOfflineDeletions: (deletedDocNames: readonly string[]) => void,
+ ): Promise<DerivedIndexStartupBacklinksResult> {
try {
- let deletedDocNames: readonly string[] = [];
this.graphFileOracle();
if (await this.backlinkIndex.loadFromDisk(branch)) {
const diff = await this.backlinkIndex.reconcileWithDisk(branch);
- deletedDocNames = diff.deletedDocNames;
+ resolveOfflineDeletions(diff.deletedDocNames);
if (diff.added > 0 || diff.updated > 0 || diff.deleted > 0) {
log.info(
{
@@ -745,17 +750,19 @@ export class DerivedDocumentIndex
);
}
} else {
+ resolveOfflineDeletions([]);
await this.backlinkIndex.rebuildFromDisk(branch);
}
await this.ingestGlobalSkillNodesLogOnly(branch, 'startup');
await this.saveBacklinksLogOnly('startup', branch);
- return { deletedDocNames, backlinkIndexDegraded: false };
+ return { backlinkIndexDegraded: false };
} catch (err) {
+ resolveOfflineDeletions([]);
log.error(
{ err, branch },
'[backlinks] startup init failed; index will populate incrementally via watcher',
);
- return { deletedDocNames: [], backlinkIndexDegraded: true };
+ return { backlinkIndexDegraded: true };
}
}
diff --git a/packages/server/src/directory-root.test.ts b/packages/server/src/directory-root.test.ts
index 44f480e61..5fabb13eb 100644
--- a/packages/server/src/directory-root.test.ts
+++ b/packages/server/src/directory-root.test.ts
@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSyn
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { resolveDirectoryRoot } from './directory-root.ts';
+import { resolveDirectoryRoot, resolveExistingNativeAncestor } from './directory-root.ts';
import { getLogger } from './logger.ts';
describe('resolveDirectoryRoot', () => {
@@ -37,6 +37,23 @@ describe('resolveDirectoryRoot', () => {
expect(diagnostics()).toEqual([]);
});
+ it('resolves the existing ancestor through an alias while retaining the absent tail separately', () => {
+ const target = join(scratch, 'target');
+ mkdirSync(target);
+ const alias = join(scratch, 'alias');
+ symlinkSync(target, alias, 'junction');
+ expect(resolveExistingNativeAncestor(join(alias, 'new', 'note.md'))).toEqual({
+ ancestor: realpathSync.native(target),
+ missingSegments: ['new', 'note.md'],
+ });
+ });
+
+ it('propagates cycles so membership and authoritative callers can apply their own error contracts', () => {
+ const loop = join(scratch, 'loop');
+ symlinkSync(loop, loop, 'dir');
+ expect(() => resolveExistingNativeAncestor(join(loop, 'note.md'))).toThrow();
+ });
+
it('keeps the given path and records which root stayed unresolved, with the errno, when native resolution fails', () => {
const file = join(scratch, 'not-a-directory');
writeFileSync(file, '');
diff --git a/packages/server/src/directory-root.ts b/packages/server/src/directory-root.ts
index ceac9897c..77c755c26 100644
--- a/packages/server/src/directory-root.ts
+++ b/packages/server/src/directory-root.ts
@@ -1,4 +1,5 @@
import { realpathSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
import { errnoCode } from './http/handler-utils.ts';
import { getLogger } from './logger.ts';
@@ -8,6 +9,26 @@ export function resolveNativePath(path: string): string {
return realpathSync.native(path);
}
+export function resolveExistingNativeAncestor(path: string): {
+ ancestor: string;
+ missingSegments: string[];
+} {
+ let cursor = resolve(path);
+ const missingSegments: string[] = [];
+ for (;;) {
+ try {
+ return { ancestor: resolveNativePath(cursor), missingSegments };
+ } catch (error) {
+ const code = errnoCode(error);
+ if (code !== 'ENOENT' && code !== 'ENOTDIR') throw error;
+ const parent = dirname(cursor);
+ if (parent === cursor) throw error;
+ missingSegments.unshift(basename(cursor));
+ cursor = parent;
+ }
+ }
+}
+
export function resolveDirectoryRoot(
directory: string,
site: {
diff --git a/packages/server/src/fs-safety.ts b/packages/server/src/fs-safety.ts
index 219c5ade9..4ebaa1dc5 100644
--- a/packages/server/src/fs-safety.ts
+++ b/packages/server/src/fs-safety.ts
@@ -5,6 +5,7 @@ import { normalizeFsPath } from './fs-traced.ts';
import { errnoCode } from './http/handler-utils.ts';
import { symlinkReachesPrivateState } from './incoming-symlink-guard.ts';
import type { PinoLogger } from './logger.ts';
+import { assertProjectContentScope } from './project-content-scope.ts';
export class SymlinkEscapeError extends Error {
constructor(message: string) {
@@ -92,6 +93,7 @@ export function assertNoSymlinkEscape(fullPath: string, resolvedContentDir: stri
) {
throw new PrivateStateSymlinkError();
}
+ assertProjectContentScope(fullPath, resolvedContentDir);
return;
} catch (err) {
const code = errnoCode(err);
diff --git a/packages/server/src/fs-traced.ts b/packages/server/src/fs-traced.ts
index 2fa7bac71..3ed07c858 100644
--- a/packages/server/src/fs-traced.ts
+++ b/packages/server/src/fs-traced.ts
@@ -1,6 +1,7 @@
import type { RmOptions, WriteFileOptions } from 'node:fs';
import {
appendFileSync,
+ chmodSync,
cpSync,
linkSync,
mkdirSync,
@@ -51,6 +52,11 @@ function buildAttrs(operation: string, path: string, extra?: Attributes): Attrib
return attrs;
}
+export const tracedChmodSync: typeof chmodSync = (path, mode) =>
+ withSpanSync('fs.chmodSync', { attributes: buildAttrs('chmodSync', String(path)) }, () =>
+ chmodSync(path, mode),
+ );
+
function byteLength(data: string | Uint8Array | ArrayBufferView): number {
if (typeof data === 'string') return Buffer.byteLength(data, 'utf-8');
if (data instanceof Uint8Array) return data.byteLength;
diff --git a/packages/server/src/http/api-pipeline.test.ts b/packages/server/src/http/api-pipeline.test.ts
index bda44c417..4caabaf22 100644
--- a/packages/server/src/http/api-pipeline.test.ts
+++ b/packages/server/src/http/api-pipeline.test.ts
@@ -37,6 +37,7 @@ async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<Native
resolve(pathname) {
if (
pathname === '/api/native-ping' ||
+ pathname === '/api/agent-write-md' ||
pathname === '/api/native-mutating' ||
pathname === '/api/native-upload'
) {
@@ -62,11 +63,13 @@ async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<Native
}
return null;
},
- isMutating: (pathname) => pathname === '/api/native-mutating',
+ isMutating: (pathname) =>
+ pathname === '/api/native-mutating' || pathname === '/api/agent-write-md',
};
const nativeApi: NativeApiHandle = {
paths: [
'/api/native-ping',
+ '/api/agent-write-md',
'/api/native-mutating',
'/api/native-upload',
'/api/native-throw',
@@ -289,6 +292,24 @@ describe('natively-mounted /api routes run the shared admission pipeline', () =>
}
});
+ test('previews reject project mutations while retaining document edits and reads', async () => {
+ const rig = await bootNativeRig({ ephemeral: true });
+ try {
+ const blocked = await rawRequest(rig.port, '/api/native-mutating', { method: 'POST' });
+ expect(blocked.status).toBe(403);
+ expect(parseProblem(blocked.body).title).toBe(
+ 'Single-file previews cannot manage project files.',
+ );
+ const edit = await rawRequest(rig.port, '/api/agent-write-md', { method: 'POST' });
+ expect(edit.status).toBe(200);
+ const read = await rawRequest(rig.port, '/api/native-ping');
+ expect(read.status).toBe(200);
+ expect(rig.dispatched).toEqual(['POST /api/agent-write-md', 'GET /api/native-ping']);
+ } finally {
+ await rig.close();
+ }
+ });
+
test('an owned URL with no handler gets the explicit RFC 9457 404', async () => {
const rig = await bootNativeRig();
try {
diff --git a/packages/server/src/http/api-pipeline.ts b/packages/server/src/http/api-pipeline.ts
index 8049212f0..8b9f71fd6 100644
--- a/packages/server/src/http/api-pipeline.ts
+++ b/packages/server/src/http/api-pipeline.ts
@@ -29,6 +29,24 @@ interface ApiRouteResolution {
dispatch?: ((req: IncomingMessage, res: ServerResponse) => Promise<void>) | undefined;
}
+const PREVIEW_DOCUMENT_MUTATIONS = new Set([
+ '/api/agent-write',
+ '/api/agent-write-md',
+ '/api/agent-patch',
+ '/api/agent-undo',
+ '/api/agent-write-batch',
+ '/api/comments',
+ '/api/comment',
+ '/api/client-logs',
+ '/api/frontmatter-patch',
+ '/api/save-version',
+ '/api/rollback',
+ '/api/lint/fix',
+ '/api/folder-config',
+ '/api/template',
+ '/api/agent-integrations/apply',
+]);
+
export interface ApiRouteTable {
resolve(pathname: string): ApiRouteResolution | null;
isMutating(pathname: string): boolean;
@@ -113,6 +131,7 @@ export interface ApiPipelineOptions {
policy?: IngressPolicy;
ephemeral?: boolean;
table: ApiRouteTable;
+ dispatchMutation?: (operation: () => Promise<void>, pathname: string) => Promise<void>;
}
export type ApiRequestPipeline = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
@@ -233,6 +252,23 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPi
}
if (table.isMutating(url)) {
+ if (
+ ephemeral &&
+ resolution.dispatch !== undefined &&
+ (method === 'POST' || method === 'PUT' || method === 'DELETE') &&
+ !PREVIEW_DOCUMENT_MUTATIONS.has(url)
+ ) {
+ errorResponse(
+ response,
+ 403,
+ 'urn:ok:error:single-file-mode',
+ 'Single-file previews cannot manage project files.',
+ {
+ handler: 'api-preview-content-scope',
+ },
+ );
+ return true;
+ }
const peerAddress = request.socket?.remoteAddress;
if (peerAddress !== undefined && !isPeerAdmitted(peerAddress, policy)) {
errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
@@ -291,7 +327,11 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPi
try {
const dispatch = resolution.dispatch;
if (dispatch !== undefined) {
- await dispatch(request, response);
+ if (table.isMutating(url) && opts.dispatchMutation !== undefined) {
+ await opts.dispatchMutation(() => dispatch(request, response), url);
+ } else {
+ await dispatch(request, response);
+ }
} else {
errorResponse(response, 404, 'urn:ok:error:not-found', 'API endpoint not found.', {
handler: 'api-dispatch',
diff --git a/packages/server/src/http/document-routes.ts b/packages/server/src/http/document-routes.ts
index 137f6a8de..2e336a539 100644
--- a/packages/server/src/http/document-routes.ts
+++ b/packages/server/src/http/document-routes.ts
@@ -175,6 +175,7 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
return;
}
+ const filePath = resolveContentEntryPath(contentDir, 'file', docName);
const existing = hocuspocus.documents.get(docName);
if (existing) {
successResponse(
@@ -191,7 +192,6 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
return;
}
- const filePath = resolveContentEntryPath(contentDir, 'file', docName);
if (!existsSync(filePath)) {
errorResponse(res, 404, 'urn:ok:error:doc-not-found', `Document not found: ${docName}.`, {
handler: 'document-read',
diff --git a/packages/server/src/http/error-response.ts b/packages/server/src/http/error-response.ts
index d0da1a17c..b9db0c336 100644
--- a/packages/server/src/http/error-response.ts
+++ b/packages/server/src/http/error-response.ts
@@ -9,7 +9,13 @@ import {
stripPathspecMagic,
} from '@inkeep/open-knowledge-core';
import type { Counter } from '@opentelemetry/api';
+import { PrivateStateSymlinkError, SymlinkEscapeError } from '../fs-safety.ts';
import { getLogger } from '../logger.ts';
+import { NestedProjectScopeError } from '../project-content-scope.ts';
+import {
+ ContentScopeAdmissionError,
+ ServerMutationShuttingDownError,
+} from '../server-content-policy.ts';
import { getMeter, setActiveSpanAttributes } from '../telemetry.ts';
import { getRequestId } from './request-id.ts';
@@ -68,6 +74,30 @@ export function errorResponse(
title: string,
options: ErrorResponseOptions = {},
): void {
+ if (
+ status === 500 &&
+ options.cause instanceof SymlinkEscapeError &&
+ !(options.cause instanceof PrivateStateSymlinkError)
+ ) {
+ status = 400;
+ type = 'urn:ok:error:path-escape';
+ title = 'Path resolves outside the content directory or contains a symlink cycle.';
+ options = { ...options, detail: undefined };
+ }
+ if (options.cause instanceof ServerMutationShuttingDownError) {
+ status = 503;
+ type = options.cause.problemType;
+ title = options.cause.message;
+ }
+ if (
+ options.cause instanceof NestedProjectScopeError ||
+ options.cause instanceof ContentScopeAdmissionError
+ ) {
+ status = 403;
+ type = 'urn:ok:error:path-escape';
+ title = 'Path is outside this server’s content scope.';
+ options = { ...options, detail: options.cause.message };
+ }
const instance = options.instance ?? `urn:uuid:${randomUUID()}`;
setActiveSpanAttributes({ 'ok.error.instance': instance });
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index d782c72e5..b58627ba2 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -508,6 +508,7 @@ export {
type StarterPackInfo,
} from './seed/index.ts';
export { serializeError } from './serialize-error.ts';
+export { ServerAuthorityCollisionError, ServerAuthorityRegistryError } from './server-authority.ts';
export { createServer, type ServerInstance, type ServerOptions } from './server-factory.ts';
export {
acquireServerLock,
diff --git a/packages/server/src/mermaid-persistence.test.ts b/packages/server/src/mermaid-persistence.test.ts
index 3b360b04c..6b699ee8b 100644
--- a/packages/server/src/mermaid-persistence.test.ts
+++ b/packages/server/src/mermaid-persistence.test.ts
@@ -1,15 +1,17 @@
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { LINEAGE_EPOCH_KEY } from '@inkeep/open-knowledge-core';
-import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import * as Y from 'yjs';
+import { tracedAtomicFs } from './fs-traced.ts';
import {
loadMermaidDoc,
MERMAID_SOURCE_ORIGIN,
type MermaidPersistenceCtx,
storeMermaidDoc,
} from './mermaid-persistence.ts';
+import { assertServerContentPath, snapshotServerContentScope } from './server-content-policy.ts';
let contentDir: string;
@@ -34,6 +36,33 @@ afterEach(() => {
});
describe('storeMermaidDoc', () => {
+ test('refuses a nested project created between staging and publishing verbatim content', async () => {
+ writeMmd(SRC);
+ const ctx = makeCtx();
+ const scope = snapshotServerContentScope(contentDir);
+ ctx.assertContentPath = (path) => assertServerContentPath(scope, path);
+ ctx.lkgCache.set(DOC, SRC);
+ const doc = new Y.Doc();
+ doc.getText('source').insert(0, 'graph TD; After-->Change;\n');
+ const write = tracedAtomicFs.writeFile;
+ const staged = vi.spyOn(tracedAtomicFs, 'writeFile').mockImplementation(async (...args) => {
+ await write(...args);
+ mkdirSync(join(contentDir, 'assets', '.ok'));
+ writeFileSync(join(contentDir, 'assets', '.ok', 'config.yml'), '');
+ });
+ try {
+ expect(await storeMermaidDoc(doc, DOC, 'agent', ctx)).toBe('write-failed');
+ expect(readFileSync(ABS(), 'utf8')).toBe(SRC);
+ expect(ctx.lkgCache.get(DOC)).toBe(SRC);
+ expect(
+ readdirSync(join(contentDir, 'assets')).filter((name) => name.endsWith('.tmp')),
+ ).toEqual([]);
+ } finally {
+ staged.mockRestore();
+ doc.destroy();
+ }
+ });
+
test('persists Y.Text("source") verbatim to the .mmd file', async () => {
const ctx = makeCtx();
const doc = new Y.Doc();
diff --git a/packages/server/src/mermaid-persistence.ts b/packages/server/src/mermaid-persistence.ts
index cca8c339f..8896d4e0c 100644
--- a/packages/server/src/mermaid-persistence.ts
+++ b/packages/server/src/mermaid-persistence.ts
@@ -11,9 +11,10 @@ import { atomicWriteFile } from '@inkeep/open-knowledge-core/server';
import type * as Y from 'yjs';
import { docNameToRelativePath } from './doc-extensions.ts';
import { assertNoSymlinkEscape } from './fs-safety.ts';
-import { tracedAtomicFs, tracedMkdir } from './fs-traced.ts';
+import { tracedMkdir } from './fs-traced.ts';
import { getLogger } from './logger.ts';
import { isWithinDir } from './path-utils.ts';
+import { contentScopedAtomicFs } from './server-content-policy.ts';
const log = getLogger('mermaid-persistence');
@@ -25,6 +26,7 @@ export const MERMAID_SOURCE_ORIGIN = {
export interface MermaidPersistenceCtx {
contentDir: string;
+ assertContentPath?: (path: string) => void;
lkgCache: Map<string, string>;
}
@@ -61,6 +63,7 @@ export function loadMermaidDoc(
if (ytext.length > 0) return;
const filePath = mermaidAbsPath(documentName, ctx.contentDir);
+ ctx.assertContentPath?.(filePath);
if (!existsSync(filePath)) return;
let raw: string;
@@ -91,6 +94,7 @@ export async function storeMermaidDoc(
const filePath = mermaidAbsPath(documentName, ctx.contentDir);
try {
assertNoSymlinkEscape(filePath, ctx.contentDir);
+ ctx.assertContentPath?.(filePath);
await tracedMkdir(resolve(filePath, '..'), { recursive: true });
if (existsSync(filePath)) {
@@ -113,7 +117,12 @@ export async function storeMermaidDoc(
}
}
- await atomicWriteFile(filePath, content, { fs: tracedAtomicFs });
+ await atomicWriteFile(filePath, content, {
+ fs: contentScopedAtomicFs((path) => {
+ assertNoSymlinkEscape(path, ctx.contentDir);
+ ctx.assertContentPath?.(path);
+ }),
+ });
ctx.lkgCache.set(documentName, content);
return 'persisted';
} catch (e) {
diff --git a/packages/server/src/nested-project-authority.test.ts b/packages/server/src/nested-project-authority.test.ts
new file mode 100644
index 000000000..d6e114c68
--- /dev/null
+++ b/packages/server/src/nested-project-authority.test.ts
@@ -0,0 +1,699 @@
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ symlinkSync,
+ unlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as decoding from 'lib0/decoding';
+import * as encoding from 'lib0/encoding';
+import { expect, test, vi } from 'vitest';
+import WebSocket from 'ws';
+import * as Y from 'yjs';
+import { testAuthorityRegistryPath } from '../../../test-support/server-authority-registry.test-helper.ts';
+import * as assetWalk from './asset-walk.ts';
+import { BacklinkIndex } from './backlink-index.ts';
+import { type BootedServer, bootServer } from './boot.ts';
+import { bootCompositionRig } from './composition-rig.test-helper.ts';
+import { ConfigSchema } from './config/schema.ts';
+import * as contentFilterModule from './content-filter.ts';
+import { DerivedDocumentIndex } from './derived-document-index.ts';
+import { getLogger } from './logger.ts';
+import { ServerLockCollisionError } from './server-lock.ts';
+
+function seedProject(projectDir: string): void {
+ mkdirSync(join(projectDir, '.ok'), { recursive: true });
+ writeFileSync(join(projectDir, '.ok', 'config.yml'), '');
+ writeFileSync(join(projectDir, '.ok', '.gitignore'), '');
+}
+
+test('missing cached documents wait for offline removal reconciliation, not existing documents', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-offline-removal-'));
+ seedProject(root);
+ writeFileSync(join(root, 'plain.md'), '# Plain\n');
+ const index = new BacklinkIndex({ projectDir: root, contentDir: root });
+ index.updateDocumentFromMarkdown('deleted', '# Cached\n');
+ await index.saveToDisk();
+ const entered = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ const originalLoad = BacklinkIndex.prototype.loadFromDisk;
+ vi.spyOn(BacklinkIndex.prototype, 'loadFromDisk').mockImplementation(async function (branch) {
+ entered.resolve();
+ await release.promise;
+ return originalLoad.call(this, branch);
+ });
+ let owner: BootedServer | undefined;
+ let missingAuth: Promise<string> | undefined;
+ try {
+ owner = await bootCompositionRig(root);
+ await Promise.race([
+ entered.promise,
+ owner.ready.then(() => {
+ throw new Error('Startup completed without reaching the paused cache load');
+ }),
+ ]);
+ const guard = owner.serverInstance.hocuspocus.configuration.extensions.find(
+ (entry) => '__kind' in entry && entry.__kind === 'removal-redirect-guard',
+ );
+ if (guard?.onAuthenticate === undefined) throw new Error('Removal guard absent');
+ const originalGuard = guard.onAuthenticate.bind(guard);
+ const removalEntered = Promise.withResolvers<void>();
+ vi.spyOn(guard, 'onAuthenticate').mockImplementation((payload) => {
+ const result = originalGuard(payload);
+ if (payload.documentName === 'deleted') removalEntered.resolve();
+ return result;
+ });
+ let settled = false;
+ missingAuth = authenticate(owner.port, 'deleted').then((result) => {
+ settled = true;
+ return result;
+ });
+ void missingAuth.catch(() => {});
+ await removalEntered.promise;
+ expect(await authenticate(owner.port, 'plain')).toBe('authenticated');
+ expect(await authenticate(owner.port, '__config__/project')).toBe('authenticated');
+ expect(settled).toBe(false);
+ release.resolve();
+ expect(await missingAuth).toContain('doc-deleted');
+ await owner.ready;
+ expect(existsSync(join(root, 'deleted.md'))).toBe(false);
+ expect(await authenticate(owner.port, 'new-page')).toBe('authenticated');
+ } finally {
+ release.resolve();
+ await missingAuth?.catch(() => {});
+ vi.restoreAllMocks();
+ await owner?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+}, 30_000);
+
+test('failed startup logs why missing-document admission is refused', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-removal-boot-failure-'));
+ const failure = new Error('Injected startup failure before offline reconciliation');
+ vi.spyOn(DerivedDocumentIndex.prototype, 'beginStartup').mockImplementationOnce(() => {
+ throw failure;
+ });
+ const errors = vi.spyOn(getLogger('server'), 'error');
+ let owner: BootedServer | undefined;
+ try {
+ owner = await bootCompositionRig(root);
+ await expect(owner.ready).rejects.toBe(failure);
+ expect(await authenticate(owner.port, 'missing')).toBe('permission-denied');
+ expect(errors).toHaveBeenCalledWith(
+ { err: failure, docName: 'missing' },
+ '[removal-guard] missing-document admission refused after startup failure',
+ );
+ } finally {
+ vi.restoreAllMocks();
+ await owner?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+}, 30_000);
+
+test.each(['rebuild', 'skill-ingestion'] as const)(
+ 'missing-document admission does not await startup %s',
+ async (phase) => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-removal-ready-'));
+ seedProject(root);
+ if (phase === 'skill-ingestion') {
+ const index = new BacklinkIndex({ projectDir: root, contentDir: root });
+ index.updateDocumentFromMarkdown('deleted', '# Cached\n');
+ await index.saveToDisk();
+ }
+ const entered = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ if (phase === 'rebuild') {
+ const original = BacklinkIndex.prototype.rebuildFromDisk;
+ vi.spyOn(BacklinkIndex.prototype, 'rebuildFromDisk').mockImplementation(
+ async function (branch) {
+ entered.resolve();
+ await release.promise;
+ return original.call(this, branch);
+ },
+ );
+ } else {
+ const original = BacklinkIndex.prototype.ingestGlobalSkillBundles;
+ vi.spyOn(BacklinkIndex.prototype, 'ingestGlobalSkillBundles').mockImplementation(
+ async function (...args) {
+ entered.resolve();
+ await release.promise;
+ return original.apply(this, args);
+ },
+ );
+ }
+ let owner: BootedServer | undefined;
+ try {
+ owner = await bootCompositionRig(root);
+ await Promise.race([
+ entered.promise,
+ owner.ready.then(() => {
+ throw new Error(`Startup completed without reaching paused ${phase}`);
+ }),
+ ]);
+ expect(await authenticate(owner.port, 'new-page')).toBe('authenticated');
+ if (phase === 'skill-ingestion')
+ expect(await authenticate(owner.port, 'deleted')).toContain('doc-deleted');
+ } finally {
+ release.resolve();
+ vi.restoreAllMocks();
+ await owner?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+ },
+ 30_000,
+);
+
+test('startup refreshes embeds loaded before asset indexes without blocking authentication', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-auth-ready-'));
+ writeFileSync(join(root, 'note.md'), '# Note\n\n![[photo.png]]\n');
+ writeFileSync(join(root, 'plain.md'), '# Plain\n');
+ writeFileSync(join(root, 'photo.png'), new Uint8Array([0x89, 0x50, 0x4e, 0x47]));
+ const seeded = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ const originalSeed = assetWalk.seedBasenameIndex;
+ const gate = vi.spyOn(assetWalk, 'seedBasenameIndex').mockImplementation(async (options) => {
+ seeded.resolve();
+ await release.promise;
+ return originalSeed(options);
+ });
+ let owner: BootedServer | undefined;
+ let auth: Promise<string> | undefined;
+ let loading:
+ | ReturnType<BootedServer['serverInstance']['hocuspocus']['openDirectConnection']>
+ | undefined;
+ try {
+ owner = await bootCompositionRig(root);
+ await Promise.race([
+ seeded.promise,
+ owner.ready.then(() => {
+ throw new Error('Startup completed without reaching paused asset seeding');
+ }),
+ ]);
+ for (const name of [
+ '__system__',
+ '__user__/config.yml',
+ '__config__/project',
+ '__local__/project',
+ '__config__/okignore',
+ ]) {
+ expect(await authenticate(owner.port, name)).toBe('authenticated');
+ }
+ const extension = owner.serverInstance.hocuspocus.configuration.extensions.find(
+ (entry) => '__kind' in entry && entry.__kind === 'principal-auth',
+ );
+ if (extension?.onAuthenticate === undefined) throw new Error('Authentication extension absent');
+ const originalAuth = extension.onAuthenticate.bind(extension);
+ const entered = Promise.withResolvers<void>();
+ let completed = false;
+ vi.spyOn(extension, 'onAuthenticate').mockImplementation((payload) => {
+ const pending = Promise.resolve(originalAuth(payload));
+ void pending.then(() => {
+ completed = true;
+ });
+ entered.resolve();
+ return pending;
+ });
+ auth = authenticate(owner.port, 'note');
+ await entered.promise;
+ expect(await auth).toBe('authenticated');
+ expect(completed).toBe(true);
+ expect(await authenticate(owner.port, 'new-before-assets')).toBe('authenticated');
+ const plain = await owner.serverInstance.hocuspocus.openDirectConnection('plain');
+ expect(plain.document.getText('source').toString()).toBe('# Plain\n');
+ await plain.disconnect();
+ loading = owner.serverInstance.hocuspocus.openDirectConnection('note');
+ const connection = await loading;
+ expect(connection.document.getText('source').toString()).toBe('# Note\n\n![[photo.png]]\n');
+ release.resolve();
+ await owner.ready;
+ const image = connection.document
+ .getXmlFragment('default')
+ .toArray()
+ .find((node) => node instanceof Y.XmlElement && node.nodeName === 'jsxComponent');
+ expect(image).toBeInstanceOf(Y.XmlElement);
+ if (!(image instanceof Y.XmlElement)) throw new Error('Embed absent');
+ expect(image.getAttribute('props')).toMatchObject({ src: '/photo.png' });
+ await connection.disconnect();
+ } finally {
+ release.resolve();
+ await auth;
+ await loading?.then((connection) => connection.disconnect()).catch(() => {});
+ vi.restoreAllMocks();
+ gate.mockRestore();
+ await owner?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+}, 30_000);
+
+test('a rejected alias startup preserves the live owner’s discovery lock', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-alias-authority-'));
+ const content = join(root, 'content');
+ const alias = join(root, 'project-alias');
+ mkdirSync(content);
+ symlinkSync(content, alias, 'junction');
+ let owner: BootedServer | undefined;
+ try {
+ owner = await bootCompositionRig(content);
+ await owner.ready;
+ const lock = join(owner.serverInstance.lockDir, 'server.lock');
+ await expect(
+ bootServer({
+ authorityRegistryPath: testAuthorityRegistryPath,
+ contentDir: content,
+ projectDir: alias,
+ config: ConfigSchema.parse({}),
+ port: 0,
+ quiet: true,
+ gitEnabled: false,
+ configHomedirOverride: join(root, 'home'),
+ }),
+ ).rejects.toBeInstanceOf(ServerLockCollisionError);
+ expect(existsSync(lock)).toBe(true);
+ expect(JSON.parse(readFileSync(lock, 'utf8')).port).toBe(owner.port);
+ } finally {
+ await owner?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+}, 60_000);
+
+test('a failed project lock releases the new content claim before retry', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-primary-authority-'));
+ const content = join(root, 'content');
+ const project = join(root, 'project');
+ mkdirSync(content);
+ seedProject(project);
+ const local = join(project, '.ok', 'local');
+ mkdirSync(local);
+ const lock = join(local, 'server.lock');
+ writeFileSync(
+ lock,
+ JSON.stringify({
+ pid: process.ppid,
+ hostname: 'fixture',
+ port: 9999,
+ startedAt: new Date().toISOString(),
+ worktreeRoot: project,
+ }),
+ );
+ let owner: BootedServer | undefined;
+ try {
+ await expect(
+ bootServer({
+ authorityRegistryPath: testAuthorityRegistryPath,
+ contentDir: content,
+ projectDir: project,
+ config: ConfigSchema.parse({}),
+ port: 0,
+ quiet: true,
+ gitEnabled: false,
+ configHomedirOverride: join(root, 'home'),
+ }),
+ ).rejects.toThrow(/already running at port 9999/);
+ unlinkSync(lock);
+ owner = await bootCompositionRig(content, {
+ projectDir: project,
+ configHomedirOverride: join(root, 'home'),
+ });
+ await owner.ready;
+ } finally {
+ await owner?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+}, 60_000);
+
+async function authenticate(port: number, documentName: string): Promise<string> {
+ const socket = new WebSocket(`ws://127.0.0.1:${port}/collab`);
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ return await new Promise<string>((resolve, reject) => {
+ timer = setTimeout(() => reject(new Error('Authentication timed out')), 10_000);
+ socket.on('error', reject);
+ socket.on('message', (message) => {
+ const decoder = decoding.createDecoder(new Uint8Array(message as Buffer));
+ decoding.readVarString(decoder);
+ if (decoding.readVarUint(decoder) !== 2) return;
+ const subtype = decoding.readVarUint(decoder);
+ if (subtype !== 1 && subtype !== 2) return;
+ clearTimeout(timer);
+ resolve(subtype === 1 ? decoding.readVarString(decoder) : 'authenticated');
+ });
+ socket.once('open', () => {
+ const encoder = encoding.createEncoder();
+ encoding.writeVarString(encoder, documentName);
+ encoding.writeVarUint(encoder, 2);
+ encoding.writeVarUint(encoder, 0);
+ encoding.writeVarString(encoder, '');
+ encoding.writeVarString(encoder, '4.0.0-rc.1');
+ socket.send(encoding.toUint8Array(encoder));
+ });
+ });
+ } finally {
+ clearTimeout(timer);
+ await new Promise<void>((resolve) => {
+ if (socket.readyState === WebSocket.CLOSED) return resolve();
+ socket.once('close', () => resolve());
+ socket.terminate();
+ });
+ }
+}
+
+test('nested servers cannot acquire authority over each other’s documents', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-nested-authority-'));
+ const nested = join(root, 'public', 'knowledge');
+ mkdirSync(join(root, '.ok'), { recursive: true });
+ mkdirSync(join(nested, '.ok'), { recursive: true });
+ writeFileSync(join(root, '.ok', 'config.yml'), '');
+ writeFileSync(join(nested, '.ok', 'config.yml'), '');
+ writeFileSync(join(root, 'parent.md'), '# Parent\n');
+ writeFileSync(join(nested, 'child.md'), '# Child\n');
+ mkdirSync(join(root, '.ok', 'local'));
+ writeFileSync(
+ join(root, '.ok', 'local', 'conflicts.json'),
+ JSON.stringify({
+ version: 2,
+ branch: 'main',
+ conflicts: [
+ {
+ kind: 'reconcile',
+ file: 'public/knowledge/child.md',
+ branch: 'main',
+ reason: 'stale-external-write',
+ detectedAt: new Date().toISOString(),
+ stages: { base: '# Child\n', ours: '# Parent conflict\n', theirs: '# Child\n' },
+ },
+ ],
+ }),
+ );
+ let parent: BootedServer | undefined;
+ let child: BootedServer | undefined;
+
+ async function request(port: number, path: string, body?: unknown) {
+ const response = await fetch(
+ `http://127.0.0.1:${port}${path}`,
+ body === undefined
+ ? {}
+ : {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify(body),
+ },
+ );
+ return { status: response.status, body: await response.json() };
+ }
+
+ try {
+ parent = await bootCompositionRig(root);
+ child = await bootCompositionRig(nested, { lockKind: 'mcp-spawned' });
+ await Promise.all([parent.ready, child.ready]);
+ const conflict = await request(parent.port, '/api/sync/resolve-conflict', {
+ file: 'public/knowledge/child.md',
+ strategy: 'content',
+ content: '# Wrong conflict owner\n',
+ agentId: 'wrong-owner',
+ });
+ expect(conflict.status).toBe(403);
+ expect(readFileSync(join(nested, 'child.md'), 'utf8')).toBe('# Child\n');
+
+ const parentRead = await request(parent.port, '/api/document?docName=public/knowledge/child');
+ expect(parentRead.status).toBe(403);
+ expect(parentRead.body.detail).toContain('Open that project instead');
+ const parentWrite = await request(parent.port, '/api/agent-write-md', {
+ docName: 'public/knowledge/child',
+ markdown: '# Wrong owner\n',
+ position: 'replace',
+ agentId: 'wrong-owner',
+ });
+ expect(parentWrite.status).toBe(403);
+ expect(readFileSync(join(nested, 'child.md'), 'utf8')).toBe('# Child\n');
+ expect(parent.serverInstance.hocuspocus.documents.has('public/knowledge/child')).toBe(false);
+ await expect(
+ parent.serverInstance.hocuspocus.openDirectConnection('public/knowledge/child'),
+ ).rejects.toThrow(/nested project/i);
+ await expect(authenticate(parent.port, 'public/knowledge/child')).resolves.toBe(
+ 'permission-denied',
+ );
+ await expect(authenticate(child.port, 'child')).resolves.toBe('authenticated');
+
+ const deleteParentFolder = await request(parent.port, '/api/delete-path', {
+ kind: 'folder',
+ path: 'public',
+ agentId: 'wrong-owner',
+ });
+ expect(deleteParentFolder.status).toBe(403);
+ const duplicateParentFolder = await request(parent.port, '/api/duplicate-path', {
+ kind: 'folder',
+ path: 'public',
+ agentId: 'wrong-owner',
+ });
+ expect(duplicateParentFolder.status).toBe(403);
+ const moveParentFolder = await request(parent.port, '/api/rename-path', {
+ kind: 'folder',
+ fromPath: 'public',
+ toPath: 'moved',
+ agentId: 'wrong-owner',
+ });
+ expect(moveParentFolder.status).toBe(403);
+ expect(readFileSync(join(nested, 'child.md'), 'utf8')).toBe('# Child\n');
+
+ const childWrite = await request(child.port, '/api/agent-write-md', {
+ docName: 'child',
+ markdown: '# Child\n\nUpdated by its own server.\n',
+ position: 'replace',
+ agentId: 'right-owner',
+ });
+ expect(childWrite.status).toBe(200);
+ const childRead = await request(child.port, '/api/document?docName=child');
+ expect(childRead.body.content).toBe('# Child\n\nUpdated by its own server.\n');
+ const ownParentWrite = await request(parent.port, '/api/agent-write-md', {
+ docName: 'parent',
+ markdown: '# Parent updated\n',
+ position: 'replace',
+ agentId: 'parent-owner',
+ });
+ expect(ownParentWrite.status).toBe(200);
+
+ unlinkSync(join(nested, '.ok', 'config.yml'));
+ const form = new FormData();
+ form.set('file', new Blob(['asset bytes'], { type: 'text/plain' }), 'note.txt');
+ form.set('parentDocName', 'public/knowledge/child');
+ form.set('placement', 'parent-dir');
+ const upload = await fetch(`http://127.0.0.1:${parent.port}/api/upload`, {
+ method: 'POST',
+ body: form,
+ });
+ expect(upload.status).toBe(403);
+ expect(
+ (await request(parent.port, '/api/document?docName=public/knowledge/child')).status,
+ ).toBe(403);
+ expect(
+ (
+ await request(parent.port, '/api/delete-path', {
+ kind: 'folder',
+ path: 'public',
+ agentId: 'wrong-owner',
+ })
+ ).status,
+ ).toBe(403);
+
+ const lateBody = {
+ docName: 'late/note',
+ markdown: '# Before\n',
+ position: 'replace',
+ agentId: 'cached-owner',
+ };
+ expect((await request(parent.port, '/api/agent-write-md', lateBody)).status).toBe(200);
+ mkdirSync(join(root, 'late', '.ok'));
+ writeFileSync(join(root, 'late', '.ok', 'config.yml'), '');
+ expect((await request(parent.port, '/api/document?docName=late/note')).status).toBe(403);
+ expect(
+ (await request(parent.port, '/api/agent-write-md', { ...lateBody, markdown: '# After\n' }))
+ .status,
+ ).toBe(403);
+ expect(readFileSync(join(root, 'late', 'note.md'), 'utf8')).toBe('# Before\n');
+ } finally {
+ await child?.destroy();
+ await parent?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+}, 60_000);
+
+test('synchronous construction failure releases its content claim before retry', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-failed-authority-'));
+ seedProject(root);
+ const fault = vi.spyOn(contentFilterModule, 'createContentFilter').mockImplementationOnce(() => {
+ throw new Error('Construction fault');
+ });
+ let replacement: BootedServer | undefined;
+ try {
+ await expect(
+ bootServer({
+ authorityRegistryPath: testAuthorityRegistryPath,
+ contentDir: root,
+ config: ConfigSchema.parse({}),
+ port: 0,
+ quiet: true,
+ gitEnabled: false,
+ configHomedirOverride: join(root, 'home'),
+ }),
+ ).rejects.toThrow('Construction fault');
+ fault.mockRestore();
+ replacement = await bootCompositionRig(root);
+ await replacement.ready;
+ } finally {
+ fault.mockRestore();
+ await replacement?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+}, 60_000);
+
+test.each(['parent-first', 'child-first'])(
+ 'custom content scopes refuse overlap (%s)',
+ async (order) => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-custom-authority-'));
+ const content = join(root, 'content');
+ const nested = join(content, 'nested');
+ mkdirSync(nested, { recursive: true });
+ writeFileSync(join(nested, 'note.md'), '# Untouched\n');
+ const firstContent = order === 'parent-first' ? content : nested;
+ const secondContent = order === 'parent-first' ? nested : content;
+ seedProject(join(root, 'first'));
+ seedProject(join(root, 'second'));
+ const boot = (dir: string, project: string) =>
+ bootServer({
+ authorityRegistryPath: testAuthorityRegistryPath,
+ contentDir: dir,
+ projectDir: join(root, project),
+ config: ConfigSchema.parse({}),
+ configHomedirOverride: join(root, 'home'),
+ host: '127.0.0.1',
+ port: 0,
+ quiet: true,
+ gitEnabled: false,
+ idleShutdownMs: null,
+ });
+ let first: BootedServer | undefined;
+ let replacement: BootedServer | undefined;
+ try {
+ first = await boot(firstContent, 'first');
+ await first.ready;
+ first.serverInstance.conflicts.raise({
+ kind: 'working-tree',
+ file: '.ok/config.yml',
+ theirsSha: 'unread-blob',
+ });
+ await expect(
+ first.serverInstance.conflicts.resolve('.ok/config.yml', 'mine'),
+ ).resolves.toBeUndefined();
+ await expect(boot(secondContent, 'second')).rejects.toThrow(
+ /content ownership is already held/i,
+ );
+ expect(readFileSync(join(nested, 'note.md'), 'utf8')).toBe('# Untouched\n');
+ await first.destroy();
+ first = undefined;
+ replacement = await boot(secondContent, 'second');
+ await replacement.ready;
+ } finally {
+ await replacement?.destroy();
+ await first?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+ },
+ 60_000,
+);
+
+test('single-file previews own only their file and block project takeover until retirement', async () => {
+ const fixture = mkdtempSync(join(tmpdir(), 'ok-preview-authority-'));
+ const root = join(fixture, 'content');
+ mkdirSync(root);
+ writeFileSync(join(root, 'one.md'), '# One\n');
+ writeFileSync(join(root, 'two.md'), '# Two\n');
+ seedProject(join(fixture, 'preview-one'));
+ seedProject(join(fixture, 'preview-two'));
+ let preview: BootedServer | undefined;
+ let sibling: BootedServer | undefined;
+ let project: BootedServer | undefined;
+ const write = async (server: BootedServer, docName: string) =>
+ fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ docName,
+ markdown: '# Updated\n',
+ position: 'replace',
+ agentId: 'preview-owner',
+ }),
+ });
+ try {
+ preview = await bootCompositionRig(root, {
+ projectDir: join(fixture, 'preview-one'),
+ ephemeral: true,
+ singleDocRelPath: 'one.md',
+ });
+ sibling = await bootCompositionRig(root, {
+ projectDir: join(fixture, 'preview-two'),
+ ephemeral: true,
+ singleDocRelPath: 'two.md',
+ });
+ await Promise.all([preview.ready, sibling.ready]);
+ for (const docName of [
+ '__user__/config.yml',
+ '__config__/project',
+ '__local__/project',
+ '__config__/okignore',
+ ]) {
+ await expect(authenticate(preview.port, docName)).resolves.toBe('authenticated');
+ }
+ expect((await write(preview, 'two')).status).toBe(403);
+ expect((await write(preview, 'one')).status).toBe(200);
+ for (const path of ['/api/lint/markdownlint-config', '/api/lint/frontmatter-schema']) {
+ const configWrite = await fetch(`http://127.0.0.1:${preview.port}${path}`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ ruleId: 'MD013', value: false }),
+ });
+ expect(configWrite.status).toBe(403);
+ expect((await configWrite.json()).type).toBe('urn:ok:error:single-file-mode');
+ }
+ const clientLogs = await fetch(`http://127.0.0.1:${preview.port}/api/client-logs`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ entries: [] }),
+ });
+ expect(clientLogs.status).toBe(200);
+ const comment = await fetch(`http://127.0.0.1:${preview.port}/api/comments`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: '{}',
+ });
+ expect(comment.status).toBe(400);
+ await expect(preview.serverInstance.hocuspocus.openDirectConnection('two')).rejects.toThrow(
+ /does not own/i,
+ );
+ await expect(authenticate(preview.port, 'two')).resolves.toBe('permission-denied');
+ const create = await fetch(`http://127.0.0.1:${preview.port}/api/create-page`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ path: 'new' }),
+ });
+ expect(create.status).toBe(403);
+ await expect(bootCompositionRig(root)).rejects.toThrow(/content ownership is already held/i);
+ expect(readFileSync(join(root, 'two.md'), 'utf8')).toBe('# Two\n');
+ await sibling.destroy();
+ sibling = undefined;
+ await preview.destroy();
+ preview = undefined;
+ project = await bootCompositionRig(root);
+ await project.ready;
+ expect(readFileSync(join(root, 'one.md'), 'utf8')).toBe('# Updated\n');
+ } finally {
+ await project?.destroy();
+ await sibling?.destroy();
+ await preview?.destroy();
+ rmSync(fixture, { recursive: true, force: true });
+ }
+}, 60_000);
diff --git a/packages/server/src/persistence.test.ts b/packages/server/src/persistence.test.ts
index 307c929c2..e7be16994 100644
--- a/packages/server/src/persistence.test.ts
+++ b/packages/server/src/persistence.test.ts
@@ -24,11 +24,13 @@ import {
} from './derived-document-index.ts';
import { DocumentDurabilityState } from './document-durability-state.ts';
import { contentHash, isSelfWrite, registerWrite } from './file-watcher';
+import * as tracedFs from './fs-traced.ts';
import {
captureDocSnapshotForPersistence,
createPersistenceExtension,
resolveWriterFromOrigin,
} from './persistence';
+import { ContentScopeAdmissionError } from './server-content-policy.ts';
import { FILE_SYSTEM_WRITER, GIT_UPSTREAM_WRITER, SERVICE_WRITER } from './shadow-repo';
describe('safeContentPath', () => {
@@ -183,7 +185,7 @@ describe('symlink-safe atomic write', () => {
symlinkSync(aPath, bPath);
await expect(simulateWrite('cycle-a', '# Content', contentDir)).rejects.toThrow(
- 'Symlink cycle detected',
+ /symlink cycle/i,
);
});
@@ -261,6 +263,38 @@ describe('persistence refuses links into private repository state', () => {
});
}
+ test('a staged store rechecks captured ownership before publishing', async () => {
+ const path = join(contentDir, 'note.md');
+ writeFileSync(path, '# Before\n');
+ let owned = true;
+ const persistence = createPersistenceExtension({
+ contentDir,
+ projectDir: contentDir,
+ gitEnabled: false,
+ assertContentPath: () => {
+ if (!owned) throw new ContentScopeAdmissionError();
+ },
+ });
+ const document = new Y.Doc();
+ document.getText('source').insert(0, '# Candidate\n');
+ const write = tracedFs.tracedWriteFile;
+ const staged = vi.spyOn(tracedFs, 'tracedWriteFile').mockImplementation(async (...args) => {
+ await write(...args);
+ owned = false;
+ });
+ try {
+ await expect(persistence.forceStore(document, 'note')).rejects.toThrow(
+ ContentScopeAdmissionError,
+ );
+ expect(staged).toHaveBeenCalledOnce();
+ expect(readFileSync(path, 'utf8')).toBe('# Before\n');
+ expect(readdirSync(contentDir).filter((name) => name.includes('.tmp'))).toEqual([]);
+ } finally {
+ staged.mockRestore();
+ document.destroy();
+ }
+ });
+
async function storeDocument(
persistence: ReturnType<typeof createPersistenceExtension>,
document: Y.Doc,
@@ -324,6 +358,34 @@ describe('persistence refuses links into private repository state', () => {
document.destroy();
});
+ test('a project marker arriving during staging prevents the atomic publish', async () => {
+ const docName = 'notes/race';
+ const before = '# Before\n';
+ const docPath = join(contentDir, 'notes', 'race.md');
+ writeFileSync(docPath, before);
+ const durabilityState = new DocumentDurabilityState();
+ durabilityState.setReconciledBase(docName, before);
+ const persistence = createPersistence(durabilityState);
+ const document = new Y.Doc();
+ composeAndWriteRawBody(document, '# After\n', 'test');
+ const write = tracedFs.tracedWriteFile;
+ const staging = vi.spyOn(tracedFs, 'tracedWriteFile').mockImplementation(async (...args) => {
+ await write(...args);
+ mkdirSync(join(contentDir, 'notes', '.ok'), { recursive: true });
+ writeFileSync(join(contentDir, 'notes', '.ok', 'config.yml'), '');
+ });
+ try {
+ await expect(storeDocument(persistence, document, docName)).rejects.toThrow(
+ /nested project/i,
+ );
+ expect(readFileSync(docPath, 'utf8')).toBe(before);
+ expect(readdirSync(join(contentDir, 'notes')).sort()).toEqual(['.ok', 'race.md']);
+ } finally {
+ staging.mockRestore();
+ document.destroy();
+ }
+ });
+
test('load leaves a Mermaid doc linked to the git config empty', async () => {
symlinkSync('../.git/config', join(contentDir, 'notes', 'cfg.mmd'));
const persistence = createPersistence();
diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.ts
index 68f33155f..81a4078af 100644
--- a/packages/server/src/persistence.ts
+++ b/packages/server/src/persistence.ts
@@ -123,6 +123,7 @@ import {
} from './metrics.ts';
import { toPosix } from './path-utils.ts';
import { classifyDuplication } from './persistence-tripwire.ts';
+import { assertProjectContentScope, NestedProjectScopeError } from './project-content-scope.ts';
import { backfillRenameLogCommitSha, getOrLoadRenameLogIndex } from './rename-log.ts';
import { getConvergedFragmentWitness, OBSERVER_SYNC_ORIGIN } from './server-observers.ts';
import type { ShadowRef, WriterIdentity } from './shadow-repo.ts';
@@ -267,6 +268,7 @@ export function classifyDeferredStoreError(err: unknown): DeferredStoreErrorClas
export interface PersistenceOptions {
contentDir: string;
+ assertContentPath?: (path: string) => void;
projectDir: string;
durabilityState?: DocumentDurabilityState;
conflicts?: Pick<ConflictAuthority, 'dissolveReconcile' | 'fileOf' | 'raise'>;
@@ -448,6 +450,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
const mermaidLkgCache = new Map<string, string>();
const mermaidPersistenceCtx: MermaidPersistenceCtx = {
+ assertContentPath: options?.assertContentPath,
contentDir,
lkgCache: mermaidLkgCache,
};
@@ -1589,7 +1592,18 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
inFlightFlushValue = normalizeBridge(markdown);
durabilityState.beginInFlightFlush(documentName, inFlightFlushValue);
- const requestedPath = safeContentPath(documentName, contentDir);
+ let requestedPath: string;
+ try {
+ requestedPath = safeContentPath(documentName, contentDir);
+ options?.assertContentPath?.(requestedPath);
+ } catch (error) {
+ if (error instanceof NestedProjectScopeError && markdown === currentBase) {
+ persistenceDeferCounts.delete(documentName);
+ return;
+ }
+ recordPathFault(documentName, error, agentTriggeredStore);
+ throw error;
+ }
if (
documentHadFileOnDisk(documentName, currentBase) &&
resolveStorePathPresence(
@@ -1802,6 +1816,8 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
return;
}
const outcome = durabilityState.tryPublishStore(storeAttempt, () => {
+ assertProjectContentScope(canonicalPath, contentDir);
+ options?.assertContentPath?.(canonicalPath);
tracedRenameSync(tmpPath, canonicalPath);
});
if (outcome !== 'published') {
@@ -2020,6 +2036,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
loadManagedArtifactDoc(document, documentName, managedArtifactCtx);
return;
}
+ options?.assertContentPath?.(safeContentPath(documentName, contentDir));
if (
isMermaidDoc(documentName) ||
isExcalidrawDoc(documentName) ||
@@ -2039,6 +2056,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
`[persistence] onLoadDocument called for ${documentName} (connections: ${document.getConnectionsCount?.() ?? '?'})`,
);
const filePath = safeContentPath(documentName, contentDir);
+ options?.assertContentPath?.(filePath);
if (!existsSync(filePath)) return;
docsWithFileObservedOnDisk.add(documentName);
@@ -2215,6 +2233,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
isExcalidrawDoc(documentName) ||
isEditableTextDoc(documentName)
) {
+ options?.assertContentPath?.(safeContentPath(documentName, contentDir));
await storeMermaidDoc(document, documentName, lastTransactionOrigin, mermaidPersistenceCtx);
return;
}
diff --git a/packages/server/src/project-content-scope.test.ts b/packages/server/src/project-content-scope.test.ts
new file mode 100644
index 000000000..69db05454
--- /dev/null
+++ b/packages/server/src/project-content-scope.test.ts
@@ -0,0 +1,32 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { expect, test } from 'vitest';
+import { assertProjectContentSubtree } from './project-content-scope.ts';
+
+test('recursive operations refuse a descendant project without relying on a file index', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-scope-subtree-'));
+ try {
+ mkdirSync(join(root, 'public', 'knowledge', '.ok'), { recursive: true });
+ writeFileSync(join(root, 'public', 'knowledge', '.ok', 'config.yml'), '');
+ expect(() => assertProjectContentSubtree(join(root, 'public'), root)).toThrow(
+ /nested project/i,
+ );
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+});
+
+test('recursive operations allow folder metadata and do not follow directory links', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-scope-subtree-'));
+ try {
+ mkdirSync(join(root, 'notes', '.ok'), { recursive: true });
+ writeFileSync(join(root, 'notes', '.ok', 'frontmatter.yml'), 'icon: note\n');
+ mkdirSync(join(root, 'child', '.ok'), { recursive: true });
+ writeFileSync(join(root, 'child', '.ok', 'config.yml'), '');
+ symlinkSync(join(root, 'child'), join(root, 'notes', 'alias'), 'junction');
+ expect(() => assertProjectContentSubtree(join(root, 'notes'), root)).not.toThrow();
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+});
diff --git a/packages/server/src/project-content-scope.ts b/packages/server/src/project-content-scope.ts
new file mode 100644
index 000000000..aad3f603a
--- /dev/null
+++ b/packages/server/src/project-content-scope.ts
@@ -0,0 +1,62 @@
+import { readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { resolveExistingNativeAncestor } from './directory-root.ts';
+import { isProjectRoot } from './fs/find-project-root.ts';
+import { isWithinDir } from './path-utils.ts';
+
+export class NestedProjectScopeError extends Error {
+ constructor(projectRoot: string) {
+ super(`This path belongs to the nested project at ${projectRoot}. Open that project instead.`);
+ this.name = 'NestedProjectScopeError';
+ }
+}
+
+function assertNoProjectBetween(path: string, root: string, canonicalRoot: string | null): void {
+ let cursor = path;
+ while (cursor !== root && isWithinDir(cursor, root)) {
+ try {
+ if (isProjectRoot(cursor) && existingRealPath(cursor) !== canonicalRoot) {
+ throw new NestedProjectScopeError(cursor);
+ }
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code;
+ if (code !== 'ELOOP' && code !== 'EACCES' && code !== 'EPERM') throw error;
+ }
+ cursor = dirname(cursor);
+ }
+}
+
+function existingRealPath(path: string): string | null {
+ try {
+ return resolveExistingNativeAncestor(path).ancestor;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'ELOOP') return null;
+ throw error;
+ }
+}
+
+export function assertProjectContentScope(fullPath: string, contentDir: string): void {
+ const path = resolve(fullPath);
+ const root = resolve(contentDir);
+ const canonicalRoot = existingRealPath(root);
+ assertNoProjectBetween(path, root, canonicalRoot);
+ const canonicalPath = existingRealPath(path);
+ if (canonicalPath !== null && canonicalRoot !== null) {
+ assertNoProjectBetween(canonicalPath, canonicalRoot, canonicalRoot);
+ }
+}
+
+export function assertProjectContentSubtree(folderPath: string, contentDir: string): void {
+ assertProjectContentScope(folderPath, contentDir);
+ const pending = [folderPath];
+ while (pending.length > 0) {
+ const directory = pending.pop();
+ if (directory === undefined) break;
+ for (const entry of readdirSync(directory, { withFileTypes: true })) {
+ if (!entry.isDirectory()) continue;
+ const child = join(directory, entry.name);
+ if (isProjectRoot(child)) throw new NestedProjectScopeError(child);
+ pending.push(child);
+ }
+ }
+}
diff --git a/packages/server/src/server-authority-lease.test.ts b/packages/server/src/server-authority-lease.test.ts
new file mode 100644
index 000000000..27d56d474
--- /dev/null
+++ b/packages/server/src/server-authority-lease.test.ts
@@ -0,0 +1,194 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { SERVER_AUTHORITY_LEASES_DIRNAME } from '@inkeep/open-knowledge-core';
+import { afterEach, expect, test, vi } from 'vitest';
+import * as fsTraced from './fs-traced.ts';
+import {
+ acquireServerAuthorityLease,
+ collectServerAuthorityLeaseOrphansUnderRegistryTransaction,
+ isServerAuthorityLeaseReleased,
+ removeReleasedServerAuthorityLease,
+ ServerAuthorityLeaseVerificationError,
+} from './server-authority-lease.ts';
+
+const directories: string[] = [];
+afterEach(() => {
+ vi.restoreAllMocks();
+ for (const path of directories.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+function fixture() {
+ const directory = mkdtempSync(join(tmpdir(), 'ok-authority-lease-'));
+ directories.push(directory);
+ const ownerToken = randomUUID();
+ const registryPath = join(directory, 'registry.sqlite');
+ const path = join(directory, SERVER_AUTHORITY_LEASES_DIRNAME, `${ownerToken}.sqlite`);
+ return { directory, ownerToken, registryPath, path };
+}
+
+test('an in-process owned lease is retained and release removes only its own file idempotently', () => {
+ const { ownerToken, registryPath, path } = fixture();
+ const release = acquireServerAuthorityLease(registryPath, ownerToken);
+ try {
+ expect(isServerAuthorityLeaseReleased(registryPath, ownerToken)).toBe(false);
+ expect(existsSync(path)).toBe(true);
+ } finally {
+ release();
+ }
+ release();
+ expect(existsSync(path)).toBe(false);
+});
+
+test.each([true, false])(
+ 'a released lease proves only its persisted owner token (matches=%s)',
+ (matches) => {
+ const { ownerToken, registryPath, path } = fixture();
+ mkdirSync(join(path, '..'), { recursive: true });
+ const database = new DatabaseSync(path);
+ database.exec('CREATE TABLE lease (owner_token TEXT PRIMARY KEY) STRICT');
+ database.prepare('INSERT INTO lease VALUES (?)').run(matches ? ownerToken : randomUUID());
+ database.close();
+ if (matches) {
+ expect(isServerAuthorityLeaseReleased(registryPath, ownerToken)).toBe(true);
+ removeReleasedServerAuthorityLease(registryPath, ownerToken);
+ expect(existsSync(path)).toBe(false);
+ } else {
+ expect(() => isServerAuthorityLeaseReleased(registryPath, ownerToken)).toThrow(
+ ServerAuthorityLeaseVerificationError,
+ );
+ expect(existsSync(path)).toBe(true);
+ }
+ },
+);
+
+test('a missing lease is not created or treated as proof of retirement', () => {
+ const { ownerToken, registryPath, path } = fixture();
+ expect(() => isServerAuthorityLeaseReleased(registryPath, ownerToken)).toThrow(
+ ServerAuthorityLeaseVerificationError,
+ );
+ expect(existsSync(path)).toBe(false);
+});
+
+test('WAL read concurrency cannot be mistaken for a released ownership lease', () => {
+ const { ownerToken, registryPath, path } = fixture();
+ mkdirSync(join(path, '..'), { recursive: true });
+ const database = new DatabaseSync(path);
+ try {
+ database.exec(
+ 'PRAGMA journal_mode=WAL; CREATE TABLE lease (owner_token TEXT PRIMARY KEY) STRICT',
+ );
+ database.prepare('INSERT INTO lease VALUES (?)').run(ownerToken);
+ database.exec('BEGIN EXCLUSIVE');
+ try {
+ isServerAuthorityLeaseReleased(registryPath, ownerToken);
+ expect.fail('WAL mode must not prove lease retirement');
+ } catch (error) {
+ expect(error).toBeInstanceOf(ServerAuthorityLeaseVerificationError);
+ expect((error as Error).cause).toBeInstanceOf(SyntaxError);
+ expect(((error as Error).cause as Error).message).toContain('DELETE-mode file locking');
+ }
+ } finally {
+ database.close();
+ }
+});
+
+test.each(['complete', 'empty-file', 'empty-table'] as const)(
+ 'an unreferenced %s lease is reclaimed only under a serialized registry transaction',
+ (state) => {
+ const { registryPath, path, ownerToken } = fixture();
+ mkdirSync(join(path, '..'), { recursive: true });
+ writeFileSync(path, '');
+ if (state !== 'empty-file') {
+ const lease = new DatabaseSync(path);
+ lease.exec('CREATE TABLE lease (owner_token TEXT PRIMARY KEY) STRICT');
+ if (state === 'complete') lease.prepare('INSERT INTO lease VALUES (?)').run(ownerToken);
+ lease.close();
+ }
+ const registry = new DatabaseSync(registryPath);
+ registry.exec('CREATE TABLE server_authority (owner_token TEXT PRIMARY KEY) STRICT');
+ try {
+ expect(() =>
+ collectServerAuthorityLeaseOrphansUnderRegistryTransaction(
+ registryPath,
+ registry,
+ new Set(),
+ ),
+ ).toThrow('held registry transaction');
+ expect(existsSync(path)).toBe(true);
+ registry.exec('BEGIN IMMEDIATE');
+ collectServerAuthorityLeaseOrphansUnderRegistryTransaction(registryPath, registry, new Set());
+ registry.exec('COMMIT');
+ expect(existsSync(path)).toBe(false);
+ } finally {
+ registry.close();
+ }
+ },
+);
+
+test('orphan collection preserves an unregistered live lease and every referenced lease', () => {
+ const { registryPath, path, ownerToken } = fixture();
+ const release = acquireServerAuthorityLease(registryPath, ownerToken);
+ const registry = new DatabaseSync(registryPath);
+ try {
+ registry.exec(
+ 'CREATE TABLE server_authority (owner_token TEXT PRIMARY KEY) STRICT; BEGIN IMMEDIATE',
+ );
+ collectServerAuthorityLeaseOrphansUnderRegistryTransaction(registryPath, registry, new Set());
+ expect(existsSync(path)).toBe(true);
+ registry.prepare('INSERT INTO server_authority VALUES (?)').run(ownerToken);
+ collectServerAuthorityLeaseOrphansUnderRegistryTransaction(
+ registryPath,
+ registry,
+ new Set([ownerToken]),
+ );
+ expect(existsSync(path)).toBe(true);
+ registry.exec('COMMIT');
+ } finally {
+ registry.close();
+ release();
+ }
+});
+
+test('an unlink failure cannot undo a completed lease release and its orphan can be reclaimed', () => {
+ const { registryPath, path, ownerToken } = fixture();
+ const release = acquireServerAuthorityLease(registryPath, ownerToken);
+ const unlink = vi.spyOn(fsTraced, 'tracedUnlinkSync').mockImplementationOnce(() => {
+ throw Object.assign(new Error('Cleanup busy'), { code: 'EBUSY' });
+ });
+ expect(() => release()).not.toThrow();
+ expect(isServerAuthorityLeaseReleased(registryPath, ownerToken)).toBe(true);
+ release();
+ expect(unlink).toHaveBeenCalledTimes(1);
+ unlink.mockRestore();
+ const registry = new DatabaseSync(registryPath);
+ try {
+ registry.exec(
+ 'CREATE TABLE server_authority (owner_token TEXT PRIMARY KEY) STRICT; BEGIN IMMEDIATE',
+ );
+ collectServerAuthorityLeaseOrphansUnderRegistryTransaction(registryPath, registry, new Set());
+ registry.exec('COMMIT');
+ expect(existsSync(path)).toBe(false);
+ } finally {
+ registry.close();
+ }
+});
+
+test('failed lease construction preserves its primary error despite cleanup failures', () => {
+ const { registryPath, ownerToken } = fixture();
+ const primary = new Error('Primary SQLite fault');
+ const close = DatabaseSync.prototype.close;
+ vi.spyOn(DatabaseSync.prototype, 'exec').mockImplementationOnce(() => {
+ throw primary;
+ });
+ vi.spyOn(DatabaseSync.prototype, 'close').mockImplementationOnce(function () {
+ close.call(this);
+ throw new Error('Secondary close fault');
+ });
+ vi.spyOn(fsTraced, 'tracedUnlinkSync').mockImplementationOnce(() => {
+ throw Object.assign(new Error('Secondary unlink fault'), { code: 'EBUSY' });
+ });
+ expect(() => acquireServerAuthorityLease(registryPath, ownerToken)).toThrow(primary);
+});
diff --git a/packages/server/src/server-authority-lease.ts b/packages/server/src/server-authority-lease.ts
new file mode 100644
index 000000000..715bab74b
--- /dev/null
+++ b/packages/server/src/server-authority-lease.ts
@@ -0,0 +1,172 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { SERVER_AUTHORITY_LEASES_DIRNAME } from '@inkeep/open-knowledge-core';
+import { z } from 'zod';
+import { tracedMkdirSync, tracedUnlinkSync, tracedWriteFileSync } from './fs-traced.ts';
+import { getLogger } from './logger.ts';
+
+export const SERVER_AUTHORITY_LEASE_PROTOCOL = 'sqlite-lifetime-lease:v1';
+const heldLeases = new Set<string>();
+
+export class ServerAuthorityLeaseVerificationError extends Error {
+ readonly leasePath: string;
+ readonly kind: 'missing' | 'invalid-data' | 'unavailable';
+ constructor(leasePath: string, cause: unknown) {
+ super(`Content ownership lease could not be verified at ${leasePath}`, { cause });
+ this.name = 'ServerAuthorityLeaseVerificationError';
+ this.leasePath = leasePath;
+ const value = cause as { code?: string; errcode?: number };
+ const sqliteCode = typeof value?.errcode === 'number' ? value.errcode & 0xff : undefined;
+ this.kind =
+ cause instanceof SyntaxError || sqliteCode === 1 || sqliteCode === 11 || sqliteCode === 26
+ ? 'invalid-data'
+ : value?.code === 'ENOENT'
+ ? 'missing'
+ : 'unavailable';
+ if (sqliteCode === 14) {
+ try {
+ lstatSync(leasePath);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') this.kind = 'missing';
+ }
+ }
+ }
+}
+
+function leasePath(registryPath: string, ownerToken: string): string {
+ return resolve(
+ dirname(registryPath),
+ SERVER_AUTHORITY_LEASES_DIRNAME,
+ `${z.uuid().parse(ownerToken)}.sqlite`,
+ );
+}
+
+function cleanupLeaseFile(path: string): void {
+ try {
+ tracedUnlinkSync(path);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+ getLogger('server-authority').warn(
+ { err: error, leasePath: path },
+ 'Retired ownership lease file cleanup failed',
+ );
+ }
+}
+
+export function acquireServerAuthorityLease(registryPath: string, ownerToken: string): () => void {
+ const path = leasePath(registryPath, ownerToken);
+ tracedMkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+ tracedWriteFileSync(path, '', { flag: 'wx', mode: 0o600 });
+ let database: DatabaseSync | undefined;
+ try {
+ database = new DatabaseSync(path, { timeout: 0 });
+ database.exec('PRAGMA journal_mode=DELETE');
+ database.exec('CREATE TABLE lease (owner_token TEXT PRIMARY KEY) STRICT');
+ database.prepare('INSERT INTO lease VALUES (?)').run(ownerToken);
+ database.exec('BEGIN EXCLUSIVE');
+ } catch (error) {
+ try {
+ database?.close();
+ } catch (cleanupError) {
+ getLogger('server-authority').warn(
+ { err: cleanupError, leasePath: path },
+ 'Failed ownership lease close failed',
+ );
+ }
+ cleanupLeaseFile(path);
+ throw error;
+ }
+ heldLeases.add(path);
+ let released = false;
+ return () => {
+ if (released) return;
+ database.close();
+ heldLeases.delete(path);
+ released = true;
+ cleanupLeaseFile(path);
+ };
+}
+
+export function isServerAuthorityLeaseReleased(registryPath: string, ownerToken: string): boolean {
+ const path = leasePath(registryPath, ownerToken);
+ return probeReleasedLease(path, ownerToken, false);
+}
+
+function probeReleasedLease(
+ path: string,
+ ownerToken: string,
+ allowUninitialized: boolean,
+): boolean {
+ if (heldLeases.has(path)) return false;
+ let database: DatabaseSync | undefined;
+ try {
+ database = new DatabaseSync(path, { readOnly: true, timeout: 0 });
+ try {
+ database.exec('BEGIN EXCLUSIVE');
+ } catch (error) {
+ const code = (error as { errcode?: number }).errcode;
+ if (typeof code === 'number' && ((code & 0xff) === 5 || (code & 0xff) === 6)) return false;
+ throw error;
+ }
+ if (database.prepare('PRAGMA journal_mode').get()?.journal_mode !== 'delete')
+ throw new SyntaxError('Content ownership lease must use SQLite DELETE-mode file locking');
+ if (
+ allowUninitialized &&
+ database.prepare('SELECT count(*) AS count FROM sqlite_schema').get()?.count === 0
+ )
+ return true;
+ const persistedToken = database.prepare('SELECT owner_token FROM lease').get()?.owner_token;
+ if (allowUninitialized && persistedToken === undefined) return true;
+ if (persistedToken !== ownerToken)
+ throw new SyntaxError('Content ownership lease token does not match its registry row');
+ return true;
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code;
+ if (
+ error instanceof SyntaxError ||
+ code === 'ERR_SQLITE_ERROR' ||
+ ['EACCES', 'EPERM', 'ENOENT', 'EIO', 'EBUSY'].includes(code ?? '')
+ )
+ throw new ServerAuthorityLeaseVerificationError(path, error);
+ throw error;
+ } finally {
+ database?.close();
+ }
+}
+
+export function removeReleasedServerAuthorityLease(registryPath: string, ownerToken: string): void {
+ cleanupLeaseFile(leasePath(registryPath, ownerToken));
+}
+
+export function collectServerAuthorityLeaseOrphansUnderRegistryTransaction(
+ registryPath: string,
+ registry: DatabaseSync,
+ referenced: ReadonlySet<string>,
+): void {
+ if (!registry.isTransaction)
+ throw new Error('Ownership lease collection requires a held registry transaction');
+ const directory = resolve(dirname(registryPath), SERVER_AUTHORITY_LEASES_DIRNAME);
+ try {
+ for (const entry of readdirSync(directory, { withFileTypes: true })) {
+ if (!entry.isFile() || !entry.name.endsWith('.sqlite')) continue;
+ const parsed = z.uuid().safeParse(entry.name.slice(0, -7));
+ if (!parsed.success || referenced.has(parsed.data)) continue;
+ const path = resolve(directory, entry.name);
+ try {
+ if (probeReleasedLease(path, parsed.data, true)) cleanupLeaseFile(path);
+ } catch (error) {
+ getLogger('server-authority').warn(
+ { err: error, leasePath: path },
+ 'Unreferenced ownership lease could not be verified',
+ );
+ }
+ }
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+ getLogger('server-authority').warn(
+ { err: error, leasePath: directory },
+ 'Ownership lease directory cleanup unavailable',
+ );
+ }
+}
diff --git a/packages/server/src/server-authority-retirement.test.ts b/packages/server/src/server-authority-retirement.test.ts
new file mode 100644
index 000000000..b86f897b0
--- /dev/null
+++ b/packages/server/src/server-authority-retirement.test.ts
@@ -0,0 +1,283 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { expect, test, vi } from 'vitest';
+import { applyAgentMarkdownWrite } from './agent-sessions.ts';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig } from './composition-rig.test-helper.ts';
+import { tracedAtomicFs } from './fs-traced.ts';
+
+test.each(['stalled', 'completes'] as const)(
+ 'a %s HTTP mutation respects the pre-flush shutdown budget',
+ async (outcome) => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-stalled-mutation-'));
+ const replacementProject = mkdtempSync(join(tmpdir(), 'ok-stalled-replacement-'));
+ mkdirSync(join(replacementProject, '.ok'));
+ writeFileSync(join(replacementProject, '.ok', 'config.yml'), '');
+ writeFileSync(join(replacementProject, '.ok', '.gitignore'), '*\n');
+ writeFileSync(join(root, 'note.md'), '# Before\n');
+ writeFileSync(join(root, 'live.md'), '# Live\n');
+ const staged = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ let owner: BootedServer | undefined;
+ let pending: Promise<unknown> | undefined;
+ try {
+ owner = await bootCompositionRig(root, {
+ destroyTimeoutMs: 500,
+ debounce: 20_000,
+ maxDebounce: 20_000,
+ });
+ await owner.ready;
+ const live = await owner.serverInstance.sessionManager.getSession('live', 'stalled-drain');
+ live.dc.document.transact(() => {
+ applyAgentMarkdownWrite(live.dc.document, '\nFLUSHED-WHILE-MUTATION-STALLED\n', 'append');
+ }, live.origin);
+ const store = owner.serverInstance.hocuspocus.storeDocumentHooks(live.dc.document, {
+ clientsCount: 0,
+ document: live.dc.document,
+ documentName: 'live',
+ lastContext: {},
+ lastTransactionOrigin: live.origin,
+ instance: owner.serverInstance.hocuspocus,
+ });
+ expect(readFileSync(join(root, 'live.md'), 'utf8')).toBe('# Live\n');
+ const manager = owner.serverInstance.sessionManager;
+ const getSession = manager.getSession.bind(manager);
+ vi.spyOn(manager, 'getSession').mockImplementation(async (...args) => {
+ const session = await getSession(...args);
+ if (args[0] === 'note') {
+ staged.resolve();
+ await release.promise;
+ }
+ return session;
+ });
+ pending = fetch(`http://127.0.0.1:${owner.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ docName: 'note',
+ position: 'replace',
+ markdown: '# Delayed\n',
+ agentId: 'stalled',
+ }),
+ }).then(
+ (response) => response.text(),
+ (error) => error,
+ );
+ await staged.promise;
+ const retiring = owner.serverInstance.destroy();
+ if (outcome === 'completes') {
+ const probe = await fetch(`http://127.0.0.1:${owner.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ docName: 'probe', position: 'replace', markdown: '# Probe\n' }),
+ });
+ expect(probe.status).toBe(503);
+ release.resolve();
+ await pending;
+ }
+ await retiring;
+ await store;
+ expect(readFileSync(join(root, 'live.md'), 'utf8')).toContain(
+ 'FLUSHED-WHILE-MUTATION-STALLED',
+ );
+ if (outcome === 'stalled') {
+ await expect(bootCompositionRig(root, { projectDir: replacementProject })).rejects.toThrow(
+ /content ownership/,
+ );
+ expect(readFileSync(join(root, 'note.md'), 'utf8')).toBe('# Before\n');
+ } else {
+ const replacement = await bootCompositionRig(root, { projectDir: replacementProject });
+ try {
+ await replacement.ready;
+ expect(readFileSync(join(root, 'note.md'), 'utf8')).toBe('# Delayed\n');
+ } finally {
+ await replacement.destroy();
+ }
+ }
+ release.resolve();
+ await pending;
+ } finally {
+ release.resolve();
+ vi.restoreAllMocks();
+ await pending;
+ await owner?.destroy().catch(() => {});
+ rmSync(root, { recursive: true, force: true });
+ rmSync(replacementProject, { recursive: true, force: true });
+ }
+ },
+ 30_000,
+);
+
+test('a pending document load retains ownership until it settles and retires', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-loading-authority-'));
+ const contentDir = join(root, 'content');
+ const replacementProject = join(root, 'replacement');
+ mkdirSync(contentDir);
+ mkdirSync(join(replacementProject, '.ok'), { recursive: true });
+ writeFileSync(join(replacementProject, '.ok', 'config.yml'), '');
+ writeFileSync(join(replacementProject, '.ok', '.gitignore'), '');
+ writeFileSync(join(contentDir, 'note.md'), '# Before\n');
+ const entered = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ let owner: BootedServer | undefined;
+ let loading:
+ | ReturnType<BootedServer['serverInstance']['hocuspocus']['openDirectConnection']>
+ | undefined;
+ let retiring: Promise<void> | undefined;
+ let replacement: BootedServer | undefined;
+ try {
+ owner = await bootCompositionRig(contentDir);
+ await owner.ready;
+ owner.serverInstance.hocuspocus.configuration.extensions.unshift({
+ async onLoadDocument({ documentName }) {
+ if (documentName !== 'note') return;
+ entered.resolve();
+ await release.promise;
+ },
+ });
+ loading = owner.serverInstance.hocuspocus.openDirectConnection('note');
+ await entered.promise;
+ retiring = owner.serverInstance.destroy();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ const outcome = await Promise.race([
+ retiring.then(() => 'retired'),
+ new Promise<string>((resolve) => {
+ timer = setTimeout(() => resolve('loading'), 1_000);
+ }),
+ ]);
+ expect(outcome).toBe('loading');
+ } finally {
+ clearTimeout(timer);
+ }
+ await expect(
+ bootCompositionRig(contentDir, { projectDir: replacementProject }),
+ ).rejects.toThrow(/content ownership is already held/i);
+ release.resolve();
+ const connection = await loading;
+ await connection.disconnect();
+ await retiring;
+ await owner.destroy();
+ owner = undefined;
+ replacement = await bootCompositionRig(contentDir, { projectDir: replacementProject });
+ await replacement.ready;
+ } finally {
+ release.resolve();
+ await loading?.then((connection) => connection.disconnect()).catch(() => {});
+ await retiring;
+ await replacement?.destroy();
+ await owner?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+}, 60_000);
+
+test.each(['internal', 'http'] as const)(
+ 'retirement protects a replacement from a staged %s conflict write',
+ async (entry) => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-retirement-authority-'));
+ const contentDir = join(root, 'content');
+ const replacementProject = join(root, 'replacement');
+ for (const project of [root, replacementProject]) {
+ mkdirSync(join(project, '.ok'), { recursive: true });
+ writeFileSync(join(project, '.ok', 'config.yml'), '');
+ writeFileSync(join(project, '.ok', '.gitignore'), '');
+ }
+ mkdirSync(contentDir);
+ writeFileSync(join(contentDir, 'note.md'), '# Before\n');
+ const staged = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ const delayed = '# Delayed old writer\n';
+ const write = tracedAtomicFs.writeFile;
+ const staging = vi.spyOn(tracedAtomicFs, 'writeFile').mockImplementation(async (...args) => {
+ await write(...args);
+ if (args[1] === delayed) {
+ staged.resolve();
+ await release.promise;
+ }
+ });
+ let old: BootedServer | undefined;
+ let replacement: BootedServer | undefined;
+ let pending: Promise<{ ok: true } | { ok: false; error: unknown }> | undefined;
+ let retiring: Promise<void> | undefined;
+ try {
+ old = await bootCompositionRig(contentDir, { projectDir: root });
+ await old.ready;
+ old.serverInstance.conflicts.raise({
+ kind: 'reconcile',
+ file: 'content/note.md',
+ reason: 'stale-external-write',
+ stages: { base: '# Before\n', ours: '# Before\n', theirs: '# Before\n' },
+ });
+ const operation =
+ entry === 'internal'
+ ? old.serverInstance.conflicts.resolve('content/note.md', 'content', delayed)
+ : fetch(`http://127.0.0.1:${old.port}/api/sync/resolve-conflict`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ file: 'content/note.md',
+ strategy: 'content',
+ content: delayed,
+ agentId: 'old',
+ }),
+ }).then(async (response) => {
+ expect(response.status).toBe(200);
+ await response.text();
+ });
+ pending = operation.then(
+ () => ({ ok: true as const }),
+ (error: unknown) => ({ ok: false as const, error }),
+ );
+ await Promise.race([
+ staged.promise,
+ pending.then((result) => {
+ throw new Error(`Write did not stage: ${JSON.stringify(result)}`);
+ }),
+ ]);
+ staging.mockRestore();
+ if (entry === 'http') {
+ retiring = old.serverInstance.destroy();
+ await expect(
+ bootCompositionRig(contentDir, { projectDir: replacementProject }),
+ ).rejects.toThrow(/content ownership is already held/i);
+ release.resolve();
+ expect(await pending).toEqual({ ok: true });
+ await retiring;
+ }
+ await old.destroy();
+ old = undefined;
+ replacement = await bootCompositionRig(contentDir, { projectDir: replacementProject });
+ await replacement.ready;
+ const updated = await fetch(`http://127.0.0.1:${replacement.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ docName: 'note',
+ markdown: '# New owner\n',
+ position: 'replace',
+ agentId: 'new',
+ }),
+ });
+ expect(updated.status).toBe(200);
+ await updated.text();
+ release.resolve();
+ if (entry === 'internal') {
+ const result = await pending;
+ expect(result.ok).toBe(false);
+ if (result.ok) throw new Error('Retired writer unexpectedly published');
+ expect(result.error).toMatchObject({ name: 'ServerMutationShuttingDownError' });
+ }
+ expect(readFileSync(join(contentDir, 'note.md'), 'utf8')).toBe('# New owner\n');
+ } finally {
+ staging.mockRestore();
+ release.resolve();
+ await pending;
+ await retiring;
+ await replacement?.destroy();
+ await old?.destroy();
+ rmSync(root, { recursive: true, force: true });
+ }
+ },
+ 60_000,
+);
diff --git a/packages/server/src/server-authority.test.ts b/packages/server/src/server-authority.test.ts
new file mode 100644
index 000000000..09d8fca12
--- /dev/null
+++ b/packages/server/src/server-authority.test.ts
@@ -0,0 +1,649 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { z } from 'zod';
+import { withHiddenWindowsConsole } from './child-process-windows-hide.ts';
+import {
+ acquireServerAuthority,
+ type ContentScope,
+ classifyServerAuthorityRegistryError,
+ contentScopeContainsPath,
+ contentScopesOverlap,
+ ServerAuthorityCollisionError,
+ ServerAuthorityRegistryError,
+} from './server-authority.ts';
+import { ServerAuthorityLeaseVerificationError } from './server-authority-lease.ts';
+
+vi.mock('node:fs', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('node:fs')>()),
+}));
+
+const root = resolve('/authority');
+const tree = (path = root, excluded: string[] = []): ContentScope => ({
+ kind: 'tree',
+ path,
+ excluded,
+});
+const file = (path = join(root, 'notes.md')): ContentScope => ({ kind: 'file', path });
+
+describe('contentScopesOverlap', () => {
+ test.each<[string, ContentScope, ContentScope, boolean]>([
+ ['equal roots', tree(), tree(), true],
+ ['nested roots', tree(), tree(join(root, 'child')), true],
+ ['boundary-prefix siblings', tree(), tree(`${root}-other`), false],
+ ['separate roots', tree(), tree(resolve('/elsewhere')), false],
+ ['filesystem root', tree(resolve('/')), tree(), true],
+ ['same file', file(), file(), true],
+ ['distinct files', file(), file(join(root, 'other.md')), false],
+ ['distinct extensions', file(), file(join(root, 'notes.mdx')), false],
+ ['file in tree', file(), tree(), true],
+ ['file outside tree', file(), tree(join(root, 'child')), false],
+ ['excluded child tree', tree(root, [join(root, 'child')]), tree(join(root, 'child')), false],
+ [
+ 'excluded grandchild tree',
+ tree(root, [join(root, 'child')]),
+ tree(join(root, 'child', 'docs')),
+ false,
+ ],
+ [
+ 'excluded file',
+ tree(root, [join(root, 'child')]),
+ file(join(root, 'child', 'notes.md')),
+ false,
+ ],
+ [
+ 'exclusion does not exclude boundary-prefix sibling',
+ tree(root, [join(root, 'child')]),
+ tree(join(root, 'child-other')),
+ true,
+ ],
+ [
+ 'partial exclusions do not make overlapping trees disjoint',
+ tree(root, [join(root, 'child')]),
+ tree(root, [join(root, 'elsewhere')]),
+ true,
+ ],
+ ])('%s', (_label, left, right, overlaps) => {
+ expect(contentScopesOverlap(left, right)).toBe(overlaps);
+ expect(contentScopesOverlap(right, left)).toBe(overlaps);
+ });
+});
+
+test('path membership agrees with overlap and exact-file identity', () => {
+ expect(contentScopeContainsPath(tree(), join(root, 'child', 'notes.md'))).toBe(true);
+ expect(contentScopeContainsPath(tree(), `${root}-other/notes.md`)).toBe(false);
+ expect(contentScopeContainsPath(tree(resolve('/')), root)).toBe(true);
+ expect(contentScopeContainsPath(tree(root, [join(root, 'child')]), join(root, 'child'))).toBe(
+ false,
+ );
+ expect(contentScopeContainsPath(file(), join(root, 'notes.md'))).toBe(true);
+ expect(contentScopeContainsPath(file(), join(root, 'notes.md', 'child'))).toBe(false);
+ expect(contentScopeContainsPath(tree(resolve('/')), 'relative.md')).toBe(false);
+});
+
+const replySchema = z.object({
+ status: z.enum(['ready', 'acquired', 'released', 'error']),
+ name: z.string().optional(),
+ message: z.string().optional(),
+ pid: z.number().optional(),
+});
+
+const driver = `
+const { acquireServerAuthority } = await import(process.env.AUTHORITY_MODULE);
+let claim;
+process.on('message', command => {
+ try {
+ if (command === 'acquire') {
+ claim = acquireServerAuthority(JSON.parse(process.env.AUTHORITY_OPTIONS));
+ process.send({ status: 'acquired', pid: process.pid });
+ } else if (command === 'release') {
+ claim.release();
+ process.send({ status: 'released' });
+ } else if (command === 'exit') {
+ process.exit(0);
+ }
+ } catch (error) {
+ process.send({ status: 'error', name: error.name, message: error.message });
+ }
+});
+process.send({ status: 'ready' });
+`;
+
+let directory: string;
+let registryPath: string;
+const releases: Array<() => void> = [];
+const workers: Array<{ child: ChildProcess; exited: Promise<void> }> = [];
+
+beforeEach(() => {
+ directory = mkdtempSync(join(tmpdir(), 'ok-server-authority-'));
+ registryPath = join(directory, 'runtime', 'authority.sqlite');
+});
+
+afterEach(async () => {
+ vi.restoreAllMocks();
+ for (const release of releases.splice(0)) release();
+ for (const { child, exited } of workers.splice(0)) {
+ if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+ await exited;
+ }
+ rmSync(directory, { recursive: true, force: true });
+});
+
+function claim(scope: ContentScope, serverInstanceId = randomUUID()) {
+ const handle = acquireServerAuthority({
+ scope,
+ projectDir: join(directory, serverInstanceId),
+ serverInstanceId,
+ registryPath,
+ });
+ releases.push(handle.release);
+ return handle;
+}
+
+async function startWorker(scope: ContentScope) {
+ let pending = Promise.withResolvers<z.infer<typeof replySchema>>();
+ let stderr = '';
+ const child = spawn(
+ process.execPath,
+ ['--import', 'tsx', '--input-type=module', '-e', driver],
+ withHiddenWindowsConsole({
+ cwd: fileURLToPath(new URL('..', import.meta.url)),
+ stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+ env: {
+ ...process.env,
+ AUTHORITY_MODULE: new URL('./server-authority.ts', import.meta.url).href,
+ AUTHORITY_OPTIONS: JSON.stringify({
+ scope,
+ projectDir: join(directory, randomUUID()),
+ serverInstanceId: randomUUID(),
+ registryPath,
+ }),
+ },
+ }),
+ );
+ child.stderr?.on('data', (chunk: Buffer) => {
+ stderr += chunk.toString();
+ });
+ child.on('message', (message) => {
+ const parsed = replySchema.safeParse(message);
+ if (parsed.success) pending.resolve(parsed.data);
+ else pending.reject(parsed.error);
+ });
+ child.on('error', (error) => pending.reject(error));
+ const exited = new Promise<void>((resolveExit) => {
+ child.once('close', (code, signal) => {
+ pending.reject(new Error(`Authority worker exited (${code}, ${signal}): ${stderr}`));
+ resolveExit();
+ });
+ });
+ workers.push({ child, exited });
+ expect((await pending.promise).status).toBe('ready');
+ return {
+ child,
+ exited,
+ exit() {
+ child.send('exit');
+ return exited;
+ },
+ send(command: 'acquire' | 'release') {
+ pending = Promise.withResolvers<z.infer<typeof replySchema>>();
+ child.send(command);
+ return pending.promise;
+ },
+ };
+}
+
+describe('acquireServerAuthority', () => {
+ test.each([
+ [517, 'contention'],
+ [261, 'contention'],
+ [779, 'invalid-data'],
+ [13, 'unknown'],
+ ] as const)(
+ 'extended SQLite result %s reports %s without a false permissions remedy',
+ (errcode, expected) => {
+ const cause = Object.assign(new Error('SQLite failure'), { errcode });
+ expect(classifyServerAuthorityRegistryError(cause)).toBe(expected);
+ const error = new ServerAuthorityRegistryError(expected, registryPath, cause);
+ expect(error.kind).toBe(expected);
+ expect(error.cause).toBe(cause);
+ expect(error.registryPath).toBe(registryPath);
+ expect(error.message).toContain('SQLite failure');
+ expect(error.message).not.toContain('writable OS-account home');
+ },
+ );
+ test('same-process different instances cannot claim overlapping scopes', () => {
+ const id = randomUUID();
+ claim(tree(), id);
+ try {
+ claim(file());
+ expect.fail('Overlapping authority must be refused');
+ } catch (error) {
+ expect(error).toBeInstanceOf(ServerAuthorityCollisionError);
+ if (!(error instanceof ServerAuthorityCollisionError)) throw error;
+ expect(error.existing).toMatchObject({
+ pid: process.pid,
+ projectDir: join(directory, id),
+ scope: tree(),
+ });
+ }
+ });
+
+ test('disjoint scopes coexist and release is idempotent without deleting a replacement', () => {
+ const id = randomUUID();
+ const first = claim(file(), id);
+ const second = claim(file(join(root, 'other.md')));
+ first.release();
+ claim(file(), id);
+ first.release();
+ expect(() => claim(file())).toThrow(ServerAuthorityCollisionError);
+ second.release();
+ expect(() => claim(file(join(root, 'other.md')))).not.toThrow();
+ });
+
+ test('claim scope is an immutable snapshot rather than the caller array', () => {
+ const excluded = [join(root, 'child')];
+ const input = { kind: 'tree' as const, path: root, excluded };
+ const handle = claim(input);
+ excluded.push(join(root, 'new-child'));
+ input.path = resolve('/changed');
+ expect(handle.scope).toEqual(tree(root, [join(root, 'child')]));
+ expect(Object.isFrozen(handle.scope)).toBe(true);
+ expect(handle.scope.kind === 'tree' && Object.isFrozen(handle.scope.excluded)).toBe(true);
+ expect(() => claim(tree(join(root, 'new-child')))).toThrow(ServerAuthorityCollisionError);
+ expect(() => claim(tree(join(root, 'child')))).not.toThrow();
+ });
+
+ test('an unreleased handle cannot delete a row whose ownership token was replaced', () => {
+ const handle = claim(tree());
+ const db = new DatabaseSync(registryPath);
+ try {
+ db.prepare('UPDATE server_authority SET owner_token = ?').run(randomUUID());
+ } finally {
+ db.close();
+ }
+ handle.release();
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ });
+
+ test.each([
+ tree('relative'),
+ tree(root, [root]),
+ tree(root, [resolve('/outside')]),
+ file('relative.md'),
+ ])('invalid scope is refused without reserving authority: %j', (scope) => {
+ expect(() => claim(scope)).toThrow();
+ expect(() => claim(tree())).not.toThrow();
+ });
+
+ test('corrupt registry fails closed instead of resetting it', () => {
+ writeFileSync(join(directory, 'corrupt.sqlite'), 'not a SQLite database');
+ registryPath = join(directory, 'corrupt.sqlite');
+ expect(() => claim(tree())).toThrow(ServerAuthorityRegistryError);
+ expect(() => claim(tree())).toThrow(registryPath);
+ expect(() => claim(tree())).toThrow(/Never remove either while a server is running/);
+ });
+
+ test('unwritable registry location fails closed', () => {
+ const parentFile = join(directory, 'not-a-directory');
+ writeFileSync(parentFile, 'file');
+ registryPath = join(parentFile, 'authority.sqlite');
+ expect(() => claim(tree())).toThrow();
+ });
+
+ test('an unknown registry version fails closed without erasing a held scope', () => {
+ const handle = claim(tree());
+ const db = new DatabaseSync(registryPath);
+ try {
+ db.exec('PRAGMA user_version = 999');
+ expect(() => claim(file())).toThrow(
+ 'This runtime does not support the content ownership registry version.',
+ );
+ db.exec('PRAGMA user_version = 2');
+ expect(() => claim(file())).toThrow(ServerAuthorityCollisionError);
+ } finally {
+ db.close();
+ handle.release();
+ }
+ });
+
+ test('the known empty unreleased v1 layout upgrades atomically without discarding any claim', () => {
+ mkdirSync(dirname(registryPath), { recursive: true });
+ const database = new DatabaseSync(registryPath);
+ database.exec(`CREATE TABLE server_authority (
+ server_instance_id TEXT PRIMARY KEY, owner_token TEXT NOT NULL, pid INTEGER NOT NULL,
+ hostname TEXT NOT NULL, machine_id TEXT NOT NULL, project_dir TEXT NOT NULL,
+ scope_json TEXT NOT NULL, started_at TEXT NOT NULL
+ ) STRICT; PRAGMA user_version = 1`);
+ database.close();
+ claim(tree());
+ const check = new DatabaseSync(registryPath);
+ try {
+ expect(check.prepare('PRAGMA user_version').get()?.user_version).toBe(2);
+ expect(
+ check.prepare('SELECT lease_protocol FROM server_authority').get()?.lease_protocol,
+ ).toBe('sqlite-lifetime-lease:v1');
+ } finally {
+ check.close();
+ }
+ });
+
+ test.each(['nonempty', 'different-columns'] as const)(
+ 'a %s v1 layout is retained with actionable retired-format recovery',
+ (state) => {
+ mkdirSync(dirname(registryPath), { recursive: true });
+ const database = new DatabaseSync(registryPath);
+ try {
+ if (state === 'nonempty') {
+ database.exec(`CREATE TABLE server_authority (
+ server_instance_id TEXT PRIMARY KEY, owner_token TEXT NOT NULL, pid INTEGER NOT NULL,
+ hostname TEXT NOT NULL, machine_id TEXT NOT NULL, project_dir TEXT NOT NULL,
+ scope_json TEXT NOT NULL, started_at TEXT NOT NULL
+ ) STRICT`);
+ database
+ .prepare('INSERT INTO server_authority VALUES (?, ?, ?, ?, ?, ?, ?, ?)')
+ .run(
+ randomUUID(),
+ randomUUID(),
+ process.pid,
+ 'legacy',
+ 'legacy',
+ directory,
+ JSON.stringify(tree()),
+ new Date().toISOString(),
+ );
+ } else database.exec('CREATE TABLE server_authority (unexpected TEXT) STRICT');
+ database.exec('PRAGMA user_version = 1');
+ const rows = database.prepare('SELECT * FROM server_authority').all();
+ const columns = database.prepare('PRAGMA table_info(server_authority)').all();
+ try {
+ claim(tree());
+ expect.fail('Retired layout must not be discarded');
+ } catch (error) {
+ expect(error).toBeInstanceOf(ServerAuthorityRegistryError);
+ expect((error as ServerAuthorityRegistryError).kind).toBe('retired-version');
+ expect((error as Error).message).toContain(
+ 'This runtime no longer reads the retired pre-release content ownership registry layout.',
+ );
+ expect((error as Error).message).toContain(`Registry: ${registryPath}.`);
+ expect((error as Error).message).not.toContain('Version 1.');
+ expect((error as Error).message).toContain('ok stop all');
+ expect((error as Error).message).toContain('-journal');
+ }
+ expect(database.prepare('PRAGMA user_version').get()?.user_version).toBe(1);
+ expect(database.prepare('SELECT * FROM server_authority').all()).toEqual(rows);
+ expect(database.prepare('PRAGMA table_info(server_authority)').all()).toEqual(columns);
+ } finally {
+ database.close();
+ }
+ },
+ );
+
+ test('optional orphan collection failure cannot refuse a valid acquisition', () => {
+ const read = vi.spyOn(fs, 'readdirSync').mockImplementationOnce(() => {
+ throw Object.assign(new Error('Garbage collection descriptor limit'), { code: 'EMFILE' });
+ });
+ expect(() => claim(tree())).not.toThrow();
+ expect(read).toHaveBeenCalledOnce();
+ read.mockRestore();
+ const check = new DatabaseSync(registryPath);
+ try {
+ expect(check.prepare('SELECT scope_json FROM server_authority').get()?.scope_json).toBe(
+ JSON.stringify(tree()),
+ );
+ } finally {
+ check.close();
+ }
+ });
+
+ test('a malformed holder record fails closed rather than being treated as stale', () => {
+ claim(tree());
+ const db = new DatabaseSync(registryPath);
+ try {
+ db.prepare('UPDATE server_authority SET pid = ?').run(0);
+ } finally {
+ db.close();
+ }
+ expect(() => claim(file(join(root, 'other.md')))).toThrow();
+ });
+
+ test('unexpected process-probe failure cannot reclaim a live holder', () => {
+ claim(tree());
+ vi.spyOn(process, 'kill').mockImplementation(() => {
+ throw Object.assign(new Error('Unknown probe failure'), { code: 'EINVAL' });
+ });
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ });
+
+ test('EPERM process-probe failure cannot reclaim a live holder', () => {
+ claim(tree());
+ vi.spyOn(process, 'kill').mockImplementation(() => {
+ throw Object.assign(new Error('Permission denied'), { code: 'EPERM' });
+ });
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ });
+
+ test('independent simultaneous conflicting starts grant exactly one lifetime claim', async () => {
+ const [left, right] = await Promise.all([
+ startWorker(tree()),
+ startWorker(tree(join(root, 'child'))),
+ ]);
+ const replies = await Promise.all([left.send('acquire'), right.send('acquire')]);
+ expect(replies.map((reply) => reply.status).sort()).toEqual(['acquired', 'error']);
+ expect(replies.find((reply) => reply.status === 'error')?.name).toBe(
+ 'ServerAuthorityCollisionError',
+ );
+ expect(() => claim(file(join(root, 'child', 'notes.md')))).toThrow(
+ ServerAuthorityCollisionError,
+ );
+ });
+
+ test('independent simultaneous disjoint file previews both retain authority', async () => {
+ const [left, right] = await Promise.all([
+ startWorker(file()),
+ startWorker(file(join(root, 'other.md'))),
+ ]);
+ const replies = await Promise.all([left.send('acquire'), right.send('acquire')]);
+ expect(replies.map((reply) => reply.status)).toEqual(['acquired', 'acquired']);
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ expect((await left.send('release')).status).toBe('released');
+ expect(() => claim(file())).not.toThrow();
+ expect(() => claim(file(join(root, 'other.md')))).toThrow(ServerAuthorityCollisionError);
+ });
+
+ test('independent parent and excluded child trees can acquire concurrently', async () => {
+ const childRoot = join(root, 'child');
+ const [parent, child] = await Promise.all([
+ startWorker(tree(root, [childRoot])),
+ startWorker(tree(childRoot)),
+ ]);
+ const replies = await Promise.all([parent.send('acquire'), child.send('acquire')]);
+ expect(replies.map((reply) => reply.status)).toEqual(['acquired', 'acquired']);
+ expect(() => claim(file(join(childRoot, 'notes.md')))).toThrow(ServerAuthorityCollisionError);
+ expect(() => claim(file())).toThrow(ServerAuthorityCollisionError);
+ });
+
+ test('a crashed holder is pruned only after its process actually exits', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ worker.child.kill('SIGKILL');
+ await worker.exited;
+ expect(() => claim(tree())).not.toThrow();
+ });
+
+ test.each(['missing', 'wal', 'mismatched-token', 'garbage', 'present-unreadable'] as const)(
+ 'an unverifiable %s lease protects only its recorded scope',
+ async (damage) => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ worker.child.kill('SIGKILL');
+ await worker.exited;
+ const registry = new DatabaseSync(registryPath);
+ const token = registry.prepare('SELECT owner_token FROM server_authority').get()?.owner_token;
+ registry.close();
+ if (typeof token !== 'string') throw new Error('Owner token absent');
+ const path = join(dirname(registryPath), 'server-authority-leases', `${token}.sqlite`);
+ if (damage === 'missing') unlinkSync(path);
+ else if (damage === 'garbage') writeFileSync(path, 'not a SQLite lease');
+ else if (damage === 'present-unreadable') {
+ unlinkSync(path);
+ mkdirSync(path);
+ } else {
+ const lease = new DatabaseSync(path);
+ if (damage === 'wal') lease.exec('PRAGMA journal_mode=WAL');
+ else lease.prepare('UPDATE lease SET owner_token = ?').run(randomUUID());
+ lease.close();
+ }
+ expect(() => claim(tree(`${root}-disjoint`))).not.toThrow();
+ try {
+ claim(tree());
+ expect.fail('Unverifiable ownership must remain protected');
+ } catch (error) {
+ expect(error).toBeInstanceOf(ServerAuthorityCollisionError);
+ expect((error as ServerAuthorityCollisionError).verifiedLease).toBe(false);
+ expect((error as ServerAuthorityCollisionError).leasePath).toBe(path);
+ expect((error as Error).cause).toBeInstanceOf(ServerAuthorityLeaseVerificationError);
+ expect(((error as Error).cause as ServerAuthorityLeaseVerificationError).kind).toBe(
+ damage === 'missing'
+ ? 'missing'
+ : damage === 'present-unreadable'
+ ? 'unavailable'
+ : 'invalid-data',
+ );
+ if (damage === 'present-unreadable') {
+ expect((error as Error).message).toContain('temporarily unavailable');
+ expect((error as Error).message).toContain('retry');
+ } else expect((error as Error).message).not.toContain('retry');
+ expect((error as Error).message).toContain('could not be verified');
+ expect((error as Error).message).toContain(registryPath);
+ expect((error as Error).message).toContain('ok stop all');
+ }
+ },
+ );
+
+ test('a live SQLite lease cannot be stolen when the holder PID is invisible', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ const probe = vi.spyOn(process, 'kill').mockImplementation(() => {
+ throw Object.assign(new Error('Foreign PID namespace'), { code: 'ESRCH' });
+ });
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ expect(probe).not.toHaveBeenCalled();
+ probe.mockRestore();
+ });
+
+ test('an exited SQLite lease is reclaimed even if the old PID now appears alive', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ worker.child.kill('SIGKILL');
+ await worker.exited;
+ const probe = vi.spyOn(process, 'kill').mockReturnValue(true);
+ expect(() => claim(tree())).not.toThrow();
+ expect(probe).not.toHaveBeenCalled();
+ probe.mockRestore();
+ });
+
+ test('crash reclamation ignores the recorded PID display metadata', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ const db = new DatabaseSync(registryPath);
+ try {
+ db.prepare('UPDATE server_authority SET pid = ?').run(process.pid);
+ } finally {
+ db.close();
+ }
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ worker.child.kill('SIGKILL');
+ await worker.exited;
+ expect(() => claim(tree())).not.toThrow();
+ });
+
+ test('an unrecognized lifetime-lease protocol fails closed', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ const db = new DatabaseSync(registryPath);
+ try {
+ db.prepare('UPDATE server_authority SET lease_protocol = ?').run('unknown-protocol');
+ } finally {
+ db.close();
+ }
+ worker.child.kill('SIGKILL');
+ await worker.exited;
+ try {
+ claim(tree());
+ expect.fail('Unknown lease protocols must remain protected');
+ } catch (error) {
+ expect(error).toBeInstanceOf(ServerAuthorityCollisionError);
+ expect((error as ServerAuthorityCollisionError).verifiedLease).toBe(false);
+ expect((error as ServerAuthorityCollisionError).leasePath).toBeUndefined();
+ expect((error as Error).message).toContain('unknown-protocol');
+ expect((error as Error).message).toContain('compatible version');
+ expect((error as Error).message).not.toContain('back up');
+ expect((error as Error).message).not.toContain('remove');
+ }
+ });
+
+ test('the registry is owner-only on filesystems supporting POSIX modes', () => {
+ claim(tree());
+ if (process.platform !== 'win32') expect(statSync(registryPath).mode & 0o777).toBe(0o600);
+ });
+
+ test('legacy rows without lifetime leases fail closed even when their old PID is gone', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ const db = new DatabaseSync(registryPath);
+ db.prepare('UPDATE server_authority SET lease_protocol = ?').run('unverified:legacy');
+ db.close();
+ worker.child.kill('SIGKILL');
+ await worker.exited;
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ });
+
+ test('legacy PID-domain records cannot be interpreted as lifetime-lease proof', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ const db = new DatabaseSync(registryPath);
+ try {
+ db.prepare('UPDATE server_authority SET lease_protocol = ?').run(
+ 'process-domain:v1:linux:foreign-boot:pid:[4026539999]',
+ );
+ } finally {
+ db.close();
+ }
+ worker.child.kill('SIGKILL');
+ await worker.exited;
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ });
+
+ test('normal process exit releases its own lifetime claim', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ await worker.exit();
+ const db = new DatabaseSync(registryPath);
+ try {
+ expect(db.prepare('SELECT * FROM server_authority').all()).toEqual([]);
+ } finally {
+ db.close();
+ }
+ expect(() => claim(tree())).not.toThrow();
+ });
+
+ test('an arbitrarily old live claim is not stolen by a timeout or TTL', async () => {
+ const worker = await startWorker(tree());
+ expect((await worker.send('acquire')).status).toBe('acquired');
+ const db = new DatabaseSync(registryPath);
+ try {
+ db.prepare('UPDATE server_authority SET started_at = ?').run('1970-01-01T00:00:00.000Z');
+ } finally {
+ db.close();
+ }
+ expect(() => claim(tree())).toThrow(ServerAuthorityCollisionError);
+ });
+});
diff --git a/packages/server/src/server-authority.ts b/packages/server/src/server-authority.ts
new file mode 100644
index 000000000..0645b05bb
--- /dev/null
+++ b/packages/server/src/server-authority.ts
@@ -0,0 +1,440 @@
+import { randomUUID } from 'node:crypto';
+import { userInfo } from 'node:os';
+import { dirname, isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { LOCAL_DIR, OK_DIR, SERVER_AUTHORITY_REGISTRY_FILENAME } from '@inkeep/open-knowledge-core';
+import { z } from 'zod';
+import {
+ normalizeFsPath,
+ tracedChmodSync,
+ tracedMkdirSync,
+ tracedWriteFileSync,
+} from './fs-traced.ts';
+import { getLogger } from './logger.ts';
+import {
+ acquireServerAuthorityLease,
+ collectServerAuthorityLeaseOrphansUnderRegistryTransaction,
+ isServerAuthorityLeaseReleased,
+ removeReleasedServerAuthorityLease,
+ SERVER_AUTHORITY_LEASE_PROTOCOL,
+ ServerAuthorityLeaseVerificationError,
+} from './server-authority-lease.ts';
+import { withSpanSync } from './telemetry.ts';
+
+export type ContentScope =
+ | { readonly kind: 'tree'; readonly path: string; readonly excluded: readonly string[] }
+ | { readonly kind: 'file'; readonly path: string };
+
+export interface ServerAuthorityHolder {
+ readonly projectDir: string;
+ readonly scope: ContentScope;
+ readonly pid: number;
+ readonly serverInstanceId: string;
+}
+
+type ServerAuthorityVerification =
+ | { kind: 'held' }
+ | { kind: 'protocol-mismatch'; protocol: string }
+ | { kind: 'failed'; error: ServerAuthorityLeaseVerificationError };
+
+function ownershipRegistryRecovery(registryPath: string | undefined): string {
+ return `Run ok stop all and confirm every OpenKnowledge server under this OS account has exited. Then back up and remove ${registryPath ?? 'the named ownership registry'} together with its -journal file if present, keeping them together as one backup. Never remove either while a server is running.`;
+}
+
+function unverifiedOwnershipMessage(
+ existing: ServerAuthorityHolder,
+ registryPath: string | undefined,
+ verification: Exclude<ServerAuthorityVerification, { kind: 'held' }>,
+): string {
+ const prefix = `Existing content ownership for ${existing.scope.path} in ${existing.projectDir} could not be verified. `;
+ if (verification.kind === 'protocol-mismatch')
+ return `${prefix}The ownership protocol ${verification.protocol} is not supported by this runtime. Update every OpenKnowledge runtime to a compatible version; no ownership record was cleared.`;
+ const error = verification.error;
+ const detail = `Lease ${error.leasePath}: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}. `;
+ const recovery = ownershipRegistryRecovery(registryPath);
+ return (
+ prefix +
+ detail +
+ (error.kind === 'unavailable'
+ ? `Lease access may be temporarily unavailable. First check access to the named lease and retry. If the failure persists, use manual recovery: ${recovery}`
+ : recovery)
+ );
+}
+
+export class ServerAuthorityCollisionError extends Error {
+ readonly existing: ServerAuthorityHolder;
+ readonly verifiedLease: boolean;
+ readonly leasePath: string | undefined;
+
+ constructor(
+ existing: ServerAuthorityHolder,
+ registryPath?: string,
+ verification: ServerAuthorityVerification = { kind: 'held' },
+ ) {
+ super(
+ verification.kind === 'held'
+ ? `OpenKnowledge content ownership is already held by ${existing.scope.kind === 'file' ? `a single-file preview of ${existing.scope.path}` : `the project server for ${existing.projectDir}`} (pid ${existing.pid}, content ${existing.scope.path}). Close that session before opening an overlapping content scope.`
+ : unverifiedOwnershipMessage(existing, registryPath, verification),
+ verification.kind === 'failed' ? { cause: verification.error } : undefined,
+ );
+ this.name = 'ServerAuthorityCollisionError';
+ this.existing = existing;
+ this.verifiedLease = verification.kind === 'held';
+ this.leasePath = verification.kind === 'failed' ? verification.error.leasePath : undefined;
+ }
+}
+
+export class ServerAuthorityRegistryError extends Error {
+ readonly kind:
+ | 'unavailable'
+ | 'unsupported-version'
+ | 'retired-version'
+ | 'invalid-data'
+ | 'contention'
+ | 'unknown';
+ readonly registryPath: string | undefined;
+
+ constructor(kind: 'unavailable', registryPath: undefined, cause: unknown);
+ constructor(kind: ServerAuthorityRegistryError['kind'], registryPath: string, cause: unknown);
+ constructor(
+ kind: ServerAuthorityRegistryError['kind'],
+ registryPath: string | undefined,
+ cause: unknown,
+ ) {
+ const headers: Record<ServerAuthorityRegistryError['kind'], string> = {
+ 'unsupported-version': 'This runtime does not support the content ownership registry version',
+ 'retired-version':
+ 'This runtime no longer reads the retired pre-release content ownership registry layout',
+ contention: 'The content ownership registry is being updated by another runtime',
+ unavailable: 'The content ownership registry cannot be accessed',
+ 'invalid-data': 'The content ownership registry contains invalid data',
+ unknown: 'The content ownership registry could not be read or updated',
+ };
+ const remedies: Record<ServerAuthorityRegistryError['kind'], string> = {
+ 'unsupported-version': 'Update every OpenKnowledge runtime to a compatible version.',
+ 'retired-version': ownershipRegistryRecovery(registryPath),
+ contention: 'Another runtime is updating the registry; try starting again.',
+ unavailable:
+ 'Check the named location and its permissions; the default registry requires a registered, writable OS-account home.',
+ 'invalid-data': ownershipRegistryRecovery(registryPath),
+ unknown:
+ 'Check the underlying error before retrying. The registry has not been reset and ownership protection cannot be disabled.',
+ };
+ super(
+ `${headers[kind]}. ${registryPath === undefined ? 'The OS-account home could not be resolved' : `Registry: ${registryPath}`}. ` +
+ `${cause instanceof Error ? cause.message : String(cause)}. ${remedies[kind]}`,
+ { cause },
+ );
+ this.name = 'ServerAuthorityRegistryError';
+ this.kind = kind;
+ this.registryPath = registryPath;
+ }
+}
+
+export function classifyServerAuthorityRegistryError(
+ error: unknown,
+): ServerAuthorityRegistryError['kind'] {
+ const value =
+ typeof error === 'object' && error !== null
+ ? (error as { errcode?: unknown; code?: unknown })
+ : undefined;
+ const code = typeof value?.errcode === 'number' ? value.errcode & 0xff : undefined;
+ if (code === 5 || code === 6) return 'contention';
+ if (code === 11 || code === 26 || error instanceof z.ZodError || error instanceof SyntaxError)
+ return 'invalid-data';
+ if (
+ typeof value?.code === 'string' &&
+ ['EACCES', 'EPERM', 'ENOENT', 'ENOTDIR', 'EROFS', 'ERR_SYSTEM_ERROR'].includes(value.code)
+ )
+ return 'unavailable';
+ return 'unknown';
+}
+
+const pathSchema = z
+ .string()
+ .min(1)
+ .refine((path) => !path.includes('\0') && isAbsolute(path) && normalize(path) === path);
+const scopeSchema = z.discriminatedUnion('kind', [
+ z.object({ kind: z.literal('file'), path: pathSchema }),
+ z
+ .object({ kind: z.literal('tree'), path: pathSchema, excluded: z.array(pathSchema) })
+ .refine(({ path, excluded }) =>
+ excluded.every(
+ (excludedPath) => relative(path, excludedPath) !== '' && containsPath(path, excludedPath),
+ ),
+ ),
+]);
+const holderRowSchema = z.object({
+ server_instance_id: z.string().min(1),
+ owner_token: z.uuid(),
+ pid: z.number().int().positive(),
+ lease_protocol: z.string().min(1),
+ project_dir: pathSchema,
+ scope_json: z.string(),
+ started_at: z.iso.datetime(),
+});
+const exitReleases = new Set<() => void>();
+let exitHandlerRegistered = false;
+
+function containsPath(parent: string, child: string): boolean {
+ const rel = relative(parent, child);
+ return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+export function contentScopeContainsPath(scope: ContentScope, path: string): boolean {
+ return (
+ isAbsolute(path) &&
+ containsPath(scope.path, path) &&
+ (scope.kind === 'file'
+ ? relative(scope.path, path) === ''
+ : !scope.excluded.some((excluded) => containsPath(excluded, path)))
+ );
+}
+
+export function contentScopesOverlap(left: ContentScope, right: ContentScope): boolean {
+ if (left.kind === 'file') return contentScopeContainsPath(right, left.path);
+ if (right.kind === 'file') return contentScopeContainsPath(left, right.path);
+ const deeperRoot = containsPath(left.path, right.path) ? right.path : left.path;
+ return contentScopeContainsPath(left, deeperRoot) && contentScopeContainsPath(right, deeperRoot);
+}
+
+function immutableScope(value: unknown): ContentScope {
+ const scope = scopeSchema.parse(value);
+ return scope.kind === 'file'
+ ? Object.freeze(scope)
+ : Object.freeze({ ...scope, excluded: Object.freeze(scope.excluded) });
+}
+
+function authoritySpan<T>(operation: 'acquire' | 'release', registryPath: string, fn: () => T): T {
+ return withSpanSync(
+ 'fs.serverAuthority',
+ {
+ attributes: {
+ 'fs.operation': 'serverAuthority',
+ 'fs.path': normalizeFsPath(registryPath),
+ 'fs.path.role': 'ok-internal',
+ 'fs.sqlite.operation': operation,
+ },
+ },
+ fn,
+ );
+}
+
+export function acquireServerAuthority(options: {
+ scope: ContentScope;
+ projectDir: string;
+ serverInstanceId: string;
+ registryPath?: string;
+}): { scope: ContentScope; release: () => void } {
+ const scope = immutableScope(options.scope);
+ const projectDir = pathSchema.parse(options.projectDir);
+ const serverInstanceId = z.string().min(1).parse(options.serverInstanceId);
+ let osHome: string;
+ try {
+ osHome = userInfo().homedir;
+ } catch (error) {
+ if (options.registryPath === undefined) {
+ throw new ServerAuthorityRegistryError('unavailable', undefined, error);
+ }
+ osHome = dirname(options.registryPath);
+ }
+ const registryPath =
+ options.registryPath ?? resolve(osHome, OK_DIR, LOCAL_DIR, SERVER_AUTHORITY_REGISTRY_FILENAME);
+ pathSchema.parse(registryPath);
+ const ownerToken = randomUUID();
+ let releaseLease: (() => void) | undefined;
+ const db = authoritySpan('acquire', registryPath, () => {
+ let database: DatabaseSync | undefined;
+ const prunedLeases: Array<{
+ token: string;
+ projectDir: string;
+ scopeKind: ContentScope['kind'];
+ startedAt: string;
+ }> = [];
+ try {
+ tracedMkdirSync(dirname(registryPath), { recursive: true, mode: 0o700 });
+ try {
+ tracedWriteFileSync(registryPath, '', { flag: 'wx', mode: 0o600 });
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+ }
+ tracedChmodSync(registryPath, 0o600);
+ database = new DatabaseSync(registryPath, { timeout: 5_000 });
+ database.exec('BEGIN IMMEDIATE');
+ const version = database.prepare('PRAGMA user_version').get()?.user_version;
+ const emptyLegacy =
+ version === 1 &&
+ database
+ .prepare('PRAGMA table_info(server_authority)')
+ .all()
+ .map((column) => column.name)
+ .join(',') ===
+ 'server_instance_id,owner_token,pid,hostname,machine_id,project_dir,scope_json,started_at' &&
+ database.prepare('SELECT count(*) AS count FROM server_authority').get()?.count === 0;
+ if (version !== 0 && version !== 2 && !emptyLegacy) {
+ throw new ServerAuthorityRegistryError(
+ version === 1 ? 'retired-version' : 'unsupported-version',
+ registryPath,
+ new Error(`Registry layout version ${version} is not supported by this runtime`),
+ );
+ }
+ if (database.prepare('PRAGMA journal_mode').get()?.journal_mode !== 'delete')
+ throw new ServerAuthorityRegistryError(
+ 'unsupported-version',
+ registryPath,
+ new Error('Content ownership requires SQLite DELETE-mode file locking'),
+ );
+ if (emptyLegacy) database.exec('DROP TABLE server_authority');
+ database.exec(`
+ CREATE TABLE IF NOT EXISTS server_authority (
+ server_instance_id TEXT PRIMARY KEY,
+ owner_token TEXT NOT NULL,
+ pid INTEGER NOT NULL,
+ lease_protocol TEXT NOT NULL,
+ project_dir TEXT NOT NULL,
+ scope_json TEXT NOT NULL,
+ started_at TEXT NOT NULL
+ ) STRICT;
+ PRAGMA user_version = 2;
+ `);
+ const holders = database
+ .prepare('SELECT * FROM server_authority')
+ .all()
+ .map((rawRow) => {
+ const row = holderRowSchema.parse(rawRow);
+ return { row, scope: immutableScope(JSON.parse(row.scope_json)) };
+ });
+ collectServerAuthorityLeaseOrphansUnderRegistryTransaction(
+ registryPath,
+ database,
+ new Set(holders.map(({ row }) => row.owner_token)),
+ );
+ for (const { row, scope: existingScope } of holders) {
+ const overlaps =
+ row.server_instance_id === serverInstanceId || contentScopesOverlap(scope, existingScope);
+ if (!overlaps) continue;
+ let verification: ServerAuthorityVerification =
+ row.lease_protocol === SERVER_AUTHORITY_LEASE_PROTOCOL
+ ? { kind: 'held' }
+ : { kind: 'protocol-mismatch', protocol: row.lease_protocol };
+ let leaseReleased = false;
+ if (verification.kind === 'held') {
+ try {
+ leaseReleased = isServerAuthorityLeaseReleased(registryPath, row.owner_token);
+ } catch (error) {
+ if (!(error instanceof ServerAuthorityLeaseVerificationError)) throw error;
+ verification = { kind: 'failed', error };
+ getLogger('server-authority').warn(
+ { err: error, registryPath },
+ 'Content ownership lease could not be verified',
+ );
+ }
+ }
+ if (leaseReleased) {
+ database
+ .prepare(
+ 'DELETE FROM server_authority WHERE server_instance_id = ? AND owner_token = ?',
+ )
+ .run(row.server_instance_id, row.owner_token);
+ prunedLeases.push({
+ token: row.owner_token,
+ projectDir: row.project_dir,
+ scopeKind: existingScope.kind,
+ startedAt: row.started_at,
+ });
+ continue;
+ }
+ throw new ServerAuthorityCollisionError(
+ {
+ projectDir: row.project_dir,
+ scope: existingScope,
+ pid: row.pid,
+ serverInstanceId: row.server_instance_id,
+ },
+ registryPath,
+ verification,
+ );
+ }
+ releaseLease = acquireServerAuthorityLease(registryPath, ownerToken);
+ database
+ .prepare(
+ 'INSERT INTO server_authority (server_instance_id, owner_token, pid, lease_protocol, project_dir, scope_json, started_at) VALUES (?, ?, ?, ?, ?, ?, ?)',
+ )
+ .run(
+ serverInstanceId,
+ ownerToken,
+ process.pid,
+ SERVER_AUTHORITY_LEASE_PROTOCOL,
+ projectDir,
+ JSON.stringify(scope),
+ new Date().toISOString(),
+ );
+ database.exec('COMMIT');
+ for (const holder of prunedLeases) {
+ getLogger('server-authority').info(
+ {
+ projectDir: holder.projectDir,
+ scopeKind: holder.scopeKind,
+ startedAt: holder.startedAt,
+ registryPath,
+ },
+ 'Reclaimed released content ownership lease',
+ );
+ removeReleasedServerAuthorityLease(registryPath, holder.token);
+ }
+ return database;
+ } catch (error) {
+ database?.close();
+ try {
+ releaseLease?.();
+ } catch (cleanupError) {
+ getLogger('server-authority').warn(
+ { err: cleanupError },
+ 'Content ownership lease cleanup failed',
+ );
+ }
+ if (
+ error instanceof ServerAuthorityCollisionError ||
+ error instanceof ServerAuthorityRegistryError
+ )
+ throw error;
+ throw new ServerAuthorityRegistryError(
+ classifyServerAuthorityRegistryError(error),
+ registryPath,
+ error,
+ );
+ }
+ });
+
+ let released = false;
+ const release = (): void => {
+ if (released) return;
+ authoritySpan('release', registryPath, () => {
+ db.prepare(`
+ DELETE FROM server_authority
+ WHERE server_instance_id = ? AND owner_token = ?
+ `).run(serverInstanceId, ownerToken);
+ db.close();
+ releaseLease?.();
+ });
+ released = true;
+ exitReleases.delete(release);
+ };
+ exitReleases.add(release);
+ if (!exitHandlerRegistered) {
+ exitHandlerRegistered = true;
+ process.prependOnceListener('exit', () => {
+ for (const releaseAtExit of exitReleases) {
+ try {
+ releaseAtExit();
+ } catch (error) {
+ getLogger('server-authority').warn(
+ { err: error },
+ 'Content ownership exit release failed',
+ );
+ }
+ }
+ });
+ }
+ return { scope, release };
+}
diff --git a/packages/server/src/server-authority.type-tests.ts b/packages/server/src/server-authority.type-tests.ts
new file mode 100644
index 000000000..2dbd96369
--- /dev/null
+++ b/packages/server/src/server-authority.type-tests.ts
@@ -0,0 +1,6 @@
+import { ServerAuthorityRegistryError } from './server-authority.ts';
+
+new ServerAuthorityRegistryError('unavailable', undefined, new Error());
+new ServerAuthorityRegistryError('invalid-data', '/registry.sqlite', new Error());
+// @ts-expect-error -- Only an unresolved OS-account home can lack a registry path
+new ServerAuthorityRegistryError('invalid-data', undefined, new Error());
diff --git a/packages/server/src/server-content-policy.test.ts b/packages/server/src/server-content-policy.test.ts
new file mode 100644
index 000000000..7d2a30a10
--- /dev/null
+++ b/packages/server/src/server-content-policy.test.ts
@@ -0,0 +1,97 @@
+import {
+ mkdirSync,
+ mkdtempSync,
+ realpathSync,
+ rmSync,
+ symlinkSync,
+ unlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+import * as projectRoots from './fs/find-project-root.ts';
+import {
+ assertServerContentPath,
+ assertServerContentSubtree,
+ canonicalContentPath,
+ snapshotServerContentScope,
+} from './server-content-policy.ts';
+
+let root: string;
+beforeEach(() => {
+ root = realpathSync(mkdtempSync(join(tmpdir(), 'ok-authority-policy-')));
+});
+afterEach(() => {
+ vi.restoreAllMocks();
+ rmSync(root, { recursive: true, force: true });
+});
+
+test('an unreadable marker does not abandon sibling project exclusions', () => {
+ for (const name of ['first', 'second']) {
+ mkdirSync(join(root, name, '.ok'), { recursive: true });
+ writeFileSync(join(root, name, '.ok', 'config.yml'), '');
+ }
+ const probe = projectRoots.isProjectRoot;
+ let unreadable: string | undefined;
+ vi.spyOn(projectRoots, 'isProjectRoot').mockImplementation((path) => {
+ if (unreadable === undefined) {
+ unreadable = path;
+ throw Object.assign(new Error('Permission denied'), { code: 'EACCES' });
+ }
+ return probe(path);
+ });
+ const scope = snapshotServerContentScope(root);
+ expect(scope.kind).toBe('tree');
+ if (scope.kind !== 'tree') throw new Error('Expected tree scope');
+ expect(scope.excluded).toHaveLength(1);
+ expect(scope.excluded[0]).not.toBe(unreadable);
+});
+
+test('removing a nested marker never expands a captured epoch', () => {
+ const child = join(root, 'nested');
+ mkdirSync(join(child, '.ok'), { recursive: true });
+ writeFileSync(join(child, '.ok', 'config.yml'), '');
+ const scope = snapshotServerContentScope(root);
+ unlinkSync(join(child, '.ok', 'config.yml'));
+ expect(() => assertServerContentPath(scope, join(child, 'new.md'))).toThrow(/nested project/i);
+ expect(() => assertServerContentSubtree(scope, root)).toThrow(/nested project/i);
+ expect(() => assertServerContentPath(scope, join(root, 'own.md'))).not.toThrow();
+});
+
+test.each(['build', 'vendor', 'node_modules', '.cache'])(
+ 'marked projects inside %s are excluded even when ingestion skips that directory',
+ (directory) => {
+ const child = join(root, directory, 'nested');
+ mkdirSync(join(child, '.ok'), { recursive: true });
+ writeFileSync(join(child, '.ok', 'config.yml'), '');
+ expect(snapshotServerContentScope(root)).toMatchObject({ kind: 'tree', excluded: [child] });
+ },
+);
+
+test('a preview admits only its exact physical file, not sibling docs or folders', () => {
+ writeFileSync(join(root, 'one.md'), '# One\n');
+ symlinkSync(join(root, 'one.md'), join(root, 'alias.md'), 'file');
+ const scope = snapshotServerContentScope(root, 'one.md');
+ expect(() => assertServerContentPath(scope, join(root, 'alias.md'))).not.toThrow();
+ expect(() => assertServerContentPath(scope, join(root, 'two.md'))).toThrow(/does not own/i);
+ expect(() => assertServerContentSubtree(scope, root)).toThrow(/does not own/i);
+});
+
+test('missing paths retain their suffix when canonicalized through an existing alias', () => {
+ mkdirSync(join(root, 'real'));
+ symlinkSync(join(root, 'real'), join(root, 'alias'), 'junction');
+ expect(canonicalContentPath(join(root, 'alias', 'missing', 'doc.md'))).toBe(
+ join(root, 'real', 'missing', 'doc.md'),
+ );
+});
+
+test('scope paths use the native directory spelling, including missing descendants', () => {
+ const directory = join(root, 'ContentCase');
+ mkdirSync(directory);
+ const native = realpathSync.native(directory);
+ expect(snapshotServerContentScope(directory).path).toBe(native);
+ expect(canonicalContentPath(join(directory, 'missing', 'note.md'))).toBe(
+ join(native, 'missing', 'note.md'),
+ );
+});
diff --git a/packages/server/src/server-content-policy.ts b/packages/server/src/server-content-policy.ts
new file mode 100644
index 000000000..147ddbdb8
--- /dev/null
+++ b/packages/server/src/server-content-policy.ts
@@ -0,0 +1,142 @@
+import { readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { resolveExistingNativeAncestor } from './directory-root.ts';
+import { isProjectRoot } from './fs/find-project-root.ts';
+import { SymlinkEscapeError } from './fs-safety.ts';
+import { normalizeFsPath, tracedAtomicFs, tracedRenameSync } from './fs-traced.ts';
+import { errnoCode } from './http/handler-utils.ts';
+import { getLogger } from './logger.ts';
+import { assertProjectContentScope, NestedProjectScopeError } from './project-content-scope.ts';
+import { type ContentScope, contentScopeContainsPath } from './server-authority.ts';
+import { withSpanSync } from './telemetry.ts';
+
+export class ContentScopeAdmissionError extends Error {
+ constructor() {
+ super('This server does not own this content path. Open the project or file that owns it.');
+ this.name = 'ContentScopeAdmissionError';
+ }
+}
+
+export class ServerMutationShuttingDownError extends Error {
+ readonly problemType: 'urn:ok:error:auth-failed' | 'urn:ok:error:concurrent-operation';
+
+ constructor(authOperation: boolean) {
+ super('The server is shutting down.');
+ this.name = 'ServerMutationShuttingDownError';
+ this.problemType = authOperation
+ ? 'urn:ok:error:auth-failed'
+ : 'urn:ok:error:concurrent-operation';
+ }
+}
+
+export function contentScopedAtomicFs(assertPath: (path: string) => void): typeof tracedAtomicFs {
+ return {
+ writeFile: tracedAtomicFs.writeFile,
+ rename: async (from, to) => {
+ assertPath(to);
+ tracedRenameSync(from, to);
+ },
+ };
+}
+
+export function canonicalContentPath(path: string): string {
+ try {
+ const { ancestor, missingSegments } = resolveExistingNativeAncestor(path);
+ return resolve(ancestor, ...missingSegments);
+ } catch (error) {
+ if (errnoCode(error) === 'ELOOP') throw new SymlinkEscapeError('symlink cycle in path');
+ throw error;
+ }
+}
+
+export function snapshotServerContentScope(
+ contentDir: string,
+ singleDocRelPath?: string,
+): ContentScope {
+ return withSpanSync(
+ 'ok.boot.content-scope',
+ { attributes: { 'content.scope.kind': singleDocRelPath === undefined ? 'tree' : 'file' } },
+ (span) => {
+ const scope = scanServerContentScope(contentDir, singleDocRelPath);
+ span.setAttribute(
+ 'content.scope.exclusions',
+ scope.kind === 'tree' ? scope.excluded.length : 0,
+ );
+ return scope;
+ },
+ );
+}
+
+function scanServerContentScope(contentDir: string, singleDocRelPath?: string): ContentScope {
+ const root = canonicalContentPath(contentDir);
+ if (singleDocRelPath !== undefined) {
+ return { kind: 'file', path: canonicalContentPath(resolve(contentDir, singleDocRelPath)) };
+ }
+ const excluded: string[] = [];
+ const pending = [root];
+ while (pending.length > 0) {
+ const directory = pending.pop();
+ if (directory === undefined) break;
+ try {
+ for (const entry of readdirSync(directory, { withFileTypes: true })) {
+ if (!entry.isDirectory()) continue;
+ const child = join(directory, entry.name);
+ try {
+ if (isProjectRoot(child)) {
+ excluded.push(canonicalContentPath(child));
+ } else {
+ pending.push(child);
+ }
+ } catch (error) {
+ const code = errnoCode(error);
+ if (code !== 'ENOENT' && code !== 'ENOTDIR' && code !== 'EACCES' && code !== 'EPERM')
+ throw error;
+ getLogger('server-content-policy').warn(
+ { path: normalizeFsPath(child), code },
+ 'Unreadable nested-project marker remains in the parent authority scope',
+ );
+ }
+ }
+ } catch (error) {
+ const code = errnoCode(error);
+ if (code !== 'ENOENT' && code !== 'ENOTDIR' && code !== 'EACCES' && code !== 'EPERM') {
+ throw error;
+ }
+ if (code === 'EACCES' || code === 'EPERM')
+ getLogger('server-content-policy').warn(
+ { path: normalizeFsPath(directory), code },
+ 'Unreadable directory remains in the parent authority scope',
+ );
+ }
+ }
+ return { kind: 'tree', path: root, excluded };
+}
+
+export function assertCapturedServerContentPath(scope: ContentScope, path: string): string {
+ const canonical = canonicalContentPath(path);
+ if (scope.kind === 'file') {
+ if (!contentScopeContainsPath(scope, canonical)) throw new ContentScopeAdmissionError();
+ return canonical;
+ }
+ const excluded = scope.excluded.find((root) =>
+ contentScopeContainsPath({ kind: 'tree', path: root, excluded: [] }, canonical),
+ );
+ if (excluded !== undefined) throw new NestedProjectScopeError(excluded);
+ if (!contentScopeContainsPath(scope, canonical)) throw new ContentScopeAdmissionError();
+ return canonical;
+}
+
+export function assertServerContentPath(scope: ContentScope, path: string): void {
+ const canonical = assertCapturedServerContentPath(scope, path);
+ if (scope.kind === 'tree') assertProjectContentScope(canonical, scope.path);
+}
+
+export function assertServerContentSubtree(scope: ContentScope, path: string): void {
+ assertServerContentPath(scope, path);
+ if (scope.kind === 'file') throw new ContentScopeAdmissionError();
+ const canonical = canonicalContentPath(path);
+ const excluded = scope.excluded.find((root) =>
+ contentScopeContainsPath({ kind: 'tree', path: canonical, excluded: [] }, root),
+ );
+ if (excluded !== undefined) throw new NestedProjectScopeError(excluded);
+}
diff --git a/packages/server/src/server-factory.test.ts b/packages/server/src/server-factory.test.ts
index 78a7e1da8..c74498905 100644
--- a/packages/server/src/server-factory.test.ts
+++ b/packages/server/src/server-factory.test.ts
@@ -2482,7 +2482,7 @@ describe('createServer() server-lock integration (V0-1)', () => {
);
expect(() => createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true })).toThrow(
- /already running at port 9999/,
+ /content ownership is already held/,
);
writeFileSync(
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index c736639b8..30101878f 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -18,6 +18,7 @@ import {
DEFAULT_ATTACHMENT_FOLDER_PATH,
DEFAULT_LINKS_VALIDATION,
DEFAULT_LINTER_CONFIG,
+ DEFAULT_SIGTERM_GRACE_MS,
DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
DOCUMENT_OPEN_BYTE_LIMIT,
humanFormat,
@@ -103,7 +104,11 @@ import {
planDirectoryIndexRegenerations,
ROOT_INDEX_DOC_NAME,
} from './content/regenerate-index.ts';
-import { type ContentFilter, createContentFilter } from './content-filter.ts';
+import {
+ type ContentFilter,
+ createContentFilter,
+ isShareableOkArtifact,
+} from './content-filter.ts';
import { isWithinContentDir, safeContentPath } from './content-path.ts';
import { dropPendingDocs, recordContributor } from './contributor-tracker.ts';
import {
@@ -117,6 +122,7 @@ import {
docNameToRelativePath,
getDocExtension,
isRegisteredMarkdownDocName,
+ stripDocExtension,
} from './doc-extensions.ts';
import { runDocLineageGuard } from './doc-lineage-guard.ts';
import {
@@ -154,10 +160,9 @@ import {
startWatcher,
type WatcherHandle,
} from './file-watcher.ts';
-import { canonicalContentPathIsRefused } from './fs-safety.ts';
+import { canonicalContentPathIsRefused, SymlinkEscapeError } from './fs-safety.ts';
import {
normalizeFsPath,
- tracedAtomicFs,
tracedMkdirSync,
tracedUnlinkSync,
tracedWriteFileSync,
@@ -250,7 +255,28 @@ import {
setRenameLogIndex,
sweepLazyPopOrphans,
} from './rename-log.ts';
-import { acquireServerLock, markServerLockDraining, releaseServerLock } from './server-lock.ts';
+import {
+ acquireServerAuthority,
+ contentScopeContainsPath,
+ ServerAuthorityCollisionError,
+} from './server-authority.ts';
+import {
+ assertCapturedServerContentPath,
+ assertServerContentPath,
+ assertServerContentSubtree,
+ ContentScopeAdmissionError,
+ canonicalContentPath,
+ contentScopedAtomicFs,
+ ServerMutationShuttingDownError,
+ snapshotServerContentScope,
+} from './server-content-policy.ts';
+import {
+ acquireServerLock,
+ markServerLockDraining,
+ readServerLock,
+ releaseServerLock,
+ ServerLockCollisionError,
+} from './server-lock.ts';
import { createServerObserverExtension } from './server-observer-extension.ts';
import type { PairedWriteOrigin } from './server-observers.ts';
import {
@@ -286,6 +312,7 @@ import {
import { resyncRecordedSkillCopies } from './skill-placements.ts';
import { skillStateYamlPath } from './skill-state.ts';
import { assertCompatibleStateManifest } from './state-manifest.ts';
+import { assertRealpathWithinDir } from './symlink-guard.ts';
import { SyncEngine } from './sync-engine.ts';
import { createSyncHandshakeSpanExtension } from './sync-handshake-span-extension.ts';
import { initTelemetry, shutdownTelemetry, withSpan } from './telemetry.ts';
@@ -317,6 +344,7 @@ export interface ServerOptions {
shadowRepo?: ShadowHandle;
contentRoot?: string;
destroyTimeoutMs?: number;
+ authorityRegistryPath?: string;
onAgentWrite?: () => void;
localOpCliArgs?: string[];
authStreamHeartbeatMs?: number;
@@ -579,14 +607,22 @@ export function createServer(options: ServerOptions): ServerInstance {
const conflicts = new ConflictAuthority({
projectDir,
contentDir,
+ assertResolutionPath: assertConflictContentPath,
branch: initialBranch,
signal: { signal: (channel) => cc1Broadcaster?.signal(channel) },
io: {
gitRaw: async (args) =>
createGitInstance(projectDir, { credentialConfig: [], timeoutMs: 30_000 }).git.raw(args),
- writeProjectFileUntracked: (absPath, bytes) => tracedWriteFileSync(absPath, bytes, 'utf-8'),
- unlinkProjectFileUndeclared: (absPath) => tracedUnlinkSync(absPath),
+ writeProjectFileUntracked: (absPath, bytes) => {
+ assertConflictContentPath(absPath);
+ tracedWriteFileSync(absPath, bytes, 'utf-8');
+ },
+ unlinkProjectFileUndeclared: (absPath) => {
+ assertConflictContentPath(absPath);
+ tracedUnlinkSync(absPath);
+ },
deleteResolvedContent: (docName, absPath) => {
+ assertContentPath(absPath);
const declaration = registerRemoval(absPath);
try {
tracedUnlinkSync(absPath);
@@ -597,9 +633,10 @@ export function createServer(options: ServerOptions): ServerInstance {
contentFilter.decrementMdDir(dirname(docName));
},
applyResolvedContent: async (docName, absPath, bytes) => {
+ assertContentPath(absPath);
const absent = !existsSync(absPath);
registerWrite(absPath, contentHash(bytes));
- await atomicWriteFile(absPath, bytes, { fs: tracedAtomicFs });
+ await atomicWriteFile(absPath, bytes, { fs: scopedAtomicFs });
if (absent) contentFilter.incrementMdDir(dirname(docName));
if (hocuspocus.documents.get(docName)) applyToDoc(docName, bytes);
setReconciledBase(docName, bytes);
@@ -965,6 +1002,33 @@ export function createServer(options: ServerOptions): ServerInstance {
initTelemetry();
const serverInstanceId = randomUUID();
+ let authorityRetired = false;
+ let documentAdmissionClosed = false;
+ let authorityScope = snapshotServerContentScope(contentDir, singleDocRelPath);
+ const assertContentPath = (path: string): void => {
+ if (authorityRetired) throw new ServerMutationShuttingDownError(false);
+ assertServerContentPath(authorityScope, path);
+ };
+ const assertContentSubtree = (path: string): void => {
+ assertContentPath(path);
+ assertServerContentSubtree(authorityScope, path);
+ };
+ const scopedAtomicFs = contentScopedAtomicFs(assertContentPath);
+ function assertConflictContentPath(path: string): void {
+ assertRealpathWithinDir(path, projectDir, { allowShareableOkArtifact: isShareableOkArtifact });
+ const canonical = canonicalContentPath(path);
+ const projectPath = toPosix(relative(canonicalContentPath(projectDir), canonical));
+ if (
+ authorityScope.kind === 'tree' &&
+ !contentScopeContainsPath(
+ { kind: 'tree', path: authorityScope.path, excluded: [] },
+ canonical,
+ ) &&
+ isShareableOkArtifact(projectPath)
+ )
+ return;
+ assertContentPath(canonical);
+ }
const lockDir = getLocalDir(projectDir);
@@ -975,23 +1039,50 @@ export function createServer(options: ServerOptions): ServerInstance {
});
const acpPermissions = new AcpPermissionStore(lockDir, getLogger('acp-permissions'));
- acquireServerLock(lockDir, {
- port: 0,
- worktreeRoot: projectDir,
- kind: options.lockKind ?? 'interactive',
- capabilities: options.capabilities ?? ['http', 'ws'],
- });
-
- if (!skipStateManifestCheck) {
- try {
+ let authority: ReturnType<typeof acquireServerAuthority>;
+ try {
+ authority = acquireServerAuthority({
+ scope: authorityScope,
+ projectDir: canonicalContentPath(projectDir),
+ serverInstanceId,
+ registryPath: options.authorityRegistryPath,
+ });
+ } catch (error) {
+ if (
+ error instanceof ServerAuthorityCollisionError &&
+ error.existing.projectDir === canonicalContentPath(projectDir)
+ ) {
+ const existing = readServerLock(lockDir);
+ if (existing?.pid === error.existing.pid) {
+ throw new ServerLockCollisionError(existing, join(lockDir, 'server.lock'));
+ }
+ }
+ throw error;
+ }
+ authorityScope = authority.scope;
+ let primaryLockAcquired = false;
+ try {
+ acquireServerLock(lockDir, {
+ port: 0,
+ worktreeRoot: projectDir,
+ kind: options.lockKind ?? 'interactive',
+ capabilities: options.capabilities ?? ['http', 'ws'],
+ });
+ primaryLockAcquired = true;
+ if (!skipStateManifestCheck) {
assertCompatibleStateManifest({
lockDir,
shadowRepoDir: resolveShadowDir(projectDir),
});
- } catch (err) {
- releaseServerLock(lockDir);
- throw err;
}
+ } catch (error) {
+ if (primaryLockAcquired) releaseServerLock(lockDir);
+ try {
+ authority.release();
+ } catch (cleanupError) {
+ log.error({ err: cleanupError }, '[server] startup authority release failed');
+ }
+ throw error;
}
const basenameIndex: BasenameIndex = createBasenameIndex();
@@ -1086,6 +1177,7 @@ export function createServer(options: ServerOptions): ServerInstance {
resolveReady = res;
rejectReady = rej;
});
+ const offlineRemovalsReconciled = Promise.withResolvers<void>();
let resolveBranchScopeAligned!: () => void;
const branchScopeAligned = new Promise<void>((res) => {
@@ -1417,8 +1509,9 @@ export function createServer(options: ServerOptions): ServerInstance {
isConflict: (docName) => conflicts.has(docName),
getDocument: (docName) => hocuspocus.documents.get(docName),
writeDisk: async (absPath, markdown) => {
+ assertContentPath(absPath);
tracedMkdirSync(dirname(absPath), { recursive: true });
- await atomicWriteFile(absPath, markdown, { fs: tracedAtomicFs });
+ await atomicWriteFile(absPath, markdown, { fs: scopedAtomicFs });
},
registerWrite: (absPath, markdown) => registerWrite(absPath, contentHash(markdown)),
noteFileIndex: (event) =>
@@ -1589,6 +1682,7 @@ export function createServer(options: ServerOptions): ServerInstance {
const docName = indexDocNameFor(directory);
const absPath = resolve(contentDir, `${docName}.md`);
+ assertContentPath(absPath);
let currentMarkdown: string | null;
try {
currentMarkdown = readFileSync(absPath, 'utf-8');
@@ -1731,6 +1825,24 @@ export function createServer(options: ServerOptions): ServerInstance {
contentFilter = createContentFilter({
projectDir,
contentDir,
+ isContentScopeExcluded: (path) => {
+ if (authorityScope.kind !== 'tree') return false;
+ try {
+ const target = canonicalContentPath(path);
+ return authorityScope.excluded.some((root) =>
+ contentScopeContainsPath({ kind: 'tree', path: root, excluded: [] }, target),
+ );
+ } catch (err) {
+ const code = errnoCode(err);
+ if (!(err instanceof SymlinkEscapeError) && code !== 'EACCES' && code !== 'EPERM')
+ throw err;
+ log.warn(
+ { path: normalizeFsPath(path), code },
+ '[content-filter] scope path could not be inspected',
+ );
+ return true;
+ }
+ },
singleDocRelPath,
attachmentFolderPath: initialAttachmentFolderPath,
inPlaceSkillDirs: new Set(scanInPlaceSkills(contentDir).map((skill) => skill.dir)),
@@ -1816,6 +1928,7 @@ export function createServer(options: ServerOptions): ServerInstance {
let globalCopyResyncTimer: ReturnType<typeof setTimeout> | null = null;
const persistenceOpts: PersistenceOptions = {
contentDir,
+ assertContentPath,
projectDir,
conflicts,
lifecycleOf: (document, docName) => conflicts.lifecycleOf(document, docName),
@@ -1879,11 +1992,31 @@ export function createServer(options: ServerOptions): ServerInstance {
});
const openDirect = hocuspocus.openDirectConnection.bind(hocuspocus);
- hocuspocus.openDirectConnection = ((documentName: string, context?: unknown) =>
- openDirect(
- canonicalDocName(documentName),
- context,
- )) as typeof hocuspocus.openDirectConnection;
+ function assertDocumentProjectScope(documentName: string): void {
+ if (documentAdmissionClosed) throw new ServerMutationShuttingDownError(false);
+ if (isReservedForUserTree(documentName)) {
+ if (
+ singleDocRelPath !== undefined &&
+ documentName !== SYSTEM_DOC_NAME &&
+ !isConfigDoc(documentName)
+ )
+ throw new ContentScopeAdmissionError();
+ return;
+ }
+ if (
+ singleDocRelPath !== undefined &&
+ canonicalDocName(documentName) !== canonicalDocName(stripDocExtension(singleDocRelPath))
+ )
+ throw new ContentScopeAdmissionError();
+ if (authorityRetired) throw new ServerMutationShuttingDownError(false);
+ assertCapturedServerContentPath(authorityScope, safeContentPath(documentName, contentDir));
+ }
+
+ hocuspocus.openDirectConnection = (async (documentName: string, context?: unknown) => {
+ const canonicalName = canonicalDocName(documentName);
+ assertDocumentProjectScope(canonicalName);
+ return openDirect(canonicalName, context);
+ }) as typeof hocuspocus.openDirectConnection;
const hp = hocuspocus;
unregisterWorkloadProviders.push(
@@ -1980,7 +2113,10 @@ export function createServer(options: ServerOptions): ServerInstance {
agentFocusBroadcaster = new AgentFocusBroadcaster(hocuspocus);
agentPresenceBroadcaster = new AgentPresenceBroadcaster(hocuspocus);
- sessionManager = new AgentSessionManager(hocuspocus, options.agentSessionOptions);
+ sessionManager = new AgentSessionManager(hocuspocus, {
+ ...options.agentSessionOptions,
+ assertDocumentScope: assertDocumentProjectScope,
+ });
const sm = sessionManager;
unregisterWorkloadProviders.push(
registerAgentSessionCountsProvider(() => ({
@@ -2005,7 +2141,11 @@ export function createServer(options: ServerOptions): ServerInstance {
const principalAuthExtension: Extension & { __kind: 'principal-auth' } = {
__kind: 'principal-auth',
+ async beforeHandleMessage(payload) {
+ assertDocumentProjectScope(payload.documentName);
+ },
async onAuthenticate(payload) {
+ assertDocumentProjectScope(payload.documentName);
const tokenStr = payload.token;
const parsed = parseHocuspocusAuthToken(tokenStr);
@@ -2106,6 +2246,20 @@ export function createServer(options: ServerOptions): ServerInstance {
const removalRedirectGuard: Extension & { __kind: 'removal-redirect-guard' } = {
__kind: 'removal-redirect-guard',
async onAuthenticate(payload) {
+ if (!isReservedForUserTree(payload.documentName)) {
+ const path = resolveDocFilePath(payload.documentName);
+ if (path !== null && !existsSync(path)) {
+ try {
+ await Promise.race([offlineRemovalsReconciled.promise, ready]);
+ } catch (err) {
+ log.error(
+ { err, docName: payload.documentName },
+ '[removal-guard] missing-document admission refused after startup failure',
+ );
+ throw err;
+ }
+ }
+ }
await runRemovalRedirectGuard(payload.documentName, {
recentlyRemovedDocs,
resolveFilePath: resolveDocFilePath,
@@ -2151,6 +2305,8 @@ export function createServer(options: ServerOptions): ServerInstance {
sessionManager,
commentDocHooksRef,
contentDir,
+ assertContentPath,
+ assertContentSubtree,
getGeneratedIndexSettingsStatus,
setGeneratedIndexEnabled,
contentFilter,
@@ -2309,7 +2465,13 @@ export function createServer(options: ServerOptions): ServerInstance {
}
void stalenessWatchdog?.dispose();
stalenessWatchdog = null;
+ authorityRetired = true;
releaseServerLock(lockDir);
+ try {
+ authority.release();
+ } catch (cleanupError) {
+ log.error({ err: cleanupError }, '[server] construction authority release failed');
+ }
throw err;
}
@@ -2349,9 +2511,11 @@ export function createServer(options: ServerOptions): ServerInstance {
bridgeLossReporter,
);
- const rerenderDocsReferencingAssetBasename = (assetBasename: string): void => {
- if (!assetBasename) return;
- const needle = `[[${assetBasename}]]`;
+ const refreshLoadedEmbeds = (
+ needle: string,
+ context: { reason: 'startup' } | { reason: 'asset-event'; assetBasename: string },
+ ): number => {
+ let refreshed = 0;
for (const [docName] of hocuspocus.documents) {
if (isReservedForUserTree(docName)) continue;
const document = hocuspocus.documents.get(docName);
@@ -2362,13 +2526,31 @@ export function createServer(options: ServerOptions): ServerInstance {
document.transact(() => {
applyDiskContentToDoc(document, source, resolveEmbed, docName);
}, FILE_WATCHER_ORIGIN);
+ refreshed++;
} catch (err) {
log.error(
- { originalError: redactedErrorSummary(err), docName, assetBasename },
- `[asset-event] failed to re-render ${docName} for asset basename ${assetBasename}`,
+ { originalError: redactedErrorSummary(err), docName, ...context },
+ context.reason === 'asset-event'
+ ? `[asset-event] failed to re-render ${docName} for asset basename ${context.assetBasename}`
+ : `[basename-index] failed to refresh loaded startup embeds in ${docName}`,
);
}
}
+ return refreshed;
+ };
+
+ const rerenderDocsReferencingAssetBasename = (assetBasename: string): void => {
+ if (!assetBasename) return;
+ refreshLoadedEmbeds(`[[${assetBasename}]]`, { reason: 'asset-event', assetBasename });
+ };
+
+ const refreshStartupEmbeds = (): void => {
+ try {
+ const documentCount = refreshLoadedEmbeds('![[', { reason: 'startup' });
+ log.debug({ documentCount }, '[basename-index] refreshed loaded startup embeds');
+ } catch (err) {
+ log.warn({ err }, '[basename-index] loaded startup embed refresh failed');
+ }
};
let pendingAssetRerenderBasenames: Set<string> | null = null;
@@ -3235,12 +3417,37 @@ export function createServer(options: ServerOptions): ServerInstance {
inflightDestroy = (async () => {
const t0 = Date.now();
const phaseErrors: Array<{ phase: string; error: string }> = [];
+ const preludeDeadline = Date.now() + Math.min(destroyTimeoutMs, DEFAULT_SIGTERM_GRACE_MS / 5);
+ const preludeRemaining = () => Math.max(1, preludeDeadline - Date.now());
+ const joinPrelude = async <T>(operation: Promise<T>, phase: string): Promise<T> => {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ return await Promise.race([
+ operation,
+ new Promise<never>((_, reject) => {
+ timer = setTimeout(
+ () => reject(new Error(`${phase} did not retire before the pre-flush deadline`)),
+ preludeRemaining(),
+ );
+ }),
+ ]);
+ } finally {
+ clearTimeout(timer);
+ }
+ };
shutdownAllowsUnload = true;
const authShutdown = Promise.allSettled([shutdownLocalOps()]);
let authResult: PromiseSettledResult<void> | undefined;
+ try {
+ [authResult] = await joinPrelude(authShutdown, 'mutation-drain');
+ } catch (err) {
+ phaseErrors.push({ phase: 'mutation-drain', error: String(err) });
+ log.error({ err }, '[server] shutdown mutation drain failed');
+ }
+ documentAdmissionClosed = true;
try {
- await closeIndexRegeneration();
+ await joinPrelude(closeIndexRegeneration(), 'generated-index');
} catch (err) {
log.warn({ err }, '[index] generated index shutdown drain failed');
phaseErrors.push({ phase: 'generated-index-drain', error: String(err) });
@@ -3250,9 +3457,10 @@ export function createServer(options: ServerOptions): ServerInstance {
unregister();
}
try {
- await stalenessWatchdog?.dispose();
+ await joinPrelude(Promise.resolve(stalenessWatchdog?.dispose()), 'staleness-watchdog');
} catch (err) {
log.warn({ err }, '[server] staleness watchdog drain failed during destroy');
+ phaseErrors.push({ phase: 'staleness-watchdog-drain', error: String(err) });
}
stalenessWatchdog = null;
@@ -3265,7 +3473,7 @@ export function createServer(options: ServerOptions): ServerInstance {
maintenanceCoordinator?.destroy();
try {
- await closeShadowHousekeeping();
+ await joinPrelude(closeShadowHousekeeping(), 'shadow-housekeeping');
} catch (err) {
log.warn({ err }, '[shadow-housekeeping] shutdown drain failed');
phaseErrors.push({ phase: 'shadow-housekeeping-drain', error: String(err) });
@@ -3297,12 +3505,34 @@ export function createServer(options: ServerOptions): ServerInstance {
},
),
new Promise<'timeout'>((r) => {
- initTimeoutId = setTimeout(() => r('timeout'), 5_000);
+ initTimeoutId = setTimeout(() => r('timeout'), preludeRemaining());
}),
]);
if (initTimeoutId !== undefined) clearTimeout(initTimeoutId);
if (initSettled === 'timeout') {
- log.warn({}, '[server] init did not complete within 5s during shutdown');
+ log.warn({}, '[server] init did not complete before the pre-flush deadline');
+ phaseErrors.push({
+ phase: 'initialization-drain',
+ error: 'Initialization remains pending',
+ });
+ }
+
+ let loadDrainTimer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ await Promise.race([
+ Promise.allSettled(hocuspocus.loadingDocuments.values()),
+ new Promise<never>((_, reject) => {
+ loadDrainTimer = setTimeout(
+ () => reject(new Error('Pending document loads did not retire')),
+ preludeRemaining(),
+ );
+ }),
+ ]);
+ } catch (err) {
+ phaseErrors.push({ phase: 'document-load-drain', error: String(err) });
+ log.error({ err }, '[server] shutdown document load drain failed');
+ } finally {
+ clearTimeout(loadDrainTimer);
}
const documentCount = hocuspocus.documents.size;
@@ -3484,8 +3714,7 @@ export function createServer(options: ServerOptions): ServerInstance {
}
}
- [authResult] = await authShutdown;
- if (authResult.status === 'rejected') {
+ if (authResult?.status === 'rejected') {
const reason: unknown = authResult.reason;
const failures = reason instanceof AggregateError ? reason.errors : [reason];
phaseErrors.push({
@@ -3498,6 +3727,13 @@ export function createServer(options: ServerOptions): ServerInstance {
}
const durationMs = Date.now() - t0;
if (phaseErrors.length === 0) {
+ authorityRetired = true;
+ try {
+ authority.release();
+ } catch (err) {
+ phaseErrors.push({ phase: 'authority-release', error: String(err) });
+ log.error({ err }, '[server] shutdown authority release failed');
+ }
log.info(
{ documentCount, durationMs },
`[server] shutdown flushed ${documentCount} documents in ${durationMs}ms`,
@@ -3966,8 +4202,7 @@ export function createServer(options: ServerOptions): ServerInstance {
const indexesStartMono = performance.now();
try {
await withSpan('ok.boot.indexes', undefined, async () => {
- const { deletedDocNames, backlinkIndexDegraded } = await derivedIndexStartup.backlinksReady;
- if (backlinkIndexDegraded) degraded.push('backlink-index');
+ const deletedDocNames = await derivedIndexStartup.offlineDeletionsReady;
let tombstonedOffline = 0;
for (const deletedDocName of deletedDocNames) {
if (isReservedForUserTree(deletedDocName)) continue;
@@ -3981,6 +4216,9 @@ export function createServer(options: ServerOptions): ServerInstance {
'[removal-guard] tombstoned docs deleted while the server was down',
);
}
+ offlineRemovalsReconciled.resolve();
+ const { backlinkIndexDegraded } = await derivedIndexStartup.backlinksReady;
+ if (backlinkIndexDegraded) degraded.push('backlink-index');
const seedWalkStartMono = performance.now();
const HOST_SKILLS_EVENT_RE = /^\.(?!ok\/)[A-Za-z0-9_-]+\/skills\//;
let lastInPlaceDirs: ReadonlySet<string> = contentFilter
@@ -4130,6 +4368,7 @@ export function createServer(options: ServerOptions): ServerInstance {
} finally {
recordBootPhase('indexesMs', Math.round(performance.now() - indexesStartMono));
if (watcher) setBootField('fileCount', watcher.getFileIndex().size);
+ refreshStartupEmbeds();
}
try {
diff --git a/packages/server/src/services/assets.ts b/packages/server/src/services/assets.ts
index 35095eeb8..e3b164f33 100644
--- a/packages/server/src/services/assets.ts
+++ b/packages/server/src/services/assets.ts
@@ -95,6 +95,7 @@ export interface AssetService {
export interface AssetServiceDeps {
contentDir: string;
+ assertContentPath?: (path: string) => void;
isPathIgnored?: (relativePath: string) => boolean;
getAttachmentFolderPath?: () => string;
resolveTrackedFile?: (relativePath: string) => string | undefined;
@@ -213,6 +214,7 @@ export function createAssetService(deps: AssetServiceDeps): AssetService {
let canonicalPath: string;
try {
canonicalPath = realpathSync(requestedPath);
+ deps.assertContentPath?.(canonicalPath);
} catch (err) {
return { ok: false, reason: 'not-found', cause: err };
}
@@ -281,6 +283,7 @@ export function createAssetService(deps: AssetServiceDeps): AssetService {
}
try {
assertNoSymlinkEscape(destDir, resolvedContentDir);
+ deps.assertContentPath?.(destDir);
} catch (err) {
cleanupTempfile();
if (isContainmentRejection(err)) {
@@ -309,6 +312,7 @@ export function createAssetService(deps: AssetServiceDeps): AssetService {
try {
const realDestDir = realpathSync(destDir);
+ deps.assertContentPath?.(realDestDir);
let realContentDir: string;
try {
realContentDir = realpathSync(resolvedContentDir);
@@ -355,6 +359,12 @@ export function createAssetService(deps: AssetServiceDeps): AssetService {
if (DEFAULT_DEDUP_MODE === 'same-dir') {
const existing = await findDuplicateAsset(destDir, sha, byteLength);
if (existing) {
+ try {
+ deps.assertContentPath?.(resolve(destDir, existing));
+ } catch (cause) {
+ cleanupTempfile();
+ return { ok: false, kind: 'dest-validation-error', cause, destDir };
+ }
cleanupTempfile();
const relPath = toPosix(relative(deps.contentDir, resolve(destDir, existing)));
return {
@@ -384,6 +394,7 @@ export function createAssetService(deps: AssetServiceDeps): AssetService {
}
try {
+ deps.assertContentPath?.(resolve(destDir, finalFilename));
const destFilename = linkTempToFinalWithCollisionRetry(tempPath, destDir, finalFilename);
const relPath = toPosix(relative(deps.contentDir, resolve(destDir, destFilename)));
return {
@@ -394,6 +405,7 @@ export function createAssetService(deps: AssetServiceDeps): AssetService {
mime: detectedMime ?? null,
};
} catch (e) {
+ cleanupTempfile();
const reason: UploadWriteReason =
e instanceof UploadWriteError ? e.reason : 'urn:ok:error:storage-error';
return { ok: false, kind: 'write-failed', reason, cause: e, filename: finalFilename };
diff --git a/packages/server/src/services/file-ops.ts b/packages/server/src/services/file-ops.ts
index e2254ec45..7a3e9096c 100644
--- a/packages/server/src/services/file-ops.ts
+++ b/packages/server/src/services/file-ops.ts
@@ -15,6 +15,7 @@ import {
} from '../fs-traced.ts';
import { errnoCode } from '../http/handler-utils.ts';
import { getLogger } from '../logger.ts';
+import { assertProjectContentSubtree } from '../project-content-scope.ts';
export class DuplicateNameExhaustedError extends Error {
readonly sourcePath: string;
@@ -47,6 +48,7 @@ type DuplicatePathOutcome =
export interface FileOpsDeps {
contentDir: string;
+ assertContentSubtree?: (path: string) => void;
resolveContentEntryPath: (contentDir: string, kind: 'file' | 'folder', path: string) => string;
docNameForPath: (relPath: string) => string;
docNameToRelativePath: (docName: string) => string;
@@ -197,6 +199,11 @@ export function createFileOpsService(deps: FileOpsDeps): FileOpsService {
return { ok: false, kind: 'type-mismatch' };
}
+ if (operationKind === 'folder') {
+ assertProjectContentSubtree(targetPath, contentDir);
+ deps.assertContentSubtree?.(targetPath);
+ }
+
const deletedDocNames =
operationKind === 'asset'
? []
@@ -282,6 +289,11 @@ export function createFileOpsService(deps: FileOpsDeps): FileOpsService {
return { ok: false, kind: 'type-mismatch' };
}
+ if (kind === 'folder') {
+ assertProjectContentSubtree(sourcePath, contentDir);
+ deps.assertContentSubtree?.(sourcePath);
+ }
+
const sourceDocNames =
kind === 'file'
? [deps.docNameForPath(requestedPath)]
diff --git a/packages/server/src/shutdown-progress-refused.test.ts b/packages/server/src/shutdown-progress-refused.test.ts
index d21fd7d1e..ae9138421 100644
--- a/packages/server/src/shutdown-progress-refused.test.ts
+++ b/packages/server/src/shutdown-progress-refused.test.ts
@@ -51,7 +51,9 @@ async function withRefusedStoreShutdown(
pid: number | undefined;
signal: string | number | undefined;
}> = [];
+ const probe = process.kill.bind(process);
vi.spyOn(process, 'kill').mockImplementation((pid, signal) => {
+ if (signal === 0) return probe(pid, signal);
blockedSignalRequests.push({ pid, signal });
throw new Error('Test signal seam refuses delivery');
});
diff --git a/packages/server/src/shutdown-progress.test.ts b/packages/server/src/shutdown-progress.test.ts
index 548201147..71c054950 100644
--- a/packages/server/src/shutdown-progress.test.ts
+++ b/packages/server/src/shutdown-progress.test.ts
@@ -89,7 +89,9 @@ async function withLoadedDocuments(
pid: number | undefined;
signal: string | number | undefined;
}> = [];
+ const probe = process.kill.bind(process);
vi.spyOn(process, 'kill').mockImplementation((pid, signal) => {
+ if (signal === 0) return probe(pid, signal);
blockedSignalRequests.push({ pid, signal });
throw new Error('Test signal seam refuses delivery');
});
diff --git a/test-support/server-authority-registry.test-helper.ts b/test-support/server-authority-registry.test-helper.ts
new file mode 100644
index 000000000..707c7559e
--- /dev/null
+++ b/test-support/server-authority-registry.test-helper.ts
@@ -0,0 +1,8 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const directory = mkdtempSync(join(tmpdir(), 'ok-test-authority-'));
+export const testAuthorityRegistryPath = join(directory, 'authority.sqlite');
+
+process.once('exit', () => rmSync(directory, { recursive: true, force: true }));