@openfairygui/backend 0.2.0-alpha.0

package/dist/index.mjs

@@ -0,0 +1,1091 @@
+import { NodeIO, ProjectWriter, UAM_SUPPORTED_MATERIALIZATION_SCOPE, materializeUamProject, readProjectAsUam } from "@openfairygui/core";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { applyUamTransactionApp } from "@openfairygui/functions";
+//#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/artifact-service.ts
+function createArtifactCapabilities() {
+	return {
+		publish: false,
+		restore: false,
+		status: "deferred"
+	};
+}
+//#endregion
+//#region src/services/context.ts
+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) {
+	return {
+		ok: false,
+		meta: createMeta(stage, startedAt, options),
+		error,
+		session
+	};
+}
+//#endregion
+//#region src/services/snapshot-utils.ts
+function cloneJsonValue(value) {
+	if (value === void 0 || value === null) return value;
+	return JSON.parse(JSON.stringify(value));
+}
+function cloneEventSnapshot(event) {
+	return {
+		...event,
+		diagnostics: event.diagnostics.map((diagnostic) => ({ ...diagnostic })),
+		payload: cloneJsonValue(event.payload)
+	};
+}
+function cloneJobSnapshot(job) {
+	return {
+		...job,
+		diagnostics: job.diagnostics.map((diagnostic) => ({ ...diagnostic })),
+		progress: job.progress ? { ...job.progress } : void 0,
+		result: cloneJsonValue(job.result),
+		error: cloneJsonValue(job.error)
+	};
+}
+function cloneCacheEntrySnapshot(entry) {
+	return {
+		...entry,
+		summary: {
+			...entry.summary,
+			diagnostics: entry.summary.diagnostics.map((diagnostic) => ({ ...diagnostic }))
+		}
+	};
+}
+function cloneCapabilitiesSnapshot(capabilities) {
+	return cloneJsonValue(capabilities);
+}
+//#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,
+		lockHeld: session.lockHeld,
+		capabilities: cloneCapabilitiesSnapshot(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 createWriterFileSystem(fileSystem, committedPaths, failedPaths) {
+	async function trackWrite(targetPath, fn) {
+		try {
+			const result = await fn();
+			committedPaths.push(targetPath);
+			return result;
+		} catch (error) {
+			failedPaths.push(targetPath);
+			throw error;
+		}
+	}
+	return {
+		async readFile(filePath) {
+			return fileSystem.readFile(filePath);
+		},
+		async readFileRaw(filePath) {
+			return fileSystem.readFileRaw(filePath);
+		},
+		async writeFile(filePath, content) {
+			await trackWrite(filePath, async () => {
+				await fileSystem.mkdir(fileSystem.dirname(filePath), { recursive: true });
+				await fileSystem.writeFile(filePath, content);
+			});
+		},
+		async writeFileRaw(filePath, data) {
+			await trackWrite(filePath, async () => {
+				await fileSystem.mkdir(fileSystem.dirname(filePath), { recursive: true });
+				await fileSystem.writeFileRaw(filePath, data);
+			});
+		},
+		async mkdir(dirPath) {
+			await fileSystem.mkdir(dirPath, { recursive: true });
+		},
+		async 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);
+		}
+	};
+}
+var AuthoringService = class {
+	constructor(context, cacheService, eventService) {
+		this.context = context;
+		this.cacheService = cacheService;
+		this.eventService = eventService;
+	}
+	async applyTransaction(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 = applyUamTransactionApp({
+			project: session.project,
+			operations: input.operations
+		});
+		if (result.ok === false) {
+			this.eventService.emit({
+				kind: "transaction.rejected",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				diagnostics: result.error.issues?.map((issue) => ({
+					code: result.error.code,
+					message: issue.message,
+					severity: "error"
+				})) ?? []
+			});
+			return failure("authoring", startedAt, result.error, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		}
+		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) {
+		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 targetViolation = await validateSaveTarget(this.context.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
+		});
+		const committedPaths = [];
+		const failedPaths = [];
+		this.eventService.emit({
+			kind: "save.started",
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			revision: session.revision
+		});
+		try {
+			await new ProjectWriter(createWriterFileSystem(this.context.fileSystem, committedPaths, failedPaths)).write(materializeUamProject(session.project), session.fairyPath);
+			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
+			});
+		}
+	}
+};
+//#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 ? [cloneCacheEntrySnapshot(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 < 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(cloneEventSnapshot),
+			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, cloneJobSnapshot(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, cloneJobSnapshot(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(cloneJobSnapshot) }, {
+			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
+		});
+		return success("runtime", startedAt, cloneJobSnapshot(this.cancelRefreshJob(session.sessionId, job)), {
+			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
+var ReadService = class {
+	constructor(context) {
+		this.context = context;
+	}
+	getCapabilities() {
+		return success("read", Date.now(), cloneCapabilitiesSnapshot(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
+		});
+	}
+};
+//#endregion
+//#region src/services/runtime-service.ts
+function randomId() {
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+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();
+		const { fairyPath, canonicalProjectPath, canonicalPathKey } = await resolveCanonicalProjectRoot(this.context.fileSystem, input.projectPath);
+		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
+		const lockFilePath = this.context.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 advisoryLock = null;
+		try {
+			advisoryLock = await this.context.fileSystem.openExclusive(lockFilePath);
+			await advisoryLock.writeFile(JSON.stringify({
+				pid: process.pid,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				canonicalPathKey
+			}));
+			await advisoryLock.close();
+			const project = await readProjectAsUam(new NodeIO(), fairyPath);
+			const sessionId = randomId();
+			const session = {
+				sessionId,
+				fairyPath,
+				canonicalProjectPath,
+				canonicalPathKey,
+				lockFilePath,
+				project,
+				revision: 0,
+				lastSavedRevision: 0,
+				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 (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 (advisoryLock) {
+				await advisoryLock.close().catch(() => void 0);
+				await this.context.fileSystem.unlink(lockFilePath).catch(() => void 0);
+			}
+			throw error;
+		}
+	}
+	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 this.context.fileSystem.unlink(session.lockFilePath).catch(() => void 0);
+		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/runtime.ts
+const BACKEND_METHODS = [
+	"getCapabilities",
+	"openSession",
+	"getSession",
+	"applyTransaction",
+	"saveSession",
+	"closeSession",
+	"getEvents",
+	"getJob",
+	"listJobs",
+	"cancelJob",
+	"getCacheSnapshot",
+	"refreshCache"
+];
+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
+		},
+		authoring: {
+			applyTransaction: true,
+			saveSession: true,
+			resourceKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.resourceKinds],
+			nodeKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.nodeKinds],
+			gearKinds: [...UAM_SUPPORTED_MATERIALIZATION_SCOPE.gearKinds],
+			unsupported: ["artifact.publish", "artifact.restore"]
+		},
+		artifact: createArtifactCapabilities(),
+		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"
+			}
+		}
+	};
+}
+function createNodeBackendFileSystem() {
+	return {
+		stat(filePath) {
+			return fs.stat(filePath);
+		},
+		readdir(dirPath) {
+			return fs.readdir(dirPath);
+		},
+		readFile(filePath) {
+			return fs.readFile(filePath, "utf-8");
+		},
+		async readFileRaw(filePath) {
+			const buffer = await fs.readFile(filePath);
+			return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+		},
+		writeFile(filePath, content) {
+			return fs.writeFile(filePath, content, "utf-8");
+		},
+		writeFileRaw(filePath, data) {
+			return fs.writeFile(filePath, data);
+		},
+		async mkdir(dirPath, options) {
+			await fs.mkdir(dirPath, { recursive: options?.recursive ?? false });
+		},
+		async resolvePath(filePath) {
+			try {
+				return await fs.realpath(filePath);
+			} catch {
+				return path.resolve(filePath);
+			}
+		},
+		async openExclusive(filePath) {
+			const handle = await fs.open(filePath, "wx");
+			return {
+				writeFile(content) {
+					return handle.writeFile(content, "utf-8");
+				},
+				close() {
+					return handle.close();
+				}
+			};
+		},
+		unlink(filePath) {
+			return fs.unlink(filePath);
+		},
+		join(...paths) {
+			return path.join(...paths);
+		},
+		dirname(filePath) {
+			return path.dirname(filePath);
+		},
+		resolve(...paths) {
+			return path.resolve(...paths);
+		}
+	};
+}
+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 ?? createNodeBackendFileSystem();
+		this.capabilities = createCapabilities();
+		this.context = {
+			fileSystem: this.fileSystem,
+			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);
+	}
+	getSession(input) {
+		return this.readService.getSession(input);
+	}
+	async applyTransaction(input) {
+		return this.authoringService.applyTransaction(input);
+	}
+	async saveSession(input) {
+		return this.authoringService.saveSession(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
+export { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, BackendRuntime, createNodeBackendFileSystem };