@openfairygui/backend 0.3.0 → 0.3.1

package/README.md

@@ -10,7 +10,7 @@ It owns:
 
 - project/session lifecycle
 - revisioned request handling
-- coordinated but non-atomic save semantics
+- coordinated save semantics, with atomic staged directory swaps on the Node adapter
 - browser-safe project sessions
 - browser-safe async project storage adapter
 - adapter-backed file sessions and backend-local session locking
@@ -39,7 +39,9 @@ and browser editors can inject an async storage adapter for OPFS, IndexedDB, ZIP
 or File System Access API bridges. Storage adapters must implement `unlink()` so resource rename/move/remove
 can clean up stale source files. Existing browser projects use a session-lifetime Web Lock: a live peer tab
 receives `lock_conflict`, while reload or abrupt document termination releases ownership without leaving a
-persistent `.openfairygui.backend.lock` marker. When Web Locks are unavailable, the storage adapter must
+persistent `.openfairygui.backend.lock` marker. The Node adapter instead keeps a token-protected lock beside
+the project directory, recovers only valid same-host stale ownership, and rejects project-directory symbolic
+links. When Web Locks are unavailable, the storage adapter must
 provide `acquireSessionLock()` with the same atomic cross-context and owner-termination semantics. The default
 Node filesystem/runtime lives under `@openfairygui/backend/node` and retains its advisory lock file behavior.
 Adapter-backed `openSession` hydrates primary resource bytes so browser-safe transactions can rename/move

package/dist/index.cjs

@@ -42,6 +42,16 @@ function createRuntimePathPolicy() {
 		workspaceBoundary: "project-root-only"
 	};
 }
+async function assertProjectPathContained(fileSystem, projectRoot, targetPath) {
+	const [resolvedRoot, resolvedTarget] = await Promise.all([fileSystem.resolvePath(projectRoot), fileSystem.resolvePath(targetPath)]);
+	const root = normalizeComparablePath(resolvedRoot);
+	const target = normalizeComparablePath(resolvedTarget);
+	if (root === "." && !target.startsWith("/") && !/^[a-z]:\//i.test(target)) return;
+	if (target === root || target.startsWith(`${root}/`)) return;
+	const error = /* @__PURE__ */ new Error(`Project path escapes the opened root: ${targetPath}`);
+	error.code = "EACCES";
+	throw error;
+}
 async function resolveFairyPath(fileSystem, input) {
 	const resolvedInput = fileSystem.resolve(input);
 	const stat = await fileSystem.stat(resolvedInput);
@@ -122,10 +132,14 @@ function failure(stage, startedAt, error, session, options) {
 }
 //#endregion
 //#region src/services/session-project-writer.ts
-function createWriterFileSystem(fileSystem, writtenPaths, failedPaths) {
+function createWriterFileSystem(fileSystem, projectRoot, writtenPaths, failedPaths) {
+	const contained = async (targetPath, operation) => {
+		await assertProjectPathContained(fileSystem, projectRoot, targetPath);
+		return operation();
+	};
 	async function trackWrite(targetPath, write) {
 		try {
-			const result = await write();
+			const result = await contained(targetPath, write);
 			writtenPaths.push(targetPath);
 			return result;
 		} catch (error) {
@@ -134,8 +148,8 @@ function createWriterFileSystem(fileSystem, writtenPaths, failedPaths) {
 		}
 	}
 	return {
-		readFile: (path) => fileSystem.readFile(path),
-		readFileRaw: (path) => fileSystem.readFileRaw(path),
+		readFile: (path) => contained(path, () => fileSystem.readFile(path)),
+		readFileRaw: (path) => contained(path, () => fileSystem.readFileRaw(path)),
 		writeFile: (path, content) => trackWrite(path, async () => {
 			await fileSystem.mkdir(fileSystem.dirname(path), { recursive: true });
 			await fileSystem.writeFile(path, content);
@@ -144,9 +158,10 @@ function createWriterFileSystem(fileSystem, writtenPaths, failedPaths) {
 			await fileSystem.mkdir(fileSystem.dirname(path), { recursive: true });
 			await fileSystem.writeFileRaw(path, data);
 		}),
-		mkdir: (path) => fileSystem.mkdir(path, { recursive: true }),
-		readdir: (path) => fileSystem.readdir(path),
+		mkdir: (path) => contained(path, () => fileSystem.mkdir(path, { recursive: true })),
+		readdir: (path) => contained(path, () => fileSystem.readdir(path)),
 		async exists(path) {
+			await assertProjectPathContained(fileSystem, projectRoot, path);
 			try {
 				await fileSystem.stat(path);
 				return true;
@@ -161,11 +176,21 @@ function createWriterFileSystem(fileSystem, writtenPaths, failedPaths) {
 	};
 }
 async function writeSessionProject(input) {
-	await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(input.fileSystem, input.writtenPaths, input.failedPaths)).write(input.document, input.fairyPath, {
-		staleSourceFiles: input.staleSourceFiles,
-		staleResourceFolders: input.staleResourceFolders,
-		staleBranchDirectories: input.staleBranchDirectories
-	});
+	const projectRoot = input.fileSystem.dirname(input.fairyPath);
+	const write = async (fileSystem) => {
+		await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(fileSystem, projectRoot, input.writtenPaths, input.failedPaths)).write(input.document, input.fairyPath, {
+			staleSourceFiles: input.staleSourceFiles,
+			staleResourceFolders: input.staleResourceFolders,
+			staleBranchDirectories: input.staleBranchDirectories
+		});
+	};
+	if (!input.fileSystem.runProjectWriteTransaction) return write(input.fileSystem);
+	try {
+		await input.fileSystem.runProjectWriteTransaction(projectRoot, write);
+	} catch (error) {
+		input.writtenPaths.length = 0;
+		throw error;
+	}
 }
 //#endregion
 //#region src/services/session-utils.ts
@@ -479,7 +504,7 @@ var AuthoringService = class {
 				lastSavedRevision: session.lastSavedRevision,
 				committedPaths,
 				failedPaths,
-				diskMayBePartiallyUpdated: true
+				diskMayBePartiallyUpdated: !fileSystem.runProjectWriteTransaction
 			}, toSessionSnapshot(session, this.context.capabilities), {
 				sessionId: session.sessionId,
 				revision: session.revision
@@ -654,7 +679,7 @@ var AuthoringService = class {
 				failedPaths,
 				skippedPaths,
 				diagnostics: diagnosticsFromError,
-				diskMayBePartiallyUpdated: true
+				diskMayBePartiallyUpdated: !fileSystem.runProjectWriteTransaction
 			}, toSessionSnapshot(session, this.context.capabilities), {
 				sessionId: session.sessionId,
 				revision: session.revision,
@@ -1143,7 +1168,7 @@ var ReadService = class {
 //#endregion
 //#region src/services/runtime-service.ts
 function randomId() {
-	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+	return crypto.randomUUID();
 }
 function createCapabilityUnavailableError(capability) {
 	const artifactCapability = capability === "artifact.publish" || capability === "artifact.restore";
@@ -1156,29 +1181,33 @@ function createCapabilityUnavailableError(capability) {
 		bridgeBoundary: artifactCapability ? "external-bridge" : void 0
 	};
 }
-function createProjectReaderFileSystem(fileSystem) {
+function createProjectReaderFileSystem(fileSystem, projectRoot) {
+	const contained = async (filePath, operation) => {
+		await assertProjectPathContained(fileSystem, projectRoot, filePath);
+		return operation();
+	};
 	return {
 		readFile(filePath) {
-			return fileSystem.readFile(filePath);
+			return contained(filePath, () => fileSystem.readFile(filePath));
 		},
 		readFileRaw(filePath) {
-			return fileSystem.readFileRaw(filePath);
+			return contained(filePath, () => fileSystem.readFileRaw(filePath));
 		},
 		writeFile(filePath, content) {
-			return fileSystem.writeFile(filePath, content);
+			return contained(filePath, () => fileSystem.writeFile(filePath, content));
 		},
 		writeFileRaw(filePath, data) {
-			return fileSystem.writeFileRaw(filePath, data);
+			return contained(filePath, () => fileSystem.writeFileRaw(filePath, data));
 		},
 		async mkdir(dirPath) {
-			await fileSystem.mkdir(dirPath, { recursive: true });
+			await contained(dirPath, () => fileSystem.mkdir(dirPath, { recursive: true }));
 		},
 		readdir(dirPath) {
-			return fileSystem.readdir(dirPath);
+			return contained(dirPath, () => fileSystem.readdir(dirPath));
 		},
 		async exists(filePath) {
 			try {
-				await fileSystem.stat(filePath);
+				await contained(filePath, () => fileSystem.stat(filePath));
 				return true;
 			} catch {
 				return false;
@@ -1272,9 +1301,25 @@ var RuntimeService = class {
 		const startedAt = Date.now();
 		if (!this.context.fileSystem) return failure("runtime", startedAt, createCapabilityUnavailableError("fileSystem"));
 		const fileSystem = this.context.fileSystem;
+		if (this.context.allowedProjectRoots?.length) {
+			let allowed = false;
+			for (const root of this.context.allowedProjectRoots) try {
+				await assertProjectPathContained(fileSystem, root, input.projectPath);
+				allowed = true;
+				break;
+			} catch (error) {
+				if (error.code !== "EACCES") throw error;
+			}
+			if (!allowed) return failure("runtime", startedAt, {
+				code: "project_root_not_allowed",
+				message: "Project path is outside the configured allowed roots.",
+				projectPath: input.projectPath
+			});
+		}
 		const { fairyPath, canonicalProjectPath, canonicalPathKey } = await resolveCanonicalProjectRoot(fileSystem, input.projectPath);
+		await fileSystem.validateProjectRoot?.(canonicalProjectPath);
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
-		const lockFilePath = fileSystem.join(canonicalProjectPath, ".openfairygui.backend.lock");
+		const lockFilePath = fileSystem.getSessionLockPath?.(canonicalProjectPath) ?? fileSystem.join(canonicalProjectPath, ".openfairygui.backend.lock");
 		if (existingSessionId) return failure("runtime", startedAt, {
 			code: "lock_conflict",
 			kind: "in_process_session_exists",
@@ -1294,7 +1339,7 @@ var RuntimeService = class {
 				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 				canonicalPathKey
 			}));
-			const read = await new _openfairygui_core_project_io.ProjectReader(createProjectReaderFileSystem(fileSystem)).readDetailed(fairyPath, { hydrateResourceBytes: true });
+			const read = await new _openfairygui_core_project_io.ProjectReader(createProjectReaderFileSystem(fileSystem, canonicalProjectPath)).readDetailed(fairyPath, { hydrateResourceBytes: true });
 			if (!read.document) throw new Error(read.diagnostics[0]?.message ?? `Unable to read project: ${fairyPath}`);
 			const document = read.document;
 			const project = (0, _openfairygui_core_uam.liftDocumentToUamProject)(document);
@@ -1352,6 +1397,11 @@ var RuntimeService = class {
 	openProjectSession(input) {
 		const startedAt = Date.now();
 		const sessionId = input.sessionId ?? randomId();
+		if (this.context.sessions.has(sessionId)) return failure("runtime", startedAt, {
+			code: "session_id_conflict",
+			message: `Session id is already in use: ${sessionId}`,
+			sessionId
+		});
 		const storage = input.storage;
 		const memoryProjectPath = `memory://${sessionId}`;
 		const canonicalProjectPath = storage?.canonicalProjectPath ?? input.canonicalProjectPath ?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || "." : memoryProjectPath);
@@ -1478,7 +1528,7 @@ const ARTIFACT_BRIDGE_CAPABILITY = {
 	bridgeEntrypoint: "@openfairygui/backend/node",
 	reason: "publish/restore require explicit Node-hosted filesystem and artifact execution."
 };
-function createCapabilities() {
+function createCapabilities(atomicSave = false) {
 	return {
 		contractVersion: BACKEND_CONTRACT_VERSION,
 		capabilitySchemaVersion: 3,
@@ -1550,7 +1600,7 @@ function createCapabilities() {
 			sessionRuntime: true,
 			advisoryLocking: true,
 			coordinatedSave: true,
-			atomicSave: false,
+			atomicSave,
 			staleRevisionProtection: true,
 			pathPolicy: createRuntimePathPolicy(),
 			events: {
@@ -1596,10 +1646,11 @@ var BackendRuntime = class {
 	jobService;
 	constructor(options = {}) {
 		this.fileSystem = options.fileSystem;
-		this.capabilities = createCapabilities();
+		this.capabilities = createCapabilities(Boolean(options.fileSystem?.runProjectWriteTransaction));
 		this.context = {
 			fileSystem: this.fileSystem,
 			host: options.host,
+			allowedProjectRoots: options.allowedProjectRoots,
 			capabilities: this.capabilities,
 			sessions: this.sessions,
 			sessionsByPath: this.sessionsByPath,
@@ -1622,7 +1673,16 @@ var BackendRuntime = class {
 		return this.readService.getCapabilities();
 	}
 	async openSession(input) {
-		return this.runtimeService.openSession(input);
+		const startedAt = Date.now();
+		try {
+			return await this.runtimeService.openSession(input);
+		} catch {
+			return failure("runtime", startedAt, {
+				code: "project_open_failed",
+				message: "Unable to open project.",
+				projectPath: input.projectPath
+			});
+		}
 	}
 	openProjectSession(input) {
 		return this.runtimeService.openProjectSession(input);
@@ -1646,7 +1706,7 @@ var BackendRuntime = class {
 		return this.authoringService.materializeSession(input);
 	}
 	async closeSession(input) {
-		return this.runtimeService.closeSession(input);
+		return this.authoringService.runSessionExclusive(input.sessionId, () => this.runtimeService.closeSession(input));
 	}
 	getEvents(input) {
 		return this.eventService.getEvents(input);

package/dist/index.d.cts

@@ -73,6 +73,12 @@ interface BackendFileSystem {
     recursive?: boolean;
   }): Promise<void>;
   resolvePath(filePath: string): Promise<string>;
+  /** Optional host validation before a project is read. Node rejects links anywhere in the project tree. */
+  validateProjectRoot?(projectRoot: string): Promise<void>;
+  /** Optional host-specific lock location. Node keeps it beside the project so directory swaps do not move it. */
+  getSessionLockPath?(canonicalProjectPath: string): string;
+  /** Runs project writes against a staged copy and commits them as one directory swap. */
+  runProjectWriteTransaction?(projectRoot: string, write: (stagedFileSystem: BackendFileSystem) => Promise<void>): Promise<void>;
   acquireSessionLock(lockPath: string): Promise<BackendSessionLock>;
   unlink(filePath: string): Promise<void>;
   rmdir(dirPath: string): Promise<void>;
@@ -164,7 +170,7 @@ interface BackendCapabilities {
     sessionRuntime: true;
     advisoryLocking: true;
     coordinatedSave: true;
-    atomicSave: false;
+    atomicSave: boolean;
     staleRevisionProtection: true;
     pathPolicy: {
       canonicalization: 'realpath+normalized-casefold';
@@ -298,6 +304,11 @@ interface AdvisoryLockConflictError {
   holderSessionId?: string;
   lockFilePath: string;
 }
+interface SessionIdConflictError {
+  code: 'session_id_conflict';
+  message: string;
+  sessionId: string;
+}
 interface SavePartialFailureError {
   code: 'save_partial_failure';
   message: string;
@@ -307,7 +318,7 @@ interface SavePartialFailureError {
   lastSavedRevision: number;
   committedPaths: string[];
   failedPaths: string[];
-  diskMayBePartiallyUpdated: true;
+  diskMayBePartiallyUpdated: boolean;
 }
 interface UamFidelityUnsupportedError {
   code: 'uam_fidelity_unsupported';
@@ -334,7 +345,7 @@ interface MaterializeWriteFailedError {
   failedPaths: string[];
   skippedPaths: string[];
   diagnostics: BackendDiagnostic[];
-  diskMayBePartiallyUpdated: true;
+  diskMayBePartiallyUpdated: boolean;
 }
 type BackendEventKind = 'session.opened' | 'transaction.applied' | 'transaction.rejected' | 'save.started' | 'save.completed' | 'save.failed' | 'session.closeRequested' | 'session.closed' | 'cache.invalidated' | 'cache.updated' | 'job.created' | 'job.started' | 'job.progress' | 'job.cancelRequested' | 'job.cancelled' | 'job.completed' | 'job.failed';
 interface BackendEvent {
@@ -467,7 +478,17 @@ interface RefreshCacheInput {
   sessionId: string;
   reason?: 'manual' | 'session_open' | 'after_save';
 }
-type BackendError = SessionNotFoundError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ApplyUamTransactionAppError;
+type BackendError = SessionNotFoundError | SessionIdConflictError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ProjectRootNotAllowedError | ProjectOpenFailedError | ApplyUamTransactionAppError;
+interface ProjectRootNotAllowedError {
+  code: 'project_root_not_allowed';
+  message: string;
+  projectPath: string;
+}
+interface ProjectOpenFailedError {
+  code: 'project_open_failed';
+  message: string;
+  projectPath: string;
+}
 interface ApplySessionTransactionInput {
   sessionId: string;
   expectedRevision: number;
@@ -514,6 +535,8 @@ interface MaterializeSessionInput {
 interface BackendRuntimeOptions {
   fileSystem?: BackendFileSystem;
   host?: BackendHostAdapter;
+  /** Canonical filesystem roots available to file-backed sessions. Omit for unrestricted library use. */
+  allowedProjectRoots?: readonly string[];
 }
 //#endregion
 //#region src/runtime.d.ts
@@ -537,8 +560,8 @@ declare class BackendRuntime {
   getCapabilities(): BackendSuccess<BackendCapabilities>;
   openSession(input: {
     projectPath: string;
-  }): Promise<BackendResult<BackendSessionSnapshot, InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError>>;
-  openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot>;
+  }): Promise<BackendResult<BackendSessionSnapshot, InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError | ProjectRootNotAllowedError | ProjectOpenFailedError>>;
+  openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot, InProcessLockConflictError | SessionIdConflictError>;
   getSession(input: {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
@@ -596,4 +619,4 @@ interface BackendAsyncStorageAdapter {
 type BackendStorageFileSystem = BackendFileSystem & FileSystem;
 declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
 //#endregion
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectOutline, type BackendProjectOutlinePackage, type BackendProjectOutlineResource, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type GetProjectOutlineInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, type UamFidelityUnsupportedError, type ValidateSessionInput, createBackendStorageFileSystem };
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectOutline, type BackendProjectOutlinePackage, type BackendProjectOutlineResource, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type GetProjectOutlineInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type ProjectOpenFailedError, type ProjectRootNotAllowedError, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionIdConflictError, type SessionNotFoundError, type SessionStaleWriteError, type UamFidelityUnsupportedError, type ValidateSessionInput, createBackendStorageFileSystem };

package/dist/index.d.mts

@@ -73,6 +73,12 @@ interface BackendFileSystem {
     recursive?: boolean;
   }): Promise<void>;
   resolvePath(filePath: string): Promise<string>;
+  /** Optional host validation before a project is read. Node rejects links anywhere in the project tree. */
+  validateProjectRoot?(projectRoot: string): Promise<void>;
+  /** Optional host-specific lock location. Node keeps it beside the project so directory swaps do not move it. */
+  getSessionLockPath?(canonicalProjectPath: string): string;
+  /** Runs project writes against a staged copy and commits them as one directory swap. */
+  runProjectWriteTransaction?(projectRoot: string, write: (stagedFileSystem: BackendFileSystem) => Promise<void>): Promise<void>;
   acquireSessionLock(lockPath: string): Promise<BackendSessionLock>;
   unlink(filePath: string): Promise<void>;
   rmdir(dirPath: string): Promise<void>;
@@ -164,7 +170,7 @@ interface BackendCapabilities {
     sessionRuntime: true;
     advisoryLocking: true;
     coordinatedSave: true;
-    atomicSave: false;
+    atomicSave: boolean;
     staleRevisionProtection: true;
     pathPolicy: {
       canonicalization: 'realpath+normalized-casefold';
@@ -298,6 +304,11 @@ interface AdvisoryLockConflictError {
   holderSessionId?: string;
   lockFilePath: string;
 }
+interface SessionIdConflictError {
+  code: 'session_id_conflict';
+  message: string;
+  sessionId: string;
+}
 interface SavePartialFailureError {
   code: 'save_partial_failure';
   message: string;
@@ -307,7 +318,7 @@ interface SavePartialFailureError {
   lastSavedRevision: number;
   committedPaths: string[];
   failedPaths: string[];
-  diskMayBePartiallyUpdated: true;
+  diskMayBePartiallyUpdated: boolean;
 }
 interface UamFidelityUnsupportedError {
   code: 'uam_fidelity_unsupported';
@@ -334,7 +345,7 @@ interface MaterializeWriteFailedError {
   failedPaths: string[];
   skippedPaths: string[];
   diagnostics: BackendDiagnostic[];
-  diskMayBePartiallyUpdated: true;
+  diskMayBePartiallyUpdated: boolean;
 }
 type BackendEventKind = 'session.opened' | 'transaction.applied' | 'transaction.rejected' | 'save.started' | 'save.completed' | 'save.failed' | 'session.closeRequested' | 'session.closed' | 'cache.invalidated' | 'cache.updated' | 'job.created' | 'job.started' | 'job.progress' | 'job.cancelRequested' | 'job.cancelled' | 'job.completed' | 'job.failed';
 interface BackendEvent {
@@ -467,7 +478,17 @@ interface RefreshCacheInput {
   sessionId: string;
   reason?: 'manual' | 'session_open' | 'after_save';
 }
-type BackendError = SessionNotFoundError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ApplyUamTransactionAppError;
+type BackendError = SessionNotFoundError | SessionIdConflictError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ProjectRootNotAllowedError | ProjectOpenFailedError | ApplyUamTransactionAppError;
+interface ProjectRootNotAllowedError {
+  code: 'project_root_not_allowed';
+  message: string;
+  projectPath: string;
+}
+interface ProjectOpenFailedError {
+  code: 'project_open_failed';
+  message: string;
+  projectPath: string;
+}
 interface ApplySessionTransactionInput {
   sessionId: string;
   expectedRevision: number;
@@ -514,6 +535,8 @@ interface MaterializeSessionInput {
 interface BackendRuntimeOptions {
   fileSystem?: BackendFileSystem;
   host?: BackendHostAdapter;
+  /** Canonical filesystem roots available to file-backed sessions. Omit for unrestricted library use. */
+  allowedProjectRoots?: readonly string[];
 }
 //#endregion
 //#region src/runtime.d.ts
@@ -537,8 +560,8 @@ declare class BackendRuntime {
   getCapabilities(): BackendSuccess<BackendCapabilities>;
   openSession(input: {
     projectPath: string;
-  }): Promise<BackendResult<BackendSessionSnapshot, InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError>>;
-  openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot>;
+  }): Promise<BackendResult<BackendSessionSnapshot, InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError | ProjectRootNotAllowedError | ProjectOpenFailedError>>;
+  openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot, InProcessLockConflictError | SessionIdConflictError>;
   getSession(input: {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
@@ -596,4 +619,4 @@ interface BackendAsyncStorageAdapter {
 type BackendStorageFileSystem = BackendFileSystem & FileSystem;
 declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
 //#endregion
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectOutline, type BackendProjectOutlinePackage, type BackendProjectOutlineResource, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type GetProjectOutlineInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, type UamFidelityUnsupportedError, type ValidateSessionInput, createBackendStorageFileSystem };
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectOutline, type BackendProjectOutlinePackage, type BackendProjectOutlineResource, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type GetProjectOutlineInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type ProjectOpenFailedError, type ProjectRootNotAllowedError, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionIdConflictError, type SessionNotFoundError, type SessionStaleWriteError, type UamFidelityUnsupportedError, type ValidateSessionInput, createBackendStorageFileSystem };