@openfairygui/backend 0.2.0-alpha.9 → 0.3.0-alpha.1

package/dist/index.mjs

@@ -1,4 +1,1640 @@
-import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-DFatY9W0.mjs";
+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";
+//#region src/contracts.ts
+const BACKEND_CONTRACT_VERSION = "1.1.0-p2";
+const BACKEND_CAPABILITY_SCHEMA_VERSION = 2;
+const BACKEND_COMPATIBILITY_POLICY = {
+	incompatibleChange: "requires contractVersion bump",
+	capabilitySchemaChange: "requires capabilitySchemaVersion bump",
+	additiveChange: "allowed without breaking existing consumers"
+};
+//#endregion
+//#region src/path-policy.ts
+function normalizeComparablePath(value) {
+	const normalized = value.replace(/[/\\]+$/, "").replace(/\\/g, "/");
+	const driveMatch = normalized.match(/^([a-z]:)(?:\/(.*))?$/i);
+	const drivePrefix = driveMatch?.[1].toLowerCase() ?? "";
+	const remainder = driveMatch ? driveMatch[2] ?? "" : normalized;
+	const hasRoot = driveMatch ? true : remainder.startsWith("/");
+	const rawSegments = remainder.split("/").filter((segment) => segment.length > 0);
+	const segments = [];
+	for (const segment of rawSegments) {
+		if (segment === ".") continue;
+		if (segment === "..") {
+			if (segments.length > 0 && segments[segments.length - 1] !== "..") segments.pop();
+			else if (!hasRoot) segments.push("..");
+			continue;
+		}
+		segments.push(segment);
+	}
+	const joined = segments.join("/");
+	return (drivePrefix ? `${drivePrefix}/${joined}`.replace(/\/$/, "") : hasRoot ? `/${joined}`.replace(/\/$/, "") : joined || ".").toLowerCase();
+}
+function createRuntimePathPolicy() {
+	return {
+		canonicalization: "realpath+normalized-casefold",
+		sessionIdentity: "project-root",
+		saveTarget: "opened-project-only",
+		outputTargets: "deferred",
+		workspaceBoundary: "project-root-only"
+	};
+}
+async function resolveFairyPath(fileSystem, input) {
+	const resolvedInput = fileSystem.resolve(input);
+	const stat = await fileSystem.stat(resolvedInput);
+	if (stat.isFile() && resolvedInput.endsWith(".fairy")) return await fileSystem.resolvePath(resolvedInput);
+	if (stat.isDirectory()) {
+		const fairyFiles = (await fileSystem.readdir(resolvedInput)).filter((entry) => entry.endsWith(".fairy"));
+		if (fairyFiles.length === 1) return await fileSystem.resolvePath(fileSystem.join(resolvedInput, fairyFiles[0]));
+		if (fairyFiles.length > 1) throw new Error(`Multiple .fairy files found in ${resolvedInput}: ${fairyFiles.join(", ")}`);
+		throw new Error(`No .fairy file found in ${resolvedInput}`);
+	}
+	throw new Error(`Input is not a .fairy file or directory: ${resolvedInput}`);
+}
+async function resolveCanonicalProjectRoot(fileSystem, input) {
+	const fairyPath = await resolveFairyPath(fileSystem, input);
+	const canonicalProjectPath = await fileSystem.resolvePath(fileSystem.dirname(fairyPath));
+	return {
+		fairyPath,
+		canonicalProjectPath,
+		canonicalPathKey: normalizeComparablePath(canonicalProjectPath)
+	};
+}
+async function validateSaveTarget(fileSystem, openedFairyPath, targetPath) {
+	if (!targetPath) return null;
+	const attemptedPath = await fileSystem.resolvePath(fileSystem.resolve(targetPath));
+	const allowedPath = await fileSystem.resolvePath(openedFairyPath);
+	if (normalizeComparablePath(attemptedPath) === normalizeComparablePath(allowedPath)) return null;
+	return {
+		code: "path_policy_violation",
+		message: `Save target is restricted to the originally opened project file: ${allowedPath}`,
+		policy: "save_target",
+		attemptedPath,
+		allowedPath
+	};
+}
+//#endregion
+//#region src/services/context.ts
+function diagnosticFromError(error) {
+	return {
+		code: error.code,
+		message: error.message,
+		severity: "error"
+	};
+}
+function randomId$1() {
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function createMeta(stage, startedAt, options) {
+	return {
+		requestId: options?.requestId ?? randomId$1(),
+		sessionId: options?.sessionId,
+		revision: options?.revision,
+		durationMs: Math.max(0, Date.now() - startedAt),
+		warnings: options?.warnings ?? [],
+		diagnostics: options?.diagnostics ?? [],
+		stage,
+		contractVersion: BACKEND_CONTRACT_VERSION,
+		capabilitySchemaVersion: 2
+	};
+}
+function success(stage, startedAt, data, options) {
+	return {
+		ok: true,
+		meta: createMeta(stage, startedAt, options),
+		data
+	};
+}
+function failure(stage, startedAt, error, session, options) {
+	const diagnostics = options?.diagnostics ?? [diagnosticFromError(error)];
+	return {
+		ok: false,
+		meta: createMeta(stage, startedAt, {
+			...options,
+			diagnostics
+		}),
+		error,
+		session
+	};
+}
+//#endregion
+//#region src/services/session-project-writer.ts
+function createWriterFileSystem(fileSystem, writtenPaths, failedPaths) {
+	async function trackWrite(targetPath, write) {
+		try {
+			const result = await write();
+			writtenPaths.push(targetPath);
+			return result;
+		} catch (error) {
+			failedPaths.push(targetPath);
+			throw error;
+		}
+	}
+	return {
+		readFile: (path) => fileSystem.readFile(path),
+		readFileRaw: (path) => fileSystem.readFileRaw(path),
+		writeFile: (path, content) => trackWrite(path, async () => {
+			await fileSystem.mkdir(fileSystem.dirname(path), { recursive: true });
+			await fileSystem.writeFile(path, content);
+		}),
+		writeFileRaw: (path, data) => trackWrite(path, async () => {
+			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),
+		async exists(path) {
+			try {
+				await fileSystem.stat(path);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		join: (...paths) => fileSystem.join(...paths),
+		dirname: (path) => fileSystem.dirname(path),
+		unlink: (path) => trackWrite(path, () => fileSystem.unlink(path)),
+		rmdir: (path) => trackWrite(path, () => fileSystem.rmdir(path))
+	};
+}
+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
+	});
+}
+//#endregion
+//#region src/services/session-utils.ts
+function toSessionSnapshot(session, capabilities) {
+	return {
+		sessionId: session.sessionId,
+		canonicalProjectPath: session.canonicalProjectPath,
+		revision: session.revision,
+		lastSavedRevision: session.lastSavedRevision,
+		dirty: session.dirty,
+		uamFidelity: session.uamFidelity,
+		lockHeld: session.lockHeld,
+		capabilities: structuredClone(capabilities)
+	};
+}
+function createSessionNotFoundError(sessionId) {
+	return {
+		code: "session_not_found",
+		message: `Session was not found: ${sessionId}`,
+		sessionId
+	};
+}
+function createStaleWriteError(session, expectedRevision) {
+	return {
+		code: "stale_write",
+		message: `Expected revision ${expectedRevision} does not match current revision ${session.revision}.`,
+		sessionId: session.sessionId,
+		canonicalPathKey: session.canonicalPathKey,
+		expectedRevision,
+		actualRevision: session.revision
+	};
+}
+//#endregion
+//#region src/services/authoring-service.ts
+function sourceFileKey(source) {
+	return [
+		source.branch,
+		source.packageName,
+		source.path,
+		source.fileName
+	].join("\0");
+}
+function resourceFolderKey(folder) {
+	return [
+		folder.branch,
+		folder.packageName,
+		folder.path
+	].join("\0");
+}
+function branchDirectoryKey(directory) {
+	return [directory.branch, directory.packageName ?? ""].join("\0");
+}
+function recordStaleProjectFiles(session, previousProject, nextProject) {
+	if (!session.fileSystem) return;
+	for (const source of staleSourceFiles(previousProject, nextProject)) session.pendingStaleSourceFiles.set(sourceFileKey(source), source);
+	for (const source of staleSourceFiles(nextProject, previousProject)) session.pendingStaleSourceFiles.delete(sourceFileKey(source));
+	for (const folder of staleResourceFolders(previousProject, nextProject)) session.pendingStaleResourceFolders.set(resourceFolderKey(folder), folder);
+	for (const folder of staleResourceFolders(nextProject, previousProject)) session.pendingStaleResourceFolders.delete(resourceFolderKey(folder));
+	for (const directory of staleBranchDirectories(previousProject, nextProject)) session.pendingStaleBranchDirectories.set(branchDirectoryKey(directory), directory);
+	for (const directory of staleBranchDirectories(nextProject, previousProject)) session.pendingStaleBranchDirectories.delete(branchDirectoryKey(directory));
+}
+function toBackendDiagnostics(error) {
+	return error.diagnostics.length > 0 ? error.diagnostics.map((diagnostic) => ({ ...diagnostic })) : [{
+		code: error.code,
+		message: error.message,
+		severity: "error",
+		operationKind: error.operationKind,
+		opIndex: error.opIndex,
+		opId: error.opId
+	}];
+}
+function createCapabilityUnavailableError$1(message) {
+	return {
+		code: "capability_unavailable",
+		message,
+		capability: "fileSystem",
+		requiredAdapter: "BackendFileSystem"
+	};
+}
+function createUamFidelityUnsupportedError(session) {
+	return {
+		code: "uam_fidelity_unsupported",
+		message: "The source project contains formal properties that the current UAM cannot preserve.",
+		sessionId: session.sessionId,
+		canonicalPathKey: session.canonicalPathKey
+	};
+}
+function validationDiagnostics(sessionProject) {
+	return validateUamProject(sessionProject).map((issue) => ({
+		code: "materialize_validation_failed",
+		message: issue.message,
+		severity: "error",
+		path: issue.path,
+		operationKind: "materializeSession"
+	}));
+}
+function toMaterializeSnapshot(session, capabilities, input) {
+	return {
+		...toSessionSnapshot(session, capabilities),
+		mode: "fullProject",
+		reason: input.reason,
+		materializeRevision: session.revision,
+		saveRevision: session.lastSavedRevision,
+		writtenPaths: [...input.writtenPaths],
+		skippedPaths: [...input.skippedPaths],
+		diagnostics: input.diagnostics.map((diagnostic) => ({ ...diagnostic }))
+	};
+}
+function storageCanonicalTarget(input) {
+	const canonicalProjectPath = input.canonicalProjectPath ?? (input.fileSystem.dirname(input.fairyPath) || ".");
+	return {
+		fileSystem: input.fileSystem,
+		fairyPath: input.fairyPath,
+		canonicalProjectPath,
+		canonicalPathKey: input.canonicalPathKey ?? normalizeComparablePath(canonicalProjectPath)
+	};
+}
+function detachSharedByteViews(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (!value || typeof value !== "object" || seen.has(value)) return;
+	seen.add(value);
+	for (const [key, child] of Object.entries(value)) {
+		if (child instanceof Uint8Array) {
+			if (typeof SharedArrayBuffer !== "undefined" && child.buffer instanceof SharedArrayBuffer) value[key] = new Uint8Array(child);
+			continue;
+		}
+		detachSharedByteViews(child, seen);
+	}
+}
+var AuthoringService = class {
+	sessionOperations = /* @__PURE__ */ new Map();
+	constructor(context, cacheService, eventService) {
+		this.context = context;
+		this.cacheService = cacheService;
+		this.eventService = eventService;
+	}
+	async runSessionExclusive(sessionId, operation) {
+		const previous = this.sessionOperations.get(sessionId) ?? Promise.resolve();
+		let release = () => void 0;
+		const current = new Promise((resolve) => {
+			release = resolve;
+		});
+		const tail = previous.then(() => current);
+		this.sessionOperations.set(sessionId, tail);
+		await previous;
+		try {
+			return await operation();
+		} finally {
+			release();
+			if (this.sessionOperations.get(sessionId) === tail) this.sessionOperations.delete(sessionId);
+		}
+	}
+	async applyTransaction(input) {
+		const queuedInput = structuredClone(input);
+		detachSharedByteViews(queuedInput);
+		return this.runSessionExclusive(queuedInput.sessionId, () => this.applyTransactionExclusive(queuedInput));
+	}
+	async applyTransactionExclusive(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
+		if (input.expectedRevision !== session.revision) {
+			this.eventService.emit({
+				kind: "transaction.rejected",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision
+			});
+			return failure("authoring", startedAt, createStaleWriteError(session, input.expectedRevision), toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		}
+		const result = await applyUamTransactionAppAsync({
+			project: session.project,
+			operations: input.operations
+		});
+		if (this.context.sessions.get(input.sessionId) !== session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
+		if (result.ok === false) {
+			const diagnostics = toBackendDiagnostics(result.error);
+			this.eventService.emit({
+				kind: "transaction.rejected",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				diagnostics
+			});
+			return failure("authoring", startedAt, result.error, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics
+			});
+		}
+		recordStaleProjectFiles(session, session.project, result.project);
+		session.project = result.project;
+		session.revision += 1;
+		session.dirty = true;
+		const cacheEntry = this.cacheService.invalidateSession(session);
+		this.eventService.emit({
+			kind: "transaction.applied",
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision
+		});
+		this.eventService.emit({
+			kind: "cache.invalidated",
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision,
+			cacheRevision: cacheEntry.revision
+		});
+		return success("authoring", startedAt, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	async saveSession(input) {
+		if (input.force === true || input.mode === "materializeCleanSession") return this.materializeSession({
+			sessionId: input.sessionId,
+			expectedRevision: input.expectedRevision,
+			targetPath: input.targetPath,
+			fileSystem: input.fileSystem,
+			mode: "fullProject",
+			reason: "force_save"
+		});
+		return this.runSessionExclusive(input.sessionId, () => this.saveSessionExclusive(input));
+	}
+	async saveSessionExclusive(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
+		const fileSystem = session.fileSystem ?? input.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("saveSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		if (input.expectedRevision !== void 0 && input.expectedRevision !== session.revision) return failure("authoring", startedAt, createStaleWriteError(session, input.expectedRevision), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
+		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		if (!session.dirty) return success("authoring", startedAt, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		if (session.uamFidelity === "unsupported") return failure("authoring", startedAt, createUamFidelityUnsupportedError(session), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const committedPaths = [];
+		const failedPaths = [];
+		this.eventService.emit({
+			kind: "save.started",
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision
+		});
+		try {
+			await writeSessionProject({
+				fileSystem,
+				document: materializeUamProject(session.project),
+				fairyPath: session.fairyPath,
+				staleSourceFiles: [...session.pendingStaleSourceFiles.values()],
+				staleResourceFolders: [...session.pendingStaleResourceFolders.values()],
+				staleBranchDirectories: [...session.pendingStaleBranchDirectories.values()],
+				writtenPaths: committedPaths,
+				failedPaths
+			});
+			session.fileSystem ??= fileSystem;
+			session.pendingStaleSourceFiles.clear();
+			session.pendingStaleResourceFolders.clear();
+			session.pendingStaleBranchDirectories.clear();
+			commitUamProjectSourcePaths(session.project);
+			session.lastSavedRevision = session.revision;
+			session.dirty = false;
+			const cacheEntry = this.cacheService.refreshSession(session);
+			this.eventService.emit({
+				kind: "save.completed",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision
+			});
+			this.eventService.emit({
+				kind: "cache.updated",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				cacheRevision: cacheEntry.revision
+			});
+			return success("authoring", startedAt, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		} catch (error) {
+			this.cacheService.invalidateSession(session);
+			this.eventService.emit({
+				kind: "save.failed",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision
+			});
+			return failure("authoring", startedAt, {
+				code: "save_partial_failure",
+				message: error instanceof Error ? error.message : String(error),
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				attemptedRevision: session.revision,
+				lastSavedRevision: session.lastSavedRevision,
+				committedPaths,
+				failedPaths,
+				diskMayBePartiallyUpdated: true
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		}
+	}
+	async materializeSession(input) {
+		return this.runSessionExclusive(input.sessionId, () => this.materializeSessionExclusive(input));
+	}
+	async materializeSessionExclusive(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
+		if (input.expectedRevision !== void 0 && input.expectedRevision !== session.revision) return failure("authoring", startedAt, createStaleWriteError(session, input.expectedRevision), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const storageTarget = input.storage ? storageCanonicalTarget(input.storage) : null;
+		const fileSystem = storageTarget?.fileSystem ?? input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("materializeSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const fairyPath = storageTarget?.fairyPath ?? session.fairyPath;
+		const targetViolation = await validateSaveTarget(fileSystem, fairyPath, input.targetPath);
+		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		if (storageTarget) {
+			const holderSessionId = this.context.sessionsByPath.get(storageTarget.canonicalPathKey);
+			if (holderSessionId && holderSessionId !== session.sessionId) return failure("authoring", startedAt, {
+				code: "lock_conflict",
+				kind: "in_process_session_exists",
+				message: `Project is already open in this backend runtime: ${storageTarget.canonicalProjectPath}`,
+				canonicalPathKey: storageTarget.canonicalPathKey,
+				holderSessionId
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		}
+		if (session.uamFidelity === "unsupported") return failure("authoring", startedAt, createUamFidelityUnsupportedError(session), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const diagnostics = validationDiagnostics(session.project);
+		if (diagnostics.length > 0) return failure("authoring", startedAt, {
+			code: "materialize_validation_failed",
+			message: `UAM materialize validation failed with ${diagnostics.length} issue(s).`,
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			issueCount: diagnostics.length,
+			diagnostics
+		}, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision,
+			diagnostics
+		});
+		let document;
+		try {
+			document = materializeUamProject(session.project);
+		} catch (error) {
+			const diagnosticsFromError = [{
+				code: "materialize_validation_failed",
+				message: error instanceof Error ? error.message : String(error),
+				severity: "error",
+				operationKind: "materializeSession"
+			}];
+			return failure("authoring", startedAt, {
+				code: "materialize_validation_failed",
+				message: error instanceof Error ? error.message : String(error),
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				issueCount: diagnosticsFromError.length,
+				diagnostics: diagnosticsFromError
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+		}
+		const writtenPaths = [];
+		const failedPaths = [];
+		const skippedPaths = [];
+		this.eventService.emit({
+			kind: "save.started",
+			sessionId: session.sessionId,
+			canonicalPathKey: storageTarget?.canonicalPathKey ?? session.canonicalPathKey,
+			revision: session.revision
+		});
+		try {
+			const isSessionStorageTarget = fileSystem === session.fileSystem && fairyPath === session.fairyPath;
+			await writeSessionProject({
+				fileSystem,
+				document,
+				fairyPath,
+				staleSourceFiles: isSessionStorageTarget ? [...session.pendingStaleSourceFiles.values()] : [],
+				staleResourceFolders: isSessionStorageTarget ? [...session.pendingStaleResourceFolders.values()] : [],
+				staleBranchDirectories: isSessionStorageTarget ? [...session.pendingStaleBranchDirectories.values()] : [],
+				writtenPaths,
+				failedPaths
+			});
+			if (isSessionStorageTarget) {
+				session.pendingStaleSourceFiles.clear();
+				session.pendingStaleResourceFolders.clear();
+				session.pendingStaleBranchDirectories.clear();
+			}
+			if (storageTarget && !isSessionStorageTarget) {
+				session.pendingStaleSourceFiles.clear();
+				session.pendingStaleResourceFolders.clear();
+				session.pendingStaleBranchDirectories.clear();
+			}
+			if (isSessionStorageTarget || storageTarget) commitUamProjectSourcePaths(session.project);
+			if (storageTarget) {
+				this.context.sessionsByPath.delete(session.canonicalPathKey);
+				session.fileSystem = storageTarget.fileSystem;
+				session.fairyPath = storageTarget.fairyPath;
+				session.canonicalProjectPath = storageTarget.canonicalProjectPath;
+				session.canonicalPathKey = storageTarget.canonicalPathKey;
+				this.context.sessionsByPath.set(session.canonicalPathKey, session.sessionId);
+			}
+			session.lastSavedRevision = session.revision;
+			session.dirty = false;
+			const cacheEntry = this.cacheService.refreshSession(session);
+			this.eventService.emit({
+				kind: "save.completed",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision
+			});
+			this.eventService.emit({
+				kind: "cache.updated",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				cacheRevision: cacheEntry.revision
+			});
+			return success("authoring", startedAt, toMaterializeSnapshot(session, this.context.capabilities, {
+				reason: input.reason,
+				writtenPaths,
+				skippedPaths,
+				diagnostics: []
+			}), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		} catch (error) {
+			const diagnosticsFromError = [{
+				code: "write_failed",
+				message: error instanceof Error ? error.message : String(error),
+				severity: "error",
+				path: failedPaths[0],
+				operationKind: "materializeSession"
+			}];
+			this.cacheService.invalidateSession(session);
+			this.eventService.emit({
+				kind: "save.failed",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+			return failure("authoring", startedAt, {
+				code: "write_failed",
+				message: error instanceof Error ? error.message : String(error),
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				attemptedRevision: session.revision,
+				lastSavedRevision: session.lastSavedRevision,
+				writtenPaths,
+				failedPaths,
+				skippedPaths,
+				diagnostics: diagnosticsFromError,
+				diskMayBePartiallyUpdated: true
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+		}
+	}
+};
+//#endregion
+//#region src/services/cache-service.ts
+function createCacheEntry(session, valid) {
+	return {
+		canonicalPathKey: session.canonicalPathKey,
+		sessionId: session.sessionId,
+		revision: session.revision,
+		lastSavedRevision: session.lastSavedRevision,
+		dirty: session.dirty,
+		valid,
+		indexedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		summary: {
+			packageCount: session.project.packages.length,
+			resourceCount: session.project.packages.reduce((total, pkg) => total + pkg.resources.length, 0),
+			diagnostics: []
+		}
+	};
+}
+var CacheService = class {
+	constructor(context) {
+		this.context = context;
+	}
+	getCacheSnapshot(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("read", startedAt, createSessionNotFoundError(input.sessionId));
+		const entry = this.context.cacheBySession.get(input.sessionId);
+		return success("read", startedAt, {
+			cacheRevision: entry?.revision ?? session.revision,
+			entries: entry ? [structuredClone(entry)] : []
+		}, {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	refreshSession(session) {
+		const entry = createCacheEntry(session, true);
+		this.context.cacheBySession.set(session.sessionId, entry);
+		return entry;
+	}
+	invalidateSession(session) {
+		const entry = createCacheEntry(session, false);
+		this.context.cacheBySession.set(session.sessionId, entry);
+		return entry;
+	}
+	removeSession(sessionId) {
+		this.context.cacheBySession.delete(sessionId);
+	}
+};
+//#endregion
+//#region src/services/event-service.ts
+const DEFAULT_EVENT_RETENTION_LIMIT = 1e3;
+var EventService = class {
+	constructor(context) {
+		this.context = context;
+	}
+	emit(event) {
+		const emitted = {
+			...event,
+			sequence: this.context.nextEventSequence(),
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			diagnostics: event.diagnostics ?? []
+		};
+		const sessionId = event.sessionId;
+		if (!sessionId) return emitted;
+		const events = this.context.eventsBySession.get(sessionId) ?? [];
+		events.push(emitted);
+		while (events.length > DEFAULT_EVENT_RETENTION_LIMIT) events.shift();
+		this.context.eventsBySession.set(sessionId, events);
+		return emitted;
+	}
+	getEvents(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("runtime", startedAt, createSessionNotFoundError(input.sessionId));
+		const events = this.context.eventsBySession.get(input.sessionId) ?? [];
+		const oldestSequence = events[0]?.sequence ?? (events.length === 0 ? 1 : 0);
+		const currentSequence = events.at(-1)?.sequence ?? 0;
+		const after = input.after === void 0 ? 0 : Number(input.after);
+		if (!Number.isInteger(after) || after < 0) return failure("runtime", startedAt, {
+			code: "event_cursor_invalid",
+			message: `Invalid event cursor: ${input.after}`,
+			sessionId: input.sessionId,
+			after: String(input.after)
+		});
+		if (events.length > 0 && after !== 0 && after < oldestSequence - 1) return failure("runtime", startedAt, {
+			code: "event_cursor_invalid",
+			message: `Event cursor has expired: ${after}`,
+			sessionId: input.sessionId,
+			after: String(input.after)
+		});
+		if (after > currentSequence) return failure("runtime", startedAt, {
+			code: "event_cursor_invalid",
+			message: `Unknown event cursor: ${after}`,
+			sessionId: input.sessionId,
+			after: String(input.after)
+		});
+		const filtered = events.filter((event) => event.sequence > after);
+		const limit = input.limit === void 0 ? filtered.length : Math.max(0, input.limit);
+		return success("runtime", startedAt, {
+			events: filtered.slice(0, limit).map((event) => structuredClone(event)),
+			oldestSequence,
+			currentSequence,
+			cursorExpired: false
+		}, {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	removeSession(sessionId) {
+		this.context.eventsBySession.delete(sessionId);
+	}
+};
+//#endregion
+//#region src/services/job-service.ts
+const COMPLETED_JOB_RETENTION_LIMIT = 100;
+const REFRESH_START_DELAY_MS = 0;
+const REFRESH_COMPLETE_DELAY_MS = 50;
+function isTerminal(status) {
+	return status === "completed" || status === "failed" || status === "cancelled";
+}
+var JobService = class {
+	constructor(context, cacheService, eventService) {
+		this.context = context;
+		this.cacheService = cacheService;
+		this.eventService = eventService;
+	}
+	cancellationRequests = /* @__PURE__ */ new Set();
+	getJobs(sessionId) {
+		return this.context.jobsBySession.get(sessionId) ?? [];
+	}
+	setJobs(sessionId, jobs) {
+		const retained = [];
+		let terminalCount = 0;
+		for (let index = jobs.length - 1; index >= 0; index -= 1) {
+			const job = jobs[index];
+			if (isTerminal(job.status)) {
+				if (terminalCount >= COMPLETED_JOB_RETENTION_LIMIT) continue;
+				terminalCount += 1;
+			}
+			retained.push(job);
+		}
+		this.context.jobsBySession.set(sessionId, retained.reverse());
+	}
+	refreshCache(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("runtime", startedAt, createSessionNotFoundError(input.sessionId));
+		const jobId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+		const job = {
+			jobId,
+			kind: "cache.refresh",
+			status: "queued",
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision,
+			diagnostics: [],
+			progress: {
+				completed: 0,
+				total: 1,
+				message: input.reason ?? "manual"
+			}
+		};
+		const jobs = this.getJobs(session.sessionId);
+		jobs.push(job);
+		this.setJobs(session.sessionId, jobs);
+		this.eventService.emit({
+			kind: "job.created",
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision,
+			jobId
+		});
+		this.scheduleRefreshJob(session.sessionId, jobId);
+		return success("runtime", startedAt, structuredClone(job), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	getJob(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("runtime", startedAt, createSessionNotFoundError(input.sessionId));
+		const job = this.getJobs(input.sessionId).find((item) => item.jobId === input.jobId);
+		if (!job) return failure("runtime", startedAt, {
+			code: "job_not_found",
+			message: `Job was not found: ${input.jobId}`,
+			sessionId: input.sessionId,
+			jobId: input.jobId
+		}, void 0, {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		return success("runtime", startedAt, structuredClone(job), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	listJobs(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("runtime", startedAt, createSessionNotFoundError(input.sessionId));
+		let jobs = [...this.getJobs(input.sessionId)];
+		if (input.kind) jobs = jobs.filter((job) => job.kind === input.kind);
+		if (input.status) if (input.status === "active") jobs = jobs.filter((job) => !isTerminal(job.status));
+		else if (input.status === "terminal") jobs = jobs.filter((job) => isTerminal(job.status));
+		else jobs = jobs.filter((job) => job.status === input.status);
+		if (input.limit !== void 0) jobs = jobs.slice(0, Math.max(0, input.limit));
+		return success("runtime", startedAt, { jobs: jobs.map((job) => structuredClone(job)) }, {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	cancelJob(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("runtime", startedAt, createSessionNotFoundError(input.sessionId));
+		const job = this.getJobs(input.sessionId).find((item) => item.jobId === input.jobId);
+		if (!job) return failure("runtime", startedAt, {
+			code: "job_not_found",
+			message: `Job was not found: ${input.jobId}`,
+			sessionId: input.sessionId,
+			jobId: input.jobId
+		}, void 0, {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		if (isTerminal(job.status)) return failure("runtime", startedAt, {
+			code: "job_not_cancellable",
+			message: `Job is already terminal: ${input.jobId}`,
+			sessionId: input.sessionId,
+			jobId: input.jobId,
+			status: job.status
+		}, void 0, {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		this.cancellationRequests.add(job.jobId);
+		this.eventService.emit({
+			kind: "job.cancelRequested",
+			sessionId: input.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision,
+			jobId: job.jobId
+		});
+		const cancelled = this.cancelRefreshJob(session.sessionId, job);
+		return success("runtime", startedAt, structuredClone(cancelled), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	removeSession(sessionId) {
+		for (const job of this.getJobs(sessionId)) this.cancellationRequests.delete(job.jobId);
+		this.context.jobsBySession.delete(sessionId);
+	}
+	replaceJob(sessionId, nextJob) {
+		const jobs = this.getJobs(sessionId).map((job) => job.jobId === nextJob.jobId ? nextJob : job);
+		this.setJobs(sessionId, jobs);
+	}
+	scheduleRefreshJob(sessionId, jobId) {
+		setTimeout(() => this.startRefreshJob(sessionId, jobId), REFRESH_START_DELAY_MS);
+	}
+	startRefreshJob(sessionId, jobId) {
+		const session = this.context.sessions.get(sessionId);
+		if (!session || session.closed) return;
+		const job = this.getJobs(sessionId).find((item) => item.jobId === jobId);
+		if (!job || isTerminal(job.status)) return;
+		if (this.cancellationRequests.has(jobId)) {
+			this.cancelRefreshJob(sessionId, job);
+			return;
+		}
+		const running = {
+			...job,
+			status: "running",
+			startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			progress: {
+				completed: 0,
+				total: 1,
+				message: "refreshing cache"
+			}
+		};
+		this.replaceJob(sessionId, running);
+		this.eventService.emit({
+			kind: "job.started",
+			sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision,
+			jobId
+		});
+		this.eventService.emit({
+			kind: "job.progress",
+			sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision,
+			jobId,
+			payload: running.progress
+		});
+		setTimeout(() => this.completeRefreshJob(sessionId, jobId), REFRESH_COMPLETE_DELAY_MS);
+	}
+	completeRefreshJob(sessionId, jobId) {
+		const session = this.context.sessions.get(sessionId);
+		if (!session || session.closed) return;
+		const job = this.getJobs(sessionId).find((item) => item.jobId === jobId);
+		if (!job || isTerminal(job.status)) return;
+		if (this.cancellationRequests.has(jobId)) {
+			this.cancelRefreshJob(sessionId, job);
+			return;
+		}
+		try {
+			const entry = this.cacheService.refreshSession(session);
+			const completed = {
+				...job,
+				status: "completed",
+				finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				cacheRevision: entry.revision,
+				progress: {
+					completed: 1,
+					total: 1,
+					message: "cache refreshed"
+				},
+				result: { cacheRevision: entry.revision }
+			};
+			this.replaceJob(sessionId, completed);
+			this.eventService.emit({
+				kind: "job.completed",
+				sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				cacheRevision: entry.revision,
+				jobId
+			});
+			this.eventService.emit({
+				kind: "cache.updated",
+				sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				cacheRevision: entry.revision
+			});
+		} catch (error) {
+			const failed = {
+				...job,
+				status: "failed",
+				finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				error: {
+					code: "cache_refresh_failed",
+					message: error instanceof Error ? error.message : "Cache refresh failed",
+					sessionId,
+					jobId
+				}
+			};
+			this.replaceJob(sessionId, failed);
+			this.eventService.emit({
+				kind: "job.failed",
+				sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				jobId,
+				diagnostics: failed.diagnostics
+			});
+		}
+	}
+	cancelRefreshJob(sessionId, job) {
+		const session = this.context.sessions.get(sessionId);
+		const cancelled = {
+			...job,
+			status: "cancelled",
+			finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			error: {
+				code: "job_cancelled",
+				message: `Job was cancelled: ${job.jobId}`,
+				sessionId,
+				jobId: job.jobId
+			}
+		};
+		this.replaceJob(sessionId, cancelled);
+		this.cancellationRequests.delete(job.jobId);
+		this.eventService.emit({
+			kind: "job.cancelled",
+			sessionId,
+			canonicalPathKey: session?.canonicalPathKey ?? job.canonicalPathKey,
+			revision: session?.revision ?? job.revision,
+			jobId: job.jobId
+		});
+		return cancelled;
+	}
+};
+//#endregion
+//#region src/services/read-service.ts
+function toProjectOutline(session) {
+	const project = session.project;
+	return {
+		sessionId: session.sessionId,
+		revision: session.revision,
+		projectId: project.projectId,
+		projectType: project.projectType,
+		version: project.version,
+		branches: [...project.branches],
+		packages: project.packages.map((pkg) => ({
+			id: pkg.id,
+			name: pkg.name,
+			branchNames: [...pkg.branchNames],
+			folders: pkg.folders.map((folder) => ({
+				branch: folder.branch,
+				path: folder.path
+			})),
+			resources: pkg.resources.map((resource) => ({
+				id: resource.id,
+				name: resource.name,
+				path: resource.path,
+				kind: resource.kind,
+				branch: resource.branch,
+				...resource.kind === "component" ? { component: {
+					displayList: resource.component.displayList.map((node) => ({
+						id: node.id,
+						name: node.name,
+						kind: node.kind
+					})),
+					controllers: resource.component.controllers.map((controller) => ({
+						name: controller.name,
+						pages: controller.pages.map((page) => ({
+							id: page.id,
+							name: page.name
+						}))
+					})),
+					transitions: resource.component.transitions.map((transition) => ({ name: transition.name }))
+				} } : {}
+			}))
+		}))
+	};
+}
+var ReadService = class {
+	constructor(context) {
+		this.context = context;
+	}
+	getCapabilities() {
+		return success("read", Date.now(), structuredClone(this.context.capabilities));
+	}
+	getSession(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("read", startedAt, createSessionNotFoundError(input.sessionId));
+		return success("read", startedAt, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	getProjectOutline(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("read", startedAt, createSessionNotFoundError(input.sessionId));
+		return success("read", startedAt, toProjectOutline(session), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+};
+//#endregion
+//#region src/services/runtime-service.ts
+function randomId() {
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function createCapabilityUnavailableError(capability) {
+	const artifactCapability = capability === "artifact.publish" || capability === "artifact.restore";
+	return {
+		code: "capability_unavailable",
+		message: artifactCapability ? `${capability} requires the Node bridge boundary exposed by @openfairygui/backend/node.` : `${capability} requires an injected BackendFileSystem adapter.`,
+		capability,
+		requiredAdapter: capability === "fileSystem" ? "BackendFileSystem" : void 0,
+		requiredHost: artifactCapability ? "node" : void 0,
+		bridgeBoundary: artifactCapability ? "external-bridge" : void 0
+	};
+}
+function createProjectReaderFileSystem(fileSystem) {
+	return {
+		readFile(filePath) {
+			return fileSystem.readFile(filePath);
+		},
+		readFileRaw(filePath) {
+			return fileSystem.readFileRaw(filePath);
+		},
+		writeFile(filePath, content) {
+			return fileSystem.writeFile(filePath, content);
+		},
+		writeFileRaw(filePath, data) {
+			return fileSystem.writeFileRaw(filePath, data);
+		},
+		async mkdir(dirPath) {
+			await fileSystem.mkdir(dirPath, { recursive: true });
+		},
+		readdir(dirPath) {
+			return fileSystem.readdir(dirPath);
+		},
+		async exists(filePath) {
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		join(...paths) {
+			return fileSystem.join(...paths);
+		},
+		dirname(filePath) {
+			return fileSystem.dirname(filePath);
+		}
+	};
+}
+function createCaptureFileSystem(files, directories) {
+	const normalize = (filePath) => filePath.replace(/\\/g, "/").replace(/\/+/g, "/");
+	return {
+		async readFile(filePath) {
+			const value = files.get(normalize(filePath));
+			if (typeof value !== "string") throw new Error(`Captured text file was not found: ${filePath}`);
+			return value;
+		},
+		async readFileRaw(filePath) {
+			const value = files.get(normalize(filePath));
+			if (!(value instanceof Uint8Array)) throw new Error(`Captured binary file was not found: ${filePath}`);
+			return value.slice();
+		},
+		async writeFile(filePath, content) {
+			files.set(normalize(filePath), content);
+		},
+		async writeFileRaw(filePath, data) {
+			files.set(normalize(filePath), data.slice());
+		},
+		async mkdir(dirPath) {
+			directories.add(normalize(dirPath));
+		},
+		async readdir() {
+			return [];
+		},
+		async exists(filePath) {
+			return files.has(normalize(filePath));
+		},
+		join(...paths) {
+			return normalize(paths.filter(Boolean).join("/"));
+		},
+		dirname(filePath) {
+			const normalized = normalize(filePath);
+			const separator = normalized.lastIndexOf("/");
+			return separator < 0 ? "" : normalized.slice(0, separator);
+		},
+		async unlink(filePath) {
+			files.delete(normalize(filePath));
+		}
+	};
+}
+function capturedFilesEqual(left, right) {
+	if (left.size !== right.size) return false;
+	for (const [filePath, leftValue] of left) {
+		const rightValue = right.get(filePath);
+		if (typeof leftValue === "string") {
+			if (leftValue !== rightValue) return false;
+			continue;
+		}
+		if (!(rightValue instanceof Uint8Array) || leftValue.length !== rightValue.length) return false;
+		for (let index = 0; index < leftValue.length; index += 1) if (leftValue[index] !== rightValue[index]) return false;
+	}
+	return true;
+}
+function capturedDirectoriesEqual(left, right) {
+	return left.size === right.size && [...left].every((directory) => right.has(directory));
+}
+async function hasFullUamFidelity(document, project) {
+	const sourceFiles = /* @__PURE__ */ new Map();
+	const materializedFiles = /* @__PURE__ */ new Map();
+	const sourceDirectories = /* @__PURE__ */ new Set();
+	const materializedDirectories = /* @__PURE__ */ new Set();
+	try {
+		await Promise.all([new ProjectWriter(createCaptureFileSystem(sourceFiles, sourceDirectories)).write(document, "Project.fairy"), new ProjectWriter(createCaptureFileSystem(materializedFiles, materializedDirectories)).write(materializeUamProject(project), "Project.fairy")]);
+	} catch {
+		return false;
+	}
+	return capturedFilesEqual(sourceFiles, materializedFiles) && capturedDirectoriesEqual(sourceDirectories, materializedDirectories);
+}
+var RuntimeService = class {
+	constructor(context, cacheService, eventService, jobService) {
+		this.context = context;
+		this.cacheService = cacheService;
+		this.eventService = eventService;
+		this.jobService = jobService;
+	}
+	async openSession(input) {
+		const startedAt = Date.now();
+		if (!this.context.fileSystem) return failure("runtime", startedAt, createCapabilityUnavailableError("fileSystem"));
+		const fileSystem = this.context.fileSystem;
+		const { fairyPath, canonicalProjectPath, canonicalPathKey } = await resolveCanonicalProjectRoot(fileSystem, input.projectPath);
+		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
+		const lockFilePath = fileSystem.join(canonicalProjectPath, ".openfairygui.backend.lock");
+		if (existingSessionId) return failure("runtime", startedAt, {
+			code: "lock_conflict",
+			kind: "in_process_session_exists",
+			message: `Project is already open in this backend runtime: ${canonicalProjectPath}`,
+			canonicalPathKey,
+			holderSessionId: existingSessionId,
+			lockFilePath
+		});
+		let sessionLock = null;
+		try {
+			sessionLock = await fileSystem.acquireSessionLock(lockFilePath);
+			await sessionLock.writeMetadata(JSON.stringify(this.context.host?.lockMetadata?.({
+				canonicalPathKey,
+				canonicalProjectPath,
+				lockFilePath
+			}) ?? {
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				canonicalPathKey
+			}));
+			const document = await new ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath, { hydrateResourceBytes: true });
+			const project = liftDocumentToUamProject(document);
+			const sessionId = randomId();
+			const session = {
+				sessionId,
+				fairyPath,
+				canonicalProjectPath,
+				canonicalPathKey,
+				lockFilePath,
+				sessionLock,
+				fileSystem,
+				project,
+				uamFidelity: await hasFullUamFidelity(document, project) ? "full" : "unsupported",
+				revision: 0,
+				lastSavedRevision: 0,
+				pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
+				pendingStaleResourceFolders: /* @__PURE__ */ new Map(),
+				pendingStaleBranchDirectories: /* @__PURE__ */ new Map(),
+				dirty: false,
+				lockHeld: true,
+				closed: false
+			};
+			this.context.sessions.set(sessionId, session);
+			this.context.sessionsByPath.set(canonicalPathKey, sessionId);
+			this.cacheService.refreshSession(session);
+			this.eventService.emit({
+				kind: "session.opened",
+				sessionId,
+				canonicalPathKey,
+				revision: session.revision
+			});
+			return success("runtime", startedAt, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		} catch (error) {
+			if (sessionLock) await sessionLock.release().catch(() => void 0);
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST") return failure("runtime", startedAt, {
+				code: "lock_conflict",
+				kind: "advisory_lock_conflict",
+				message: `Advisory lock already exists for project: ${canonicalProjectPath}`,
+				canonicalPathKey,
+				lockFilePath
+			});
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOTSUP") return failure("runtime", startedAt, {
+				...createCapabilityUnavailableError("fileSystem"),
+				message: error instanceof Error ? error.message : String(error)
+			});
+			throw error;
+		}
+	}
+	openProjectSession(input) {
+		const startedAt = Date.now();
+		const sessionId = input.sessionId ?? randomId();
+		const storage = input.storage;
+		const memoryProjectPath = `memory://${sessionId}`;
+		const canonicalProjectPath = storage?.canonicalProjectPath ?? input.canonicalProjectPath ?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || "." : memoryProjectPath);
+		const canonicalPathKey = storage?.canonicalPathKey ?? input.canonicalPathKey ?? (storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
+		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
+		if (existingSessionId) return failure("runtime", startedAt, {
+			code: "lock_conflict",
+			kind: "in_process_session_exists",
+			message: `Project is already open in this backend runtime: ${canonicalProjectPath}`,
+			canonicalPathKey,
+			holderSessionId: existingSessionId
+		});
+		const session = {
+			sessionId,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
+			canonicalProjectPath,
+			canonicalPathKey,
+			lockFilePath: "",
+			sessionLock: null,
+			fileSystem: storage?.fileSystem,
+			project: normalizeUamProject(input.project),
+			uamFidelity: "full",
+			revision: 0,
+			lastSavedRevision: 0,
+			pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
+			pendingStaleResourceFolders: /* @__PURE__ */ new Map(),
+			pendingStaleBranchDirectories: /* @__PURE__ */ new Map(),
+			dirty: false,
+			lockHeld: false,
+			closed: false
+		};
+		this.context.sessions.set(sessionId, session);
+		this.context.sessionsByPath.set(canonicalPathKey, sessionId);
+		this.cacheService.refreshSession(session);
+		this.eventService.emit({
+			kind: "session.opened",
+			sessionId,
+			canonicalPathKey,
+			revision: session.revision
+		});
+		return success("runtime", startedAt, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+	async closeSession(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("runtime", startedAt, createSessionNotFoundError(input.sessionId));
+		this.eventService.emit({
+			kind: "session.closeRequested",
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision
+		});
+		await session.sessionLock?.release().catch(() => void 0);
+		session.sessionLock = null;
+		session.lockHeld = false;
+		session.closed = true;
+		this.context.sessions.delete(session.sessionId);
+		this.context.sessionsByPath.delete(session.canonicalPathKey);
+		this.cacheService.removeSession(session.sessionId);
+		this.jobService.removeSession(session.sessionId);
+		this.eventService.emit({
+			kind: "session.closed",
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision
+		});
+		this.eventService.removeSession(session.sessionId);
+		return success("runtime", startedAt, {
+			sessionId: session.sessionId,
+			closed: true
+		}, {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
+};
+//#endregion
+//#region src/services/artifact-service.ts
+function createArtifactCapabilities() {
+	const bridge = {
+		available: false,
+		requiredHost: "node",
+		executionBoundary: "external-bridge",
+		bridgeEntrypoint: "@openfairygui/backend/node",
+		reason: "publish/restore require explicit Node-hosted filesystem and artifact execution."
+	};
+	return {
+		publish: false,
+		restore: false,
+		status: "bridge-required",
+		publishBridge: bridge,
+		restoreBridge: bridge
+	};
+}
+//#endregion
+//#region src/runtime/capabilities.ts
+const BACKEND_METHODS = [
+	"getCapabilities",
+	"openSession",
+	"openProjectSession",
+	"getSession",
+	"getProjectOutline",
+	"applyTransaction",
+	"saveSession",
+	"materializeSession",
+	"closeSession",
+	"getEvents",
+	"getJob",
+	"listJobs",
+	"cancelJob",
+	"getCacheSnapshot",
+	"refreshCache"
+];
+const ARTIFACT_BRIDGE_CAPABILITY = {
+	available: false,
+	requiredHost: "node",
+	executionBoundary: "external-bridge",
+	bridgeEntrypoint: "@openfairygui/backend/node",
+	reason: "publish/restore require explicit Node-hosted filesystem and artifact execution."
+};
+function createCapabilities() {
+	return {
+		contractVersion: BACKEND_CONTRACT_VERSION,
+		capabilitySchemaVersion: 2,
+		transactionKernelOwner: "@openfairygui/core",
+		appSeamOwner: "@openfairygui/functions",
+		runtimeOwner: "@openfairygui/backend",
+		methods: BACKEND_METHODS,
+		read: {
+			capabilitySnapshot: true,
+			sessionSnapshot: true,
+			projectOutline: true
+		},
+		authoring: {
+			applyTransaction: true,
+			saveSession: true,
+			resourceKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.resourceKinds],
+			nodeKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.nodeKinds],
+			gearKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.gearKinds],
+			transactionScope: {
+				resourceKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.resourceKinds],
+				nodeKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.nodeKinds],
+				gearKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.gearKinds]
+			},
+			unsupported: ["artifact.publish", "artifact.restore"]
+		},
+		artifact: createArtifactCapabilities(),
+		manifest: {
+			browserSafe: true,
+			rootEntrypoint: "@openfairygui/backend",
+			nodeEntrypoint: "@openfairygui/backend/node",
+			adapters: {
+				fileSystem: {
+					injected: true,
+					requiredFor: [
+						"openSession",
+						"saveSession",
+						"materializeSession"
+					]
+				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: [
+						"openProjectSession.writeback",
+						"saveSession",
+						"materializeSession"
+					],
+					adapterFactory: "createBackendStorageFileSystem"
+				},
+				host: {
+					injected: true,
+					requiredFor: ["advisoryLockMetadata"]
+				}
+			},
+			executionBoundaries: {
+				projectSession: "in-process-browser-safe",
+				fileBackedSession: "adapter-backed",
+				artifactPublish: ARTIFACT_BRIDGE_CAPABILITY,
+				artifactRestore: ARTIFACT_BRIDGE_CAPABILITY
+			},
+			diagnostics: {
+				stableCodes: true,
+				errorDiagnosticMirror: true
+			}
+		},
+		compatibilityPolicy: BACKEND_COMPATIBILITY_POLICY,
+		runtime: {
+			sessionRuntime: true,
+			advisoryLocking: true,
+			coordinatedSave: true,
+			atomicSave: false,
+			staleRevisionProtection: true,
+			pathPolicy: createRuntimePathPolicy(),
+			events: {
+				polling: true,
+				subscriptions: false,
+				retentionLimit: 1e3,
+				sequenceScope: "runtime"
+			},
+			jobs: {
+				inMemory: true,
+				cooperativeCancel: true,
+				persistent: false,
+				supportedKinds: ["cache.refresh"],
+				artifactJobs: false,
+				completedRetentionLimit: 100
+			},
+			cache: {
+				derivedReadOnly: true,
+				keyedBy: "canonicalPathKey",
+				sourceOfTruth: false,
+				refreshMethod: "refreshCache"
+			}
+		}
+	};
+}
+//#endregion
+//#region src/runtime.ts
+var BackendRuntime = class {
+	fileSystem;
+	capabilities;
+	sessions = /* @__PURE__ */ new Map();
+	sessionsByPath = /* @__PURE__ */ new Map();
+	eventsBySession = /* @__PURE__ */ new Map();
+	jobsBySession = /* @__PURE__ */ new Map();
+	cacheBySession = /* @__PURE__ */ new Map();
+	eventSequence = 0;
+	context;
+	readService;
+	runtimeService;
+	authoringService;
+	cacheService;
+	eventService;
+	jobService;
+	constructor(options = {}) {
+		this.fileSystem = options.fileSystem;
+		this.capabilities = createCapabilities();
+		this.context = {
+			fileSystem: this.fileSystem,
+			host: options.host,
+			capabilities: this.capabilities,
+			sessions: this.sessions,
+			sessionsByPath: this.sessionsByPath,
+			eventsBySession: this.eventsBySession,
+			jobsBySession: this.jobsBySession,
+			cacheBySession: this.cacheBySession,
+			nextEventSequence: () => {
+				this.eventSequence += 1;
+				return this.eventSequence;
+			}
+		};
+		this.readService = new ReadService(this.context);
+		this.eventService = new EventService(this.context);
+		this.cacheService = new CacheService(this.context);
+		this.jobService = new JobService(this.context, this.cacheService, this.eventService);
+		this.runtimeService = new RuntimeService(this.context, this.cacheService, this.eventService, this.jobService);
+		this.authoringService = new AuthoringService(this.context, this.cacheService, this.eventService);
+	}
+	getCapabilities() {
+		return this.readService.getCapabilities();
+	}
+	async openSession(input) {
+		return this.runtimeService.openSession(input);
+	}
+	openProjectSession(input) {
+		return this.runtimeService.openProjectSession(input);
+	}
+	getSession(input) {
+		return this.readService.getSession(input);
+	}
+	getProjectOutline(input) {
+		return this.readService.getProjectOutline(input);
+	}
+	async applyTransaction(input) {
+		return this.authoringService.applyTransaction(input);
+	}
+	async saveSession(input) {
+		return this.authoringService.saveSession(input);
+	}
+	async materializeSession(input) {
+		return this.authoringService.materializeSession(input);
+	}
+	async closeSession(input) {
+		return this.runtimeService.closeSession(input);
+	}
+	getEvents(input) {
+		return this.eventService.getEvents(input);
+	}
+	getJob(input) {
+		return this.jobService.getJob(input);
+	}
+	listJobs(input) {
+		return this.jobService.listJobs(input);
+	}
+	cancelJob(input) {
+		return this.jobService.cancelJob(input);
+	}
+	getCacheSnapshot(input) {
+		return this.cacheService.getCacheSnapshot(input);
+	}
+	refreshCache(input) {
+		return this.jobService.refreshCache(input);
+	}
+};
+//#endregion
 //#region src/storage.ts
 var StorageFileStat = class {
 	constructor(kind) {
@@ -16,6 +1652,42 @@ function createPathError(code, message) {
 	error.code = code;
 	return error;
 }
+function getWebLockManager() {
+	if (typeof navigator === "undefined") return null;
+	const lockManager = navigator.locks;
+	return lockManager && typeof lockManager.request === "function" ? lockManager : null;
+}
+function acquireWebSessionLock(lockManager, lockName) {
+	return new Promise((resolve, reject) => {
+		let releasePlatformLock = () => void 0;
+		const held = new Promise((release) => {
+			releasePlatformLock = release;
+		});
+		lockManager.request(lockName, {
+			mode: "exclusive",
+			ifAvailable: true
+		}, async (lock) => {
+			if (!lock) {
+				reject(createPathError("EEXIST", `Browser session lock is already held: ${lockName}`));
+				return;
+			}
+			let released = false;
+			resolve({
+				writeMetadata() {
+					return Promise.resolve();
+				},
+				release() {
+					if (!released) {
+						released = true;
+						releasePlatformLock();
+					}
+					return Promise.resolve();
+				}
+			});
+			await held;
+		}).catch(reject);
+	});
+}
 function normalizeStoragePath(value) {
 	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
 	const absolute = normalized.startsWith("/");
@@ -70,7 +1742,8 @@ async function inferStat(storage, filePath) {
 	}
 }
 function createBackendStorageFileSystem(storage) {
-	const lockedPaths = /* @__PURE__ */ new Set();
+	if (typeof storage.unlink !== "function") throw createPathError("ENOTSUP", "Storage adapter must provide unlink() for project resource lifecycle writes.");
+	if (typeof storage.rmdir !== "function") throw createPathError("ENOTSUP", "Storage adapter must provide rmdir() for project resource folder lifecycle writes.");
 	const fileSystem = {
 		stat(filePath) {
 			return inferStat(storage, fileSystem.resolve(filePath));
@@ -106,29 +1779,18 @@ function createBackendStorageFileSystem(storage) {
 			const resolved = fileSystem.resolve(filePath);
 			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
 		},
-		async openExclusive(filePath) {
-			const resolved = fileSystem.resolve(filePath);
-			if (storage.openExclusive) return storage.openExclusive(resolved);
-			if (lockedPaths.has(resolved) || await fileSystem.exists(resolved)) throw createPathError("EEXIST", `Storage path already exists: ${resolved}`);
-			lockedPaths.add(resolved);
-			let closed = false;
-			return {
-				async writeFile(content) {
-					if (closed) throw createPathError("EBADF", `Storage lock handle is closed: ${resolved}`);
-					await fileSystem.mkdir(fileSystem.dirname(resolved), { recursive: true });
-					await storage.writeFile(resolved, content);
-				},
-				async close() {
-					closed = true;
-					lockedPaths.delete(resolved);
-				}
-			};
+		async acquireSessionLock(lockPath) {
+			const resolved = fileSystem.resolve(lockPath);
+			if (storage.acquireSessionLock) return storage.acquireSessionLock(resolved);
+			const lockManager = getWebLockManager();
+			if (!lockManager) throw createPathError("ENOTSUP", "Browser openSession requires Web Locks or BackendAsyncStorageAdapter.acquireSessionLock().");
+			return acquireWebSessionLock(lockManager, `@openfairygui/backend:${resolved}`);
 		},
 		unlink(filePath) {
-			const resolved = fileSystem.resolve(filePath);
-			lockedPaths.delete(resolved);
-			if (storage.unlink) return storage.unlink(resolved);
-			throw createPathError("ENOTSUP", "Storage adapter does not provide unlink().");
+			return storage.unlink(fileSystem.resolve(filePath));
+		},
+		rmdir(dirPath) {
+			return storage.rmdir(fileSystem.resolve(dirPath));
 		},
 		join(...paths) {
 			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);