@openfairygui/backend 0.2.0-alpha.0 → 0.2.0-alpha.10

package/dist/index.mjs

@@ -1,1091 +1,146 @@
-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"
+import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-DFatY9W0.mjs";
+//#region src/storage.ts
+var StorageFileStat = class {
+	constructor(kind) {
+		this.kind = kind;
+	}
+	isFile() {
+		return this.kind === "file";
+	}
+	isDirectory() {
+		return this.kind === "directory";
+	}
 };
-//#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);
+function createPathError(code, message) {
+	const error = new Error(message);
+	error.code = code;
+	return error;
+}
+function normalizeStoragePath(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
+	const absolute = normalized.startsWith("/");
+	const rawSegments = normalized.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("..");
+			if (segments.length > 0) segments.pop();
 			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;
+	if (absolute) return joined ? `/${joined}` : "/";
+	return joined || ".";
+}
+function joinStoragePath(...paths) {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join("/"));
+}
+function dirnameStoragePath(filePath) {
+	const normalized = normalizeStoragePath(filePath);
+	if (normalized === "/" || normalized === ".") return ".";
+	const absolute = normalized.startsWith("/");
+	const parts = normalized.split("/").filter((part) => part.length > 0);
+	parts.pop();
+	if (parts.length === 0) return absolute ? "/" : ".";
+	return `${absolute ? "/" : ""}${parts.join("/")}`;
+}
+function statFromLike(stat) {
+	if (typeof stat.isFile === "function" && typeof stat.isDirectory === "function") return stat;
+	const kind = stat.kind ?? stat.type;
+	if (kind === "file" || kind === "directory") return new StorageFileStat(kind);
+	throw createPathError("EINVAL", "Storage stat must provide kind/type or isFile()/isDirectory().");
+}
+async function inferStat(storage, filePath) {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat("directory");
+	} catch {}
+	try {
+		await storage.readFileRaw(filePath);
+		return new StorageFileStat("file");
+	} catch {
 		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;
+			await storage.readFile(filePath);
+			return new StorageFileStat("file");
+		} catch {
+			throw createPathError("ENOENT", `Storage path not found: ${filePath}`);
 		}
 	}
-	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 {
+function createBackendStorageFileSystem(storage) {
+	const lockedPaths = /* @__PURE__ */ new Set();
+	const fileSystem = {
 		stat(filePath) {
-			return fs.stat(filePath);
+			return inferStat(storage, fileSystem.resolve(filePath));
 		},
 		readdir(dirPath) {
-			return fs.readdir(dirPath);
+			return storage.readdir(fileSystem.resolve(dirPath));
 		},
 		readFile(filePath) {
-			return fs.readFile(filePath, "utf-8");
+			return storage.readFile(fileSystem.resolve(filePath));
 		},
-		async readFileRaw(filePath) {
-			const buffer = await fs.readFile(filePath);
-			return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+		readFileRaw(filePath) {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
 		},
 		writeFile(filePath, content) {
-			return fs.writeFile(filePath, content, "utf-8");
+			return storage.writeFile(fileSystem.resolve(filePath), content);
 		},
 		writeFileRaw(filePath, data) {
-			return fs.writeFile(filePath, data);
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
 		},
-		async mkdir(dirPath, options) {
-			await fs.mkdir(dirPath, { recursive: options?.recursive ?? false });
+		mkdir(dirPath, options) {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
 		},
-		async resolvePath(filePath) {
+		async exists(filePath) {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
 			try {
-				return await fs.realpath(filePath);
+				await fileSystem.stat(filePath);
+				return true;
 			} catch {
-				return path.resolve(filePath);
+				return false;
 			}
 		},
+		resolvePath(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
+		},
 		async openExclusive(filePath) {
-			const handle = await fs.open(filePath, "wx");
+			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 {
-				writeFile(content) {
-					return handle.writeFile(content, "utf-8");
+				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);
 				},
-				close() {
-					return handle.close();
+				async close() {
+					closed = true;
+					lockedPaths.delete(resolved);
 				}
 			};
 		},
 		unlink(filePath) {
-			return fs.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().");
 		},
 		join(...paths) {
-			return path.join(...paths);
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
 		},
 		dirname(filePath) {
-			return path.dirname(filePath);
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
 		},
 		resolve(...paths) {
-			return path.resolve(...paths);
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
 		}
 	};
+	return fileSystem;
 }
-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 };
+export { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, BackendRuntime, createBackendStorageFileSystem };