Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdxindex 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 onWhen 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.mdxindex 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 clieFor 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.mdxindex 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.tsxindex 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<sexport 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.tsxindex 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 (<divref={wrapperRef}diff --git a/packages/app/src/editor/components/PropPanel.dom.test.tsx b/packages/app/src/editor/components/PropPanel.dom.test.tsxindex 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.tsxindex 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.tsindex 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): voidexport 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "إغلاق النافذة"diff --git a/packages/app/src/locales/bn/messages.json b/packages/app/src/locales/bn/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "উইন্ডো বন্ধ করুন"diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "Close window"diff --git a/packages/app/src/locales/es/messages.json b/packages/app/src/locales/es/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "Cerrar ventana"diff --git a/packages/app/src/locales/fr/messages.json b/packages/app/src/locales/fr/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "Fermer la fenêtre"diff --git a/packages/app/src/locales/hi/messages.json b/packages/app/src/locales/hi/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "विंडो बंद करें"diff --git a/packages/app/src/locales/id/messages.json b/packages/app/src/locales/id/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "Tutup jendela"diff --git a/packages/app/src/locales/ko/messages.json b/packages/app/src/locales/ko/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "창 닫기"diff --git a/packages/app/src/locales/pl/messages.json b/packages/app/src/locales/pl/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "Zamknij okno"diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr ""diff --git a/packages/app/src/locales/pt-BR/messages.json b/packages/app/src/locales/pt-BR/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "Fechar janela"diff --git a/packages/app/src/locales/ur/messages.json b/packages/app/src/locales/ur/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "ونڈو بند کریں"diff --git a/packages/app/src/locales/zh-Hans/messages.json b/packages/app/src/locales/zh-Hans/messages.jsonindex 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.poindex 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.tsxmsgid "Close window"msgstr "关闭窗口"diff --git a/packages/app/src/locales/zh-Hant/messages.json b/packages/app/src/locales/zh-Hant/messages.jsonindex 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.poindex 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.tsxmsgid "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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, docNameawait 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.tsindex 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.tsindex 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 withawait 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 withconst 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 withconst 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 = {}): Pconst 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.tsindex 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   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(' ');diff --git a/packages/cli/src/commands/removal-plan.test.ts b/packages/cli/src/commands/removal-plan.test.tsindex 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.tsindex 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.tsindex 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: StartCommandOptioprocess.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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): Promopts.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.tsnew file mode 100644index 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.tsindex 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): strinif (!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.tsindex 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.tsindex 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 DerivedDocumentIndexthis.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 DerivedDocumentIndexthis.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.tsindex 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, writeFileSynimport { 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.tsindex 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.tsindex 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.tsindex 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): Attribreturn 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.tsindex 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<Nativeresolve(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.tsindex 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): ApiRequestPitry {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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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): DeferredStoreErrorClasexport 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): Persisconst mermaidLkgCache = new Map<string, string>();const mermaidPersistenceCtx: MermaidPersistenceCtx = {+ assertContentPath: options?.assertContentPath,contentDir,lkgCache: mermaidLkgCache,};@@ -1589,7 +1592,18 @@ export function createPersistenceExtension(options?: PersistenceOptions): PersisinFlightFlushValue = 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): Persisreturn;}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): PersisloadManagedArtifactDoc(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): PersisisExcalidrawDoc(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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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 }));