@openfairygui/backend 0.3.0 → 0.3.1

package/dist/node.d.mts

@@ -72,6 +72,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>;
@@ -163,7 +169,7 @@ interface BackendCapabilities {
     sessionRuntime: true;
     advisoryLocking: true;
     coordinatedSave: true;
-    atomicSave: false;
+    atomicSave: boolean;
     staleRevisionProtection: true;
     pathPolicy: {
       canonicalization: 'realpath+normalized-casefold';
@@ -297,6 +303,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;
@@ -306,7 +317,7 @@ interface SavePartialFailureError {
   lastSavedRevision: number;
   committedPaths: string[];
   failedPaths: string[];
-  diskMayBePartiallyUpdated: true;
+  diskMayBePartiallyUpdated: boolean;
 }
 interface UamFidelityUnsupportedError {
   code: 'uam_fidelity_unsupported';
@@ -333,7 +344,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 {
@@ -465,7 +476,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;
@@ -512,6 +533,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
@@ -535,8 +558,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>;

package/dist/node.mjs

@@ -1,5 +1,7 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { UAM_SUPPORTED_MATERIALIZATION_SCOPE, UAM_SUPPORTED_TRANSACTION_SCOPE, commitUamProjectSourcePaths, liftDocumentToUamProject, materializeUamProject, normalizeUamProject, staleBranchDirectories, staleResourceFolders, staleSourceFiles, validateUamProject } from "@openfairygui/core/uam";
 import { applyUamTransactionAppAsync } from "@openfairygui/functions/uam";
 import { ProjectReader, ProjectWriter } from "@openfairygui/core/project-io";
@@ -34,6 +36,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 +134,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 +150,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 +160,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 +178,21 @@ function createWriterFileSystem(fileSystem, writtenPaths, failedPaths) {
 	};
 }
 async function writeSessionProject(input) {
-	await new 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 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 +506,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 +681,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 +1170,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 +1183,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 +1303,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 +1341,7 @@ var RuntimeService = class {
 				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 				canonicalPathKey
 			}));
-			const read = await new ProjectReader(createProjectReaderFileSystem(fileSystem)).readDetailed(fairyPath, { hydrateResourceBytes: true });
+			const read = await new 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 = liftDocumentToUamProject(document);
@@ -1352,6 +1399,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 +1530,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 +1602,7 @@ function createCapabilities() {
 			sessionRuntime: true,
 			advisoryLocking: true,
 			coordinatedSave: true,
-			atomicSave: false,
+			atomicSave,
 			staleRevisionProtection: true,
 			pathPolicy: createRuntimePathPolicy(),
 			events: {
@@ -1596,10 +1648,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 +1675,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 +1708,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);
@@ -1669,13 +1731,161 @@ var BackendRuntime = class {
 };
 //#endregion
 //#region src/node.ts
+const PROCESS_START_TIME = Math.trunc(Date.now() - process.uptime() * 1e3);
+function parseLockMetadata(content) {
+	try {
+		const value = JSON.parse(content);
+		if (value.schemaVersion !== 1 || !Number.isSafeInteger(value.pid) || !Number.isFinite(value.processStartTime) || typeof value.hostname !== "string" || typeof value.token !== "string") return null;
+		return value;
+	} catch {
+		return null;
+	}
+}
+function isProcessAlive(metadata) {
+	if (metadata.hostname !== os.hostname()) return true;
+	if (metadata.pid === process.pid) return Math.abs(metadata.processStartTime - PROCESS_START_TIME) < 1e3;
+	try {
+		process.kill(metadata.pid, 0);
+		return true;
+	} catch (error) {
+		return error.code !== "ESRCH";
+	}
+}
+async function recoverStaleLock(filePath) {
+	let before;
+	try {
+		before = await fs.readFile(filePath, "utf-8");
+	} catch {
+		return false;
+	}
+	const metadata = parseLockMetadata(before);
+	if (!metadata || isProcessAlive(metadata)) return false;
+	const current = parseLockMetadata(await fs.readFile(filePath, "utf-8").catch(() => ""));
+	if (!current || current.token !== metadata.token) return false;
+	await fs.unlink(filePath);
+	return true;
+}
+async function resolvePathThroughExistingAncestor(filePath) {
+	const missing = [];
+	let candidate = path.resolve(filePath);
+	for (;;) try {
+		const resolved = await fs.realpath(candidate);
+		return path.join(resolved, ...missing);
+	} catch (error) {
+		const code = error.code;
+		if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+		const parent = path.dirname(candidate);
+		if (parent === candidate) return path.resolve(filePath);
+		missing.unshift(path.basename(candidate));
+		candidate = parent;
+	}
+}
+async function pathExists(filePath) {
+	return fs.stat(filePath).then(() => true, (error) => {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	});
+}
+async function assertNoSymlinks(dirPath) {
+	for (const entry of await fs.readdir(dirPath, { withFileTypes: true })) {
+		const entryPath = path.join(dirPath, entry.name);
+		if (entry.isSymbolicLink()) throw new Error(`Symbolic links are not supported in project directories: ${entryPath}`);
+		if (entry.isDirectory()) await assertNoSymlinks(entryPath);
+	}
+}
+function createStagedNodeFileSystem(projectRoot, stagingRoot) {
+	const { runProjectWriteTransaction: _, ...base } = createNodeBackendFileSystem();
+	const translate = (filePath) => {
+		const relative = path.relative(projectRoot, path.resolve(filePath));
+		if (relative.startsWith("..") || path.isAbsolute(relative)) {
+			const error = /* @__PURE__ */ new Error(`Project path escapes the staged root: ${filePath}`);
+			error.code = "EACCES";
+			throw error;
+		}
+		return path.join(stagingRoot, relative);
+	};
+	return {
+		...base,
+		stat: (filePath) => fs.stat(translate(filePath)),
+		async readdir(dirPath) {
+			const entries = await fs.readdir(translate(dirPath), { withFileTypes: true });
+			const symlink = entries.find((entry) => entry.isSymbolicLink());
+			if (symlink) throw new Error(`Symbolic links are not supported in project directories: ${path.join(dirPath, symlink.name)}`);
+			return entries.map((entry) => entry.name);
+		},
+		readFile: (filePath) => fs.readFile(translate(filePath), "utf-8"),
+		async readFileRaw(filePath) {
+			const buffer = await fs.readFile(translate(filePath));
+			return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+		},
+		writeFile: (filePath, content) => fs.writeFile(translate(filePath), content, "utf-8"),
+		writeFileRaw: (filePath, data) => fs.writeFile(translate(filePath), data),
+		async mkdir(dirPath, options) {
+			await fs.mkdir(translate(dirPath), { recursive: options?.recursive ?? false });
+		},
+		resolvePath: (filePath) => resolvePathThroughExistingAncestor(translate(filePath)),
+		unlink: (filePath) => fs.unlink(translate(filePath)),
+		rmdir: (dirPath) => fs.rmdir(translate(dirPath))
+	};
+}
+async function runNodeProjectWriteTransaction(projectRoot, write) {
+	const root = path.resolve(projectRoot);
+	const parent = path.dirname(root);
+	const name = path.basename(root);
+	const staging = path.join(parent, `.${name}.save-${randomUUID()}`);
+	const backup = path.join(parent, `.${name}.save-backup-${randomUUID()}`);
+	const existed = await pathExists(root);
+	if (existed) {
+		await assertNoSymlinks(root);
+		await fs.cp(root, staging, {
+			recursive: true,
+			errorOnExist: true,
+			force: false
+		});
+	} else await fs.mkdir(staging, { recursive: true });
+	try {
+		await write(createStagedNodeFileSystem(root, staging));
+	} catch (error) {
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	if (!existed) {
+		await fs.rename(staging, root);
+		return;
+	}
+	await fs.rename(root, backup);
+	try {
+		await fs.rename(staging, root);
+	} catch (error) {
+		await fs.rename(backup, root);
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	await fs.rm(backup, {
+		recursive: true,
+		force: true
+	}).catch(() => void 0);
+}
 function createNodeBackendFileSystem() {
 	return {
 		stat(filePath) {
 			return fs.stat(filePath);
 		},
-		readdir(dirPath) {
-			return fs.readdir(dirPath);
+		async readdir(dirPath) {
+			const entries = await fs.readdir(dirPath, { withFileTypes: true });
+			const symlink = entries.find((entry) => entry.isSymbolicLink());
+			if (symlink) {
+				const error = /* @__PURE__ */ new Error(`Symbolic links are not supported in project directories: ${path.join(dirPath, symlink.name)}`);
+				error.code = "ELOOP";
+				throw error;
+			}
+			return entries.map((entry) => entry.name);
 		},
 		readFile(filePath) {
 			return fs.readFile(filePath, "utf-8");
@@ -1694,16 +1904,32 @@ function createNodeBackendFileSystem() {
 			await fs.mkdir(dirPath, { recursive: options?.recursive ?? false });
 		},
 		async resolvePath(filePath) {
-			try {
-				return await fs.realpath(filePath);
-			} catch {
-				return path.resolve(filePath);
-			}
+			return resolvePathThroughExistingAncestor(filePath);
 		},
+		validateProjectRoot: assertNoSymlinks,
+		getSessionLockPath(canonicalProjectPath) {
+			return path.join(path.dirname(canonicalProjectPath), `.${path.basename(canonicalProjectPath)}.openfairygui.backend.lock`);
+		},
+		runProjectWriteTransaction: runNodeProjectWriteTransaction,
 		async acquireSessionLock(filePath) {
-			const handle = await fs.open(filePath, "wx");
+			let handle;
+			try {
+				handle = await fs.open(filePath, "wx");
+			} catch (error) {
+				if (error.code !== "EEXIST" || !await recoverStaleLock(filePath)) throw error;
+				handle = await fs.open(filePath, "wx");
+			}
+			const owner = {
+				schemaVersion: 1,
+				pid: process.pid,
+				processStartTime: PROCESS_START_TIME,
+				hostname: os.hostname(),
+				token: randomUUID(),
+				createdAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
 			let closed = false;
 			let released = false;
+			let metadataWritten = false;
 			const closeHandle = async () => {
 				if (closed) return;
 				await handle.close();
@@ -1711,13 +1937,23 @@ function createNodeBackendFileSystem() {
 			};
 			return {
 				async writeMetadata(content) {
-					await handle.writeFile(content, "utf-8");
+					let supplied = {};
+					try {
+						const parsed = JSON.parse(content);
+						if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) supplied = parsed;
+					} catch {}
+					await handle.writeFile(JSON.stringify({
+						...supplied,
+						...owner
+					}, null, 2), "utf-8");
+					metadataWritten = true;
 					await closeHandle();
 				},
 				async release() {
 					if (released) return;
 					await closeHandle();
-					await fs.unlink(filePath).catch((error) => {
+					const current = metadataWritten ? parseLockMetadata(await fs.readFile(filePath, "utf-8").catch(() => "")) : null;
+					if (!metadataWritten || current?.token === owner.token) await fs.unlink(filePath).catch((error) => {
 						if (error.code !== "ENOENT") throw error;
 					});
 					released = true;
@@ -1743,11 +1979,7 @@ function createNodeBackendFileSystem() {
 }
 function createNodeBackendHostAdapter() {
 	return { lockMetadata(input) {
-		return {
-			pid: process.pid,
-			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-			canonicalPathKey: input.canonicalPathKey
-		};
+		return { canonicalPathKey: input.canonicalPathKey };
 	} };
 }
 function createNodeBackendRuntime(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/backend",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -11,7 +11,10 @@
   },
   "homepage": "https://github.com/OpenFairyGUI/OpenFairyGUI#readme",
   "bugs": {
-    "url": "https://github.com/OpenFairyGUI/OpenFairYGUI/issues"
+    "url": "https://github.com/OpenFairyGUI/OpenFairyGUI/issues"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "type": "module",
   "sideEffects": false,
@@ -52,13 +55,13 @@
     "runtime"
   ],
   "dependencies": {
-    "@openfairygui/functions": "0.3.0",
-    "@openfairygui/core": "0.3.0"
+    "@openfairygui/core": "0.3.1",
+    "@openfairygui/functions": "0.3.1"
   },
   "devDependencies": {
     "ava": "^7.0.0",
     "tsx": "^4.0.0",
-    "@openfairygui/test-utils": "0.2.0-alpha.10"
+    "@openfairygui/test-utils": "0.3.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/index.ts

@@ -57,9 +57,12 @@ export {
 	type MaterializeValidationFailedError,
 	type MaterializeWriteFailedError,
 	type OpenProjectSessionInput,
+	type ProjectOpenFailedError,
+	type ProjectRootNotAllowedError,
 	type RefreshCacheInput,
 	type SavePartialFailureError,
 	type SaveSessionInput,
+	type SessionIdConflictError,
 	type SessionNotFoundError,
 	type SessionStaleWriteError,
 	type UamFidelityUnsupportedError,