@openfairygui/backend 0.2.0-alpha.14 → 0.2.0-alpha.16

package/src/services/authoring-service.ts

@@ -1,9 +1,13 @@
-import { ProjectWriter, type FileSystem, type ProjectSourceFile } from '@openfairygui/core/project-io';
-import { commitUamProjectSourcePaths, materializeUamProject, validateUamProject, type UamProject } from '@openfairygui/core/uam';
-import { applyUamTransactionApp, type ApplyUamTransactionAppError } from '@openfairygui/functions/uam';
-import type { CacheService } from './cache-service.js';
-import { failure, success, type BackendContext } from './context.js';
-import type { EventService } from './event-service.js';
+import { type FileSystem, type ProjectSourceFile, ProjectWriter } from '@openfairygui/core/project-io';
+import {
+	commitUamProjectSourcePaths,
+	materializeUamProject,
+	type UamProject,
+	validateUamProject,
+} from '@openfairygui/core/uam';
+import { type ApplyUamTransactionAppError, applyUamTransactionApp } from '@openfairygui/functions/uam';
+import type { BackendDiagnostic } from '../contracts.js';
+import { normalizeComparablePath, type PathPolicyViolationError, validateSaveTarget } from '../path-policy.js';
 import type {
 	ApplySessionTransactionInput,
 	BackendCapabilityUnavailableError,
@@ -15,13 +19,15 @@ import type {
 	MaterializeSessionSnapshot,
 	MaterializeValidationFailedError,
 	MaterializeWriteFailedError,
-	SaveSessionInput,
 	SavePartialFailureError,
+	SaveSessionInput,
 	SessionNotFoundError,
 	SessionStaleWriteError,
+	UamFidelityUnsupportedError,
 } from '../runtime.js';
-import type { BackendDiagnostic } from '../contracts.js';
-import { normalizeComparablePath, validateSaveTarget, type PathPolicyViolationError } from '../path-policy.js';
+import type { CacheService } from './cache-service.js';
+import { type BackendContext, failure, success } from './context.js';
+import type { EventService } from './event-service.js';
 import { createSessionNotFoundError, createStaleWriteError, toSessionSnapshot } from './session-utils.js';
 
 function createWriterFileSystem(
@@ -85,17 +91,36 @@ function createWriterFileSystem(
 	};
 }
 
-function projectAssetSourceFiles(project: UamProject): Map<string, ProjectSourceFile> {
+function projectSourceFiles(project: UamProject): Map<string, ProjectSourceFile> {
 	const result = new Map<string, ProjectSourceFile>();
 	for (const pkg of project.packages) {
+		result.set(`${pkg.id}/package.xml`, {
+			packageName: pkg.name,
+			branch: '',
+			path: '',
+			fileName: 'package.xml',
+		});
+		const branches = new Set<string>();
 		for (const resource of pkg.resources) {
-			if (resource.kind === 'component') continue;
-			const fileName = resource.fileName ?? resource.file ?? '';
+			if (resource.branch) branches.add(resource.branch);
+			const fileName = resource.kind === 'component'
+				? `${resource.name}.xml`
+				: resource.fileName ?? resource.file ?? '';
 			if (!fileName) continue;
-			result.set(
-				`${pkg.id}/${resource.id}`,
-				{ packageName: pkg.name, branch: resource.branch, path: resource.path, fileName },
-			);
+			result.set(`${pkg.id}/${resource.id}`, {
+				packageName: pkg.name,
+				branch: resource.branch,
+				path: resource.path,
+				fileName,
+			});
+		}
+		for (const branch of branches) {
+			result.set(`${pkg.id}/branch/${branch}`, {
+				packageName: pkg.name,
+				branch,
+				path: '',
+				fileName: 'package_branch.xml',
+			});
 		}
 	}
 	return result;
@@ -105,14 +130,14 @@ function sourceFileKey(source: ProjectSourceFile): string {
 	return [source.branch, source.packageName, source.path, source.fileName].join('\0');
 }
 
-function recordStaleResourceSources(
+function recordStaleProjectFiles(
 	session: Parameters<typeof toSessionSnapshot>[0],
 	previousProject: UamProject,
 	nextProject: UamProject,
 ): void {
 	if (!session.fileSystem) return;
-	const previousSources = projectAssetSourceFiles(previousProject);
-	const nextSourceKeys = new Set([...projectAssetSourceFiles(nextProject).values()].map(sourceFileKey));
+	const previousSources = projectSourceFiles(previousProject);
+	const nextSourceKeys = new Set([...projectSourceFiles(nextProject).values()].map(sourceFileKey));
 	for (const source of previousSources.values()) {
 		const key = sourceFileKey(source);
 		if (!nextSourceKeys.has(key)) session.pendingStaleSourceFiles.set(key, source);
@@ -126,15 +151,15 @@ function toBackendDiagnostics(error: ApplyUamTransactionAppError): BackendDiagno
 	return error.diagnostics.length > 0
 		? error.diagnostics.map((diagnostic) => ({ ...diagnostic }))
 		: [
-			{
-				code: error.code,
-				message: error.message,
-				severity: 'error',
-				operationKind: error.operationKind,
-				opIndex: error.opIndex,
-				opId: error.opId,
-			},
-		];
+				{
+					code: error.code,
+					message: error.message,
+					severity: 'error',
+					operationKind: error.operationKind,
+					opIndex: error.opIndex,
+					opId: error.opId,
+				},
+			];
 }
 
 function createCapabilityUnavailableError(message: string): BackendCapabilityUnavailableError {
@@ -146,6 +171,17 @@ function createCapabilityUnavailableError(message: string): BackendCapabilityUna
 	};
 }
 
+function createUamFidelityUnsupportedError(
+	session: Parameters<typeof toSessionSnapshot>[0],
+): UamFidelityUnsupportedError {
+	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: Parameters<typeof validateUamProject>[0]): BackendDiagnostic[] {
 	const issues = validateUamProject(sessionProject);
 	return issues.map((issue) => ({
@@ -195,12 +231,31 @@ function storageCanonicalTarget(input: NonNullable<MaterializeSessionInput['stor
 }
 
 export class AuthoringService {
+	private readonly sessionOperations = new Map<string, Promise<void>>();
+
 	public constructor(
 		private readonly context: BackendContext,
 		private readonly cacheService: CacheService,
 		private readonly eventService: EventService,
 	) {}
 
+	private async runSessionExclusive<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
+		const previous = this.sessionOperations.get(sessionId) ?? Promise.resolve();
+		let release = (): void => undefined;
+		const current = new Promise<void>((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);
+		}
+	}
+
 	public async applyTransaction(
 		input: ApplySessionTransactionInput,
 	): Promise<
@@ -208,6 +263,17 @@ export class AuthoringService {
 			BackendSessionSnapshot,
 			SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError
 		>
+	> {
+		return this.runSessionExclusive(input.sessionId, () => this.applyTransactionExclusive(input));
+	}
+
+	private async applyTransactionExclusive(
+		input: ApplySessionTransactionInput,
+	): Promise<
+		BackendResult<
+			BackendSessionSnapshot,
+			SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError
+		>
 	> {
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
@@ -259,7 +325,7 @@ export class AuthoringService {
 			);
 		}
 
-		recordStaleResourceSources(session, session.project, result.project);
+		recordStaleProjectFiles(session, session.project, result.project);
 		session.project = result.project;
 		session.revision += 1;
 		session.dirty = true;
@@ -284,12 +350,15 @@ export class AuthoringService {
 		});
 	}
 
-	public async saveSession(input: SaveSessionInput): Promise<
+	public async saveSession(
+		input: SaveSessionInput,
+	): Promise<
 		BackendResult<
 			BackendSessionSnapshot | MaterializeSessionSnapshot,
 			| SessionNotFoundError
 			| SessionStaleWriteError
 			| SavePartialFailureError
+			| UamFidelityUnsupportedError
 			| MaterializeValidationFailedError
 			| MaterializeWriteFailedError
 			| PathPolicyViolationError
@@ -307,6 +376,25 @@ export class AuthoringService {
 				reason: 'force_save',
 			});
 		}
+		return this.runSessionExclusive(input.sessionId, () => this.saveSessionExclusive(input));
+	}
+
+	private async saveSessionExclusive(
+		input: SaveSessionInput,
+	): Promise<
+		BackendResult<
+			BackendSessionSnapshot | MaterializeSessionSnapshot,
+			| SessionNotFoundError
+			| SessionStaleWriteError
+			| SavePartialFailureError
+			| UamFidelityUnsupportedError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
+			| PathPolicyViolationError
+			| InProcessLockConflictError
+			| BackendCapabilityUnavailableError
+		>
+	> {
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) {
@@ -317,9 +405,7 @@ export class AuthoringService {
 			return failure(
 				'authoring',
 				startedAt,
-				createCapabilityUnavailableError(
-					'saveSession requires an injected BackendFileSystem adapter.',
-				),
+				createCapabilityUnavailableError('saveSession requires an injected BackendFileSystem adapter.'),
 				toSessionSnapshot(session, this.context.capabilities),
 				{
 					sessionId: session.sessionId,
@@ -358,6 +444,18 @@ export class AuthoringService {
 				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: string[] = [];
 		const failedPaths: string[] = [];
@@ -426,11 +524,32 @@ export class AuthoringService {
 		}
 	}
 
-	public async materializeSession(input: MaterializeSessionInput): Promise<
+	public async materializeSession(
+		input: MaterializeSessionInput,
+	): Promise<
+		BackendResult<
+			MaterializeSessionSnapshot,
+			| SessionNotFoundError
+			| SessionStaleWriteError
+			| UamFidelityUnsupportedError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
+			| PathPolicyViolationError
+			| InProcessLockConflictError
+			| BackendCapabilityUnavailableError
+		>
+	> {
+		return this.runSessionExclusive(input.sessionId, () => this.materializeSessionExclusive(input));
+	}
+
+	private async materializeSessionExclusive(
+		input: MaterializeSessionInput,
+	): Promise<
 		BackendResult<
 			MaterializeSessionSnapshot,
 			| SessionNotFoundError
 			| SessionStaleWriteError
+			| UamFidelityUnsupportedError
 			| MaterializeValidationFailedError
 			| MaterializeWriteFailedError
 			| PathPolicyViolationError
@@ -457,14 +576,13 @@ export class AuthoringService {
 		}
 
 		const storageTarget = input.storage ? storageCanonicalTarget(input.storage) : null;
-		const fileSystem = storageTarget?.fileSystem ?? input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		const fileSystem =
+			storageTarget?.fileSystem ?? input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
 		if (!fileSystem) {
 			return failure(
 				'authoring',
 				startedAt,
-				createCapabilityUnavailableError(
-					'materializeSession requires an injected BackendFileSystem adapter.',
-				),
+				createCapabilityUnavailableError('materializeSession requires an injected BackendFileSystem adapter.'),
 				toSessionSnapshot(session, this.context.capabilities),
 				{
 					sessionId: session.sessionId,
@@ -510,6 +628,19 @@ export class AuthoringService {
 			}
 		}
 
+		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) {
 			const error: MaterializeValidationFailedError = {
@@ -520,17 +651,11 @@ export class AuthoringService {
 				issueCount: diagnostics.length,
 				diagnostics,
 			};
-			return failure(
-				'authoring',
-				startedAt,
-				error,
-				toSessionSnapshot(session, this.context.capabilities),
-				{
-					sessionId: session.sessionId,
-					revision: session.revision,
-					diagnostics,
-				},
-			);
+			return failure('authoring', startedAt, error, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics,
+			});
 		}
 
 		let document: ReturnType<typeof materializeUamProject>;

package/src/services/context.ts

@@ -1,3 +1,11 @@
+import {
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_CONTRACT_VERSION,
+	type BackendDiagnostic,
+	type BackendMessage,
+	type BackendResponseMeta,
+	type BackendStage,
+} from '../contracts.js';
 import type {
 	BackendCacheEntry,
 	BackendCapabilities,
@@ -10,14 +18,6 @@ import type {
 	BackendSessionSnapshot,
 	BackendSuccess,
 } from '../runtime.js';
-import {
-	BACKEND_CAPABILITY_SCHEMA_VERSION,
-	BACKEND_CONTRACT_VERSION,
-	type BackendDiagnostic,
-	type BackendMessage,
-	type BackendResponseMeta,
-	type BackendStage,
-} from '../contracts.js';
 
 export interface BackendSessionState {
 	sessionId: string;
@@ -27,9 +27,10 @@ export interface BackendSessionState {
 	lockFilePath: string;
 	fileSystem?: BackendFileSystem;
 	project: import('@openfairygui/core/uam').UamProject;
+	uamFidelity: 'full' | 'unsupported';
 	revision: number;
 	lastSavedRevision: number;
-	/** Source files deferred until a successful replacement project write. */
+	/** Package-controlled files deferred until a successful replacement project write. */
 	pendingStaleSourceFiles: Map<string, import('@openfairygui/core/project-io').ProjectSourceFile>;
 	dirty: boolean;
 	lockHeld: boolean;

package/src/services/runtime-service.ts

@@ -1,20 +1,25 @@
-import { ProjectReader, type FileSystem } from '@openfairygui/core/project-io';
-import { liftDocumentToUamProject, normalizeUamProject } from '@openfairygui/core/uam';
-import { failure, success, type BackendContext, type BackendSessionState } from './context.js';
-import type { CacheService } from './cache-service.js';
-import type { EventService } from './event-service.js';
-import type { JobService } from './job-service.js';
+import { type FileSystem, ProjectReader, ProjectWriter } from '@openfairygui/core/project-io';
+import {
+	liftDocumentToUamProject,
+	materializeUamProject,
+	normalizeUamProject,
+	type UamProject,
+} from '@openfairygui/core/uam';
+import { normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-policy.js';
 import type {
 	AdvisoryLockConflictError,
+	BackendCapabilityUnavailableError,
 	BackendFileHandle,
 	BackendResult,
 	BackendSessionSnapshot,
-	BackendCapabilityUnavailableError,
 	InProcessLockConflictError,
 	OpenProjectSessionInput,
 	SessionNotFoundError,
 } from '../runtime.js';
-import { normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-policy.js';
+import type { CacheService } from './cache-service.js';
+import { type BackendContext, type BackendSessionState, failure, success } from './context.js';
+import type { EventService } from './event-service.js';
+import type { JobService } from './job-service.js';
 import { createSessionNotFoundError, toSessionSnapshot } from './session-utils.js';
 
 function randomId(): string {
@@ -74,6 +79,82 @@ function createProjectReaderFileSystem(fileSystem: NonNullable<BackendContext['f
 	};
 }
 
+function createCaptureFileSystem(files: Map<string, string | Uint8Array>): FileSystem {
+	const normalize = (filePath: string): string => filePath.replace(/\\/g, '/').replace(/\/+/g, '/');
+	return {
+		async readFile(filePath: string): Promise<string> {
+			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: string): Promise<Uint8Array> {
+			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: string, content: string): Promise<void> {
+			files.set(normalize(filePath), content);
+		},
+		async writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			files.set(normalize(filePath), data.slice());
+		},
+		async mkdir(): Promise<void> {},
+		async readdir(): Promise<string[]> {
+			return [];
+		},
+		async exists(filePath: string): Promise<boolean> {
+			return files.has(normalize(filePath));
+		},
+		join(...paths: string[]): string {
+			return normalize(paths.filter(Boolean).join('/'));
+		},
+		dirname(filePath: string): string {
+			const normalized = normalize(filePath);
+			const separator = normalized.lastIndexOf('/');
+			return separator < 0 ? '' : normalized.slice(0, separator);
+		},
+		async unlink(filePath: string): Promise<void> {
+			files.delete(normalize(filePath));
+		},
+	};
+}
+
+function capturedFilesEqual(left: Map<string, string | Uint8Array>, right: Map<string, string | Uint8Array>): boolean {
+	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: Awaited<ReturnType<ProjectReader['read']>>,
+	project: UamProject,
+): Promise<boolean> {
+	const sourceFiles = new Map<string, string | Uint8Array>();
+	const materializedFiles = new Map<string, string | Uint8Array>();
+	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);
+}
+
 export class RuntimeService {
 	public constructor(
 		private readonly context: BackendContext,
@@ -129,7 +210,8 @@ export class RuntimeService {
 			await advisoryLock.close();
 
 			const reader = new ProjectReader(createProjectReaderFileSystem(fileSystem));
-			const project = liftDocumentToUamProject(await reader.read(fairyPath, { hydrateResourceBytes: true }));
+			const document = await reader.read(fairyPath, { hydrateResourceBytes: true });
+			const project = liftDocumentToUamProject(document);
 			const sessionId = randomId();
 			const session: BackendSessionState = {
 				sessionId,
@@ -139,6 +221,7 @@ export class RuntimeService {
 				lockFilePath,
 				fileSystem,
 				project,
+				uamFidelity: (await hasFullUamFidelity(document, project)) ? 'full' : 'unsupported',
 				revision: 0,
 				lastSavedRevision: 0,
 				pendingStaleSourceFiles: new Map(),
@@ -178,12 +261,14 @@ export class RuntimeService {
 		const sessionId = input.sessionId ?? randomId();
 		const storage = input.storage;
 		const memoryProjectPath = `memory://${sessionId}`;
-		const canonicalProjectPath = storage?.canonicalProjectPath
-			?? input.canonicalProjectPath
-			?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || '.' : memoryProjectPath);
-		const canonicalPathKey = storage?.canonicalPathKey
-			?? input.canonicalPathKey
-			?? (storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
+		const canonicalProjectPath =
+			storage?.canonicalProjectPath ??
+			input.canonicalProjectPath ??
+			(storage ? storage.fileSystem.dirname(storage.fairyPath) || '.' : memoryProjectPath);
+		const canonicalPathKey =
+			storage?.canonicalPathKey ??
+			input.canonicalPathKey ??
+			(storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
 		if (existingSessionId) {
 			return failure('runtime', startedAt, {
@@ -203,6 +288,7 @@ export class RuntimeService {
 			lockFilePath: '',
 			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
+			uamFidelity: 'full',
 			revision: 0,
 			lastSavedRevision: 0,
 			pendingStaleSourceFiles: new Map(),

package/src/services/session-utils.ts

@@ -7,13 +7,17 @@ import type {
 import type { BackendSessionState } from './context.js';
 import { cloneCapabilitiesSnapshot } from './snapshot-utils.js';
 
-export function toSessionSnapshot(session: BackendSessionState, capabilities: BackendCapabilities): BackendSessionSnapshot {
+export function toSessionSnapshot(
+	session: BackendSessionState,
+	capabilities: BackendCapabilities,
+): BackendSessionSnapshot {
 	return {
 		sessionId: session.sessionId,
 		canonicalProjectPath: session.canonicalProjectPath,
 		revision: session.revision,
 		lastSavedRevision: session.lastSavedRevision,
 		dirty: session.dirty,
+		uamFidelity: session.uamFidelity,
 		lockHeld: session.lockHeld,
 		capabilities: cloneCapabilitiesSnapshot(capabilities),
 	};