@openfairygui/backend 0.2.0-alpha.13 → 0.2.0-alpha.15

package/dist/{runtime-DFatY9W0.mjs → runtime-CxH7aT_v.mjs}

@@ -1,4 +1,4 @@
-import { UAM_SUPPORTED_MATERIALIZATION_SCOPE, UAM_SUPPORTED_TRANSACTION_SCOPE, liftDocumentToUamProject, materializeUamProject, normalizeUamProject, validateUamProject } from "@openfairygui/core/uam";
+import { UAM_SUPPORTED_MATERIALIZATION_SCOPE, UAM_SUPPORTED_TRANSACTION_SCOPE, commitUamProjectSourcePaths, liftDocumentToUamProject, materializeUamProject, normalizeUamProject, validateUamProject } from "@openfairygui/core/uam";
 import { ProjectReader, ProjectWriter } from "@openfairygui/core/project-io";
 import { applyUamTransactionApp } from "@openfairygui/functions/uam";
 //#region src/contracts.ts
@@ -179,6 +179,7 @@ function toSessionSnapshot(session, capabilities) {
 		revision: session.revision,
 		lastSavedRevision: session.lastSavedRevision,
 		dirty: session.dirty,
+		uamFidelity: session.uamFidelity,
 		lockHeld: session.lockHeld,
 		capabilities: cloneCapabilitiesSnapshot(capabilities)
 	};
@@ -251,9 +252,45 @@ function createWriterFileSystem(fileSystem, committedPaths, failedPaths) {
 		},
 		dirname(filePath) {
 			return fileSystem.dirname(filePath);
+		},
+		async unlink(filePath) {
+			await trackWrite(filePath, () => fileSystem.unlink(filePath));
 		}
 	};
 }
+function projectAssetSourceFiles(project) {
+	const result = /* @__PURE__ */ new Map();
+	for (const pkg of project.packages) for (const resource of pkg.resources) {
+		if (resource.kind === "component") continue;
+		const fileName = resource.fileName ?? resource.file ?? "";
+		if (!fileName) continue;
+		result.set(`${pkg.id}/${resource.id}`, {
+			packageName: pkg.name,
+			branch: resource.branch,
+			path: resource.path,
+			fileName
+		});
+	}
+	return result;
+}
+function sourceFileKey(source) {
+	return [
+		source.branch,
+		source.packageName,
+		source.path,
+		source.fileName
+	].join("\0");
+}
+function recordStaleResourceSources(session, previousProject, nextProject) {
+	if (!session.fileSystem) return;
+	const previousSources = projectAssetSourceFiles(previousProject);
+	const nextSourceKeys = new Set([...projectAssetSourceFiles(nextProject).values()].map(sourceFileKey));
+	for (const source of previousSources.values()) {
+		const key = sourceFileKey(source);
+		if (!nextSourceKeys.has(key)) session.pendingStaleSourceFiles.set(key, source);
+	}
+	for (const key of nextSourceKeys) session.pendingStaleSourceFiles.delete(key);
+}
 function toBackendDiagnostics(error) {
 	return error.diagnostics.length > 0 ? error.diagnostics.map((diagnostic) => ({ ...diagnostic })) : [{
 		code: error.code,
@@ -272,6 +309,14 @@ function createCapabilityUnavailableError$1(message) {
 		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",
@@ -303,12 +348,32 @@ function storageCanonicalTarget(input) {
 	};
 }
 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) {
+		return this.runSessionExclusive(input.sessionId, () => this.applyTransactionExclusive(input));
+	}
+	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));
@@ -343,6 +408,7 @@ var AuthoringService = class {
 				diagnostics
 			});
 		}
+		recordStaleResourceSources(session, session.project, result.project);
 		session.project = result.project;
 		session.revision += 1;
 		session.dirty = true;
@@ -374,10 +440,13 @@ var AuthoringService = class {
 			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 = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		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
@@ -395,6 +464,10 @@ var AuthoringService = class {
 			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({
@@ -404,7 +477,10 @@ var AuthoringService = class {
 			revision: session.revision
 		});
 		try {
-			await new ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write(materializeUamProject(session.project), session.fairyPath);
+			await new ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write(materializeUamProject(session.project), session.fairyPath, { staleSourceFiles: [...session.pendingStaleSourceFiles.values()] });
+			session.fileSystem ??= fileSystem;
+			session.pendingStaleSourceFiles.clear();
+			commitUamProjectSourcePaths(session.project);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;
 			const cacheEntry = this.cacheService.refreshSession(session);
@@ -450,6 +526,9 @@ var AuthoringService = class {
 		}
 	}
 	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));
@@ -482,6 +561,10 @@ var AuthoringService = class {
 				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",
@@ -528,7 +611,12 @@ var AuthoringService = class {
 			revision: session.revision
 		});
 		try {
-			await new ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths)).write(document, fairyPath);
+			const writer = new ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths));
+			const isSessionStorageTarget = fileSystem === session.fileSystem && fairyPath === session.fairyPath;
+			await writer.write(document, fairyPath, { staleSourceFiles: isSessionStorageTarget ? [...session.pendingStaleSourceFiles.values()] : [] });
+			if (isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (storageTarget && !isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (isSessionStorageTarget || storageTarget) commitUamProjectSourcePaths(session.project);
 			if (storageTarget) {
 				this.context.sessionsByPath.delete(session.canonicalPathKey);
 				session.fileSystem = storageTarget.fileSystem;
@@ -1055,6 +1143,68 @@ function createProjectReaderFileSystem(fileSystem) {
 		}
 	};
 }
+function createCaptureFileSystem(files) {
+	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() {},
+		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;
+}
+async function hasFullUamFidelity(document, project) {
+	const sourceFiles = /* @__PURE__ */ new Map();
+	const materializedFiles = /* @__PURE__ */ new Map();
+	try {
+		await Promise.all([new ProjectWriter(createCaptureFileSystem(sourceFiles)).write(document, "Project.fairy"), new ProjectWriter(createCaptureFileSystem(materializedFiles)).write(materializeUamProject(project), "Project.fairy")]);
+	} catch {
+		return false;
+	}
+	return capturedFilesEqual(sourceFiles, materializedFiles);
+}
 var RuntimeService = class {
 	constructor(context, cacheService, eventService, jobService) {
 		this.context = context;
@@ -1089,7 +1239,8 @@ var RuntimeService = class {
 				canonicalPathKey
 			}));
 			await advisoryLock.close();
-			const project = liftDocumentToUamProject(await new ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath));
+			const document = await new ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath, { hydrateResourceBytes: true });
+			const project = liftDocumentToUamProject(document);
 			const sessionId = randomId();
 			const session = {
 				sessionId,
@@ -1099,8 +1250,10 @@ var RuntimeService = class {
 				lockFilePath,
 				fileSystem,
 				project,
+				uamFidelity: await hasFullUamFidelity(document, project) ? "full" : "unsupported",
 				revision: 0,
 				lastSavedRevision: 0,
+				pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
 				dirty: false,
 				lockHeld: true,
 				closed: false
@@ -1156,8 +1309,10 @@ var RuntimeService = class {
 			lockFilePath: "",
 			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
+			uamFidelity: "full",
 			revision: 0,
 			lastSavedRevision: 0,
+			pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
 			dirty: false,
 			lockHeld: false,
 			closed: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/backend",
-  "version": "0.2.0-alpha.13",
+  "version": "0.2.0-alpha.15",
   "description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -52,8 +52,8 @@
     "runtime"
   ],
   "dependencies": {
-    "@openfairygui/core": "0.2.0-alpha.13",
-    "@openfairygui/functions": "0.2.0-alpha.13"
+    "@openfairygui/core": "0.2.0-alpha.15",
+    "@openfairygui/functions": "0.2.0-alpha.15"
   },
   "devDependencies": {
     "ava": "^7.0.0",

package/src/index.ts

@@ -1,13 +1,21 @@
 export {
-	BackendRuntime,
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_COMPATIBILITY_POLICY,
+	BACKEND_CONTRACT_VERSION,
+	type BackendDiagnostic,
+	type BackendMessage,
+	type BackendResponseMeta,
+	type BackendStage,
+} from './contracts.js';
+export {
 	type AdvisoryLockConflictError,
 	type ApplySessionTransactionInput,
 	type BackendArtifactBridgeCapability,
 	type BackendCacheEntry,
 	type BackendCacheSnapshot,
+	type BackendCapabilities,
 	type BackendCapabilityManifest,
 	type BackendCapabilityUnavailableError,
-	type BackendCapabilities,
 	type BackendError,
 	type BackendEvent,
 	type BackendEventKind,
@@ -16,6 +24,7 @@ export {
 	type BackendFileStat,
 	type BackendFileSystem,
 	type BackendHostAdapter,
+	type BackendJobErrors,
 	type BackendJobKind,
 	type BackendJobListSnapshot,
 	type BackendJobListStatusFilter,
@@ -24,11 +33,12 @@ export {
 	type BackendJobProgress,
 	type BackendJobSnapshot,
 	type BackendJobStatus,
-	type BackendJobErrors,
+	type BackendProjectSessionStorage,
 	type BackendResult,
+	BackendRuntime,
+	type BackendRuntimeOptions,
 	type BackendSessionSnapshot,
 	type BackendSuccess,
-	type BackendRuntimeOptions,
 	type CacheRefreshFailedError,
 	type CancelJobInput,
 	type EventCursorInvalidError,
@@ -43,25 +53,16 @@ export {
 	type MaterializeValidationFailedError,
 	type MaterializeWriteFailedError,
 	type OpenProjectSessionInput,
-	type BackendProjectSessionStorage,
 	type RefreshCacheInput,
-	type SaveSessionInput,
 	type SavePartialFailureError,
+	type SaveSessionInput,
 	type SessionNotFoundError,
 	type SessionStaleWriteError,
+	type UamFidelityUnsupportedError,
 } from './runtime.js';
 export {
-	createBackendStorageFileSystem,
 	type BackendAsyncStorageAdapter,
 	type BackendStorageFileSystem,
 	type BackendStorageStatLike,
+	createBackendStorageFileSystem,
 } from './storage.js';
-export {
-	type BackendDiagnostic,
-	type BackendMessage,
-	type BackendResponseMeta,
-	type BackendStage,
-	BACKEND_CAPABILITY_SCHEMA_VERSION,
-	BACKEND_COMPATIBILITY_POLICY,
-	BACKEND_CONTRACT_VERSION,
-} from './contracts.js';

package/src/runtime.ts

@@ -181,6 +181,7 @@ export interface BackendSessionSnapshot {
 	revision: number;
 	lastSavedRevision: number;
 	dirty: boolean;
+	uamFidelity: 'full' | 'unsupported';
 	lockHeld: boolean;
 	capabilities: BackendCapabilities;
 }
@@ -255,6 +256,13 @@ export interface SavePartialFailureError {
 	diskMayBePartiallyUpdated: true;
 }
 
+export interface UamFidelityUnsupportedError {
+	code: 'uam_fidelity_unsupported';
+	message: string;
+	sessionId: string;
+	canonicalPathKey: string;
+}
+
 export interface MaterializeValidationFailedError {
 	code: 'materialize_validation_failed';
 	message: string;
@@ -458,6 +466,7 @@ export type BackendError =
 	| InProcessLockConflictError
 	| AdvisoryLockConflictError
 	| SavePartialFailureError
+	| UamFidelityUnsupportedError
 	| MaterializeValidationFailedError
 	| MaterializeWriteFailedError
 	| PathPolicyViolationError
@@ -704,12 +713,15 @@ export class BackendRuntime {
 		return this.authoringService.applyTransaction(input);
 	}
 
-	public async saveSession(input: SaveSessionInput): Promise<
+	public async saveSession(
+		input: SaveSessionInput,
+	): Promise<
 		BackendResult<
 			BackendSessionSnapshot | MaterializeSessionSnapshot,
 			| SessionNotFoundError
 			| SessionStaleWriteError
 			| SavePartialFailureError
+			| UamFidelityUnsupportedError
 			| MaterializeValidationFailedError
 			| MaterializeWriteFailedError
 			| PathPolicyViolationError
@@ -720,11 +732,14 @@ export class BackendRuntime {
 		return this.authoringService.saveSession(input);
 	}
 
-	public async materializeSession(input: MaterializeSessionInput): Promise<
+	public async materializeSession(
+		input: MaterializeSessionInput,
+	): Promise<
 		BackendResult<
 			MaterializeSessionSnapshot,
 			| SessionNotFoundError
 			| SessionStaleWriteError
+			| UamFidelityUnsupportedError
 			| MaterializeValidationFailedError
 			| MaterializeWriteFailedError
 			| PathPolicyViolationError