@openfairygui/backend 0.2.0-alpha.3 → 0.2.0-alpha.30

package/dist/{runtime-u1Bq_ysz.d.mts → runtime-Wu6vGZ-j.d.cts}

@@ -1,5 +1,5 @@
-import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
 import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
+import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
 
 //#region src/contracts.d.ts
 declare const BACKEND_CONTRACT_VERSION: "1.1.0-p2";
@@ -18,6 +18,14 @@ interface BackendDiagnostic {
   code: string;
   message: string;
   severity: 'info' | 'warning' | 'error';
+  path?: string;
+  nodeKind?: string;
+  resourceKind?: string;
+  gearKind?: string;
+  field?: string;
+  operationKind?: string;
+  opIndex?: number;
+  opId?: string;
 }
 interface BackendResponseMeta {
   requestId: string;
@@ -40,7 +48,7 @@ interface PathPolicyViolationError {
   allowedPath: string;
 }
 //#endregion
-//#region src/runtime.d.ts
+//#region src/runtime/contracts.d.ts
 interface BackendFileHandle {
   writeFile(content: string): Promise<void>;
   close(): Promise<void>;
@@ -62,6 +70,7 @@ interface BackendFileSystem {
   resolvePath(filePath: string): Promise<string>;
   openExclusive(filePath: string): Promise<BackendFileHandle>;
   unlink(filePath: string): Promise<void>;
+  rmdir(dirPath: string): Promise<void>;
   join(...paths: string[]): string;
   dirname(filePath: string): string;
   resolve(...paths: string[]): string;
@@ -87,7 +96,13 @@ interface BackendCapabilityManifest {
   adapters: {
     fileSystem: {
       injected: true;
-      requiredFor: readonly ['openSession', 'saveSession'];
+      requiredFor: readonly ['openSession', 'saveSession', 'materializeSession'];
+    };
+    projectStorage: {
+      injected: true;
+      browserSafe: true;
+      requiredFor: readonly ['openProjectSession.writeback', 'saveSession', 'materializeSession'];
+      adapterFactory: 'createBackendStorageFileSystem';
     };
     host: {
       injected: true;
@@ -111,7 +126,7 @@ interface BackendCapabilities {
   transactionKernelOwner: '@openfairygui/core';
   appSeamOwner: '@openfairygui/functions';
   runtimeOwner: '@openfairygui/backend';
-  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
   read: {
     capabilitySnapshot: true;
     sessionSnapshot: true;
@@ -179,9 +194,19 @@ interface BackendSessionSnapshot {
   revision: number;
   lastSavedRevision: number;
   dirty: boolean;
+  uamFidelity: 'full' | 'unsupported';
   lockHeld: boolean;
   capabilities: BackendCapabilities;
 }
+interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
+  mode: 'fullProject';
+  reason?: string;
+  materializeRevision: number;
+  saveRevision: number;
+  writtenPaths: string[];
+  skippedPaths: string[];
+  diagnostics: BackendDiagnostic[];
+}
 interface BackendSuccess<T> {
   ok: true;
   meta: BackendResponseMeta;
@@ -234,6 +259,33 @@ interface SavePartialFailureError {
   failedPaths: string[];
   diskMayBePartiallyUpdated: true;
 }
+interface UamFidelityUnsupportedError {
+  code: 'uam_fidelity_unsupported';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+}
+interface MaterializeValidationFailedError {
+  code: 'materialize_validation_failed';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  issueCount: number;
+  diagnostics: BackendDiagnostic[];
+}
+interface MaterializeWriteFailedError {
+  code: 'write_failed';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  attemptedRevision: number;
+  lastSavedRevision: number;
+  writtenPaths: string[];
+  failedPaths: string[];
+  skippedPaths: string[];
+  diagnostics: BackendDiagnostic[];
+  diskMayBePartiallyUpdated: true;
+}
 type BackendEventKind = 'session.opened' | 'transaction.applied' | 'transaction.rejected' | 'save.started' | 'save.completed' | 'save.failed' | 'session.closeRequested' | 'session.closed' | 'cache.invalidated' | 'cache.updated' | 'job.created' | 'job.started' | 'job.progress' | 'job.cancelRequested' | 'job.cancelled' | 'job.completed' | 'job.failed';
 interface BackendEvent {
   sequence: number;
@@ -365,7 +417,7 @@ interface RefreshCacheInput {
   sessionId: string;
   reason?: 'manual' | 'session_open' | 'after_save';
 }
-type BackendError = SessionNotFoundError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ApplyUamTransactionAppError;
+type BackendError = SessionNotFoundError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ApplyUamTransactionAppError;
 interface ApplySessionTransactionInput {
   sessionId: string;
   expectedRevision: number;
@@ -376,11 +428,37 @@ interface OpenProjectSessionInput {
   sessionId?: string;
   canonicalProjectPath?: string;
   canonicalPathKey?: string;
+  storage?: BackendProjectSessionStorage;
+}
+interface BackendProjectSessionStorage {
+  fileSystem: BackendFileSystem;
+  fairyPath: string;
+  canonicalProjectPath?: string;
+  canonicalPathKey?: string;
+}
+interface SaveSessionInput {
+  sessionId: string;
+  expectedRevision?: number;
+  targetPath?: string;
+  fileSystem?: BackendFileSystem;
+  force?: boolean;
+  mode?: 'materializeCleanSession';
+}
+interface MaterializeSessionInput {
+  sessionId: string;
+  expectedRevision?: number;
+  storage?: BackendProjectSessionStorage;
+  targetPath?: string;
+  fileSystem?: BackendFileSystem;
+  mode?: 'fullProject';
+  reason?: string;
 }
 interface BackendRuntimeOptions {
   fileSystem?: BackendFileSystem;
   host?: BackendHostAdapter;
 }
+//#endregion
+//#region src/runtime.d.ts
 declare class BackendRuntime {
   private readonly fileSystem?;
   private readonly capabilities;
@@ -407,11 +485,8 @@ declare class BackendRuntime {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
   applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
-  saveSession(input: {
-    sessionId: string;
-    expectedRevision?: number;
-    targetPath?: string;
-  }): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>>;
+  saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot | MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
+  materializeSession(input: MaterializeSessionInput): Promise<BackendResult<MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
   closeSession(input: {
     sessionId: string;
   }): Promise<BackendResult<{
@@ -426,4 +501,4 @@ declare class BackendRuntime {
   refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError>;
 }
 //#endregion
-export { BackendSuccess as A, OpenProjectSessionInput as B, BackendJobProgress as C, BackendRuntime as D, BackendResult as E, GetEventsInput as F, BACKEND_CAPABILITY_SCHEMA_VERSION as G, SavePartialFailureError as H, GetEventsSnapshot as I, BackendDiagnostic as J, BACKEND_COMPATIBILITY_POLICY as K, GetJobInput as L, CancelJobInput as M, EventCursorInvalidError as N, BackendRuntimeOptions as O, GetCacheSnapshotInput as P, InProcessLockConflictError as R, BackendJobNotFoundError as S, BackendJobStatus as T, SessionNotFoundError as U, RefreshCacheInput as V, SessionStaleWriteError as W, BackendResponseMeta as X, BackendMessage as Y, BackendStage as Z, BackendJobErrors as _, BackendCacheSnapshot as a, BackendJobListStatusFilter as b, BackendCapabilityUnavailableError as c, BackendEventKind as d, BackendFailure as f, BackendHostAdapter as g, BackendFileSystem as h, BackendCacheEntry as i, CacheRefreshFailedError as j, BackendSessionSnapshot as k, BackendError as l, BackendFileStat as m, ApplySessionTransactionInput as n, BackendCapabilities as o, BackendFileHandle as p, BACKEND_CONTRACT_VERSION as q, BackendArtifactBridgeCapability as r, BackendCapabilityManifest as s, AdvisoryLockConflictError as t, BackendEvent as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, ListJobsInput as z };
+export { BACKEND_COMPATIBILITY_POLICY as $, BackendSessionSnapshot as A, ListJobsInput as B, BackendJobNotFoundError as C, BackendProjectSessionStorage as D, BackendJobStatus as E, GetCacheSnapshotInput as F, OpenProjectSessionInput as G, MaterializeSessionSnapshot as H, GetEventsInput as I, SaveSessionInput as J, RefreshCacheInput as K, GetEventsSnapshot as L, CacheRefreshFailedError as M, CancelJobInput as N, BackendResult as O, EventCursorInvalidError as P, BACKEND_CAPABILITY_SCHEMA_VERSION as Q, GetJobInput as R, BackendJobNotCancellableError as S, BackendJobSnapshot as T, MaterializeValidationFailedError as U, MaterializeSessionInput as V, MaterializeWriteFailedError as W, SessionStaleWriteError as X, SessionNotFoundError as Y, UamFidelityUnsupportedError as Z, BackendHostAdapter as _, BackendCacheEntry as a, BackendJobListSnapshot as b, BackendCapabilityManifest as c, BackendEvent as d, BACKEND_CONTRACT_VERSION as et, BackendEventKind as f, BackendFileSystem as g, BackendFileStat as h, BackendArtifactBridgeCapability as i, BackendStage as it, BackendSuccess as j, BackendRuntimeOptions as k, BackendCapabilityUnavailableError as l, BackendFileHandle as m, AdvisoryLockConflictError as n, BackendMessage as nt, BackendCacheSnapshot as o, BackendFailure as p, SavePartialFailureError as q, ApplySessionTransactionInput as r, BackendResponseMeta as rt, BackendCapabilities as s, BackendRuntime as t, BackendDiagnostic as tt, BackendError as u, BackendJobErrors as v, BackendJobProgress as w, BackendJobListStatusFilter as x, BackendJobKind as y, InProcessLockConflictError as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/backend",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.30",
   "description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -52,12 +52,13 @@
     "runtime"
   ],
   "dependencies": {
-    "@openfairygui/core": "0.2.0-alpha.3",
-    "@openfairygui/functions": "0.2.0-alpha.3"
+    "@openfairygui/core": "0.2.0-alpha.30",
+    "@openfairygui/functions": "0.2.0-alpha.30"
   },
   "devDependencies": {
     "ava": "^7.0.0",
-    "tsx": "^4.0.0"
+    "tsx": "^4.0.0",
+    "@openfairygui/test-utils": "0.2.0-alpha.10"
   },
   "scripts": {
     "build": "tsdown src/index.ts src/node.ts --format esm,cjs --platform node --external node:fs --external node:fs/promises --external node:path --env.PACKAGE_VERSION=$npm_package_version",

package/src/contracts.ts

@@ -17,6 +17,14 @@ export interface BackendDiagnostic {
 	code: string;
 	message: string;
 	severity: 'info' | 'warning' | 'error';
+	path?: string;
+	nodeKind?: string;
+	resourceKind?: string;
+	gearKind?: string;
+	field?: string;
+	operationKind?: string;
+	opIndex?: number;
+	opId?: string;
 }
 
 export interface BackendResponseMeta {

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,
@@ -38,18 +48,21 @@ export {
 	type GetJobInput,
 	type InProcessLockConflictError,
 	type ListJobsInput,
+	type MaterializeSessionInput,
+	type MaterializeSessionSnapshot,
+	type MaterializeValidationFailedError,
+	type MaterializeWriteFailedError,
 	type OpenProjectSessionInput,
 	type RefreshCacheInput,
 	type SavePartialFailureError,
+	type SaveSessionInput,
 	type SessionNotFoundError,
 	type SessionStaleWriteError,
+	type UamFidelityUnsupportedError,
 } from './runtime.js';
 export {
-	type BackendDiagnostic,
-	type BackendMessage,
-	type BackendResponseMeta,
-	type BackendStage,
-	BACKEND_CAPABILITY_SCHEMA_VERSION,
-	BACKEND_COMPATIBILITY_POLICY,
-	BACKEND_CONTRACT_VERSION,
-} from './contracts.js';
+	type BackendAsyncStorageAdapter,
+	type BackendStorageFileSystem,
+	type BackendStorageStatLike,
+	createBackendStorageFileSystem,
+} from './storage.js';

package/src/node.ts

@@ -54,6 +54,9 @@ export function createNodeBackendFileSystem(): BackendFileSystem {
 		unlink(filePath: string): Promise<void> {
 			return fs.unlink(filePath);
 		},
+		rmdir(dirPath: string): Promise<void> {
+			return fs.rmdir(dirPath);
+		},
 		join(...paths: string[]): string {
 			return path.join(...paths);
 		},

package/src/runtime/capabilities.ts

@@ -0,0 +1,126 @@
+import {
+	UAM_SUPPORTED_MATERIALIZATION_SCOPE,
+	UAM_SUPPORTED_TRANSACTION_SCOPE,
+} from '@openfairygui/core/uam';
+import {
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_COMPATIBILITY_POLICY,
+	BACKEND_CONTRACT_VERSION,
+} from '../contracts.js';
+import { createRuntimePathPolicy } from '../path-policy.js';
+import { createArtifactCapabilities } from '../services/artifact-service.js';
+import type { BackendArtifactBridgeCapability, BackendCapabilities } from './contracts.js';
+
+const BACKEND_METHODS = [
+	'getCapabilities',
+	'openSession',
+	'openProjectSession',
+	'getSession',
+	'applyTransaction',
+	'saveSession',
+	'materializeSession',
+	'closeSession',
+	'getEvents',
+	'getJob',
+	'listJobs',
+	'cancelJob',
+	'getCacheSnapshot',
+	'refreshCache',
+] as const;
+
+const ARTIFACT_BRIDGE_CAPABILITY = {
+	available: false,
+	requiredHost: 'node',
+	executionBoundary: 'external-bridge',
+	bridgeEntrypoint: '@openfairygui/backend/node',
+	reason: 'publish/restore require explicit Node-hosted filesystem and artifact execution.',
+} as const satisfies BackendArtifactBridgeCapability;
+
+export function createCapabilities(): BackendCapabilities {
+	return {
+		contractVersion: BACKEND_CONTRACT_VERSION,
+		capabilitySchemaVersion: BACKEND_CAPABILITY_SCHEMA_VERSION,
+		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],
+			transactionScope: {
+				resourceKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.resourceKinds],
+				nodeKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.nodeKinds],
+				gearKinds: [...UAM_SUPPORTED_TRANSACTION_SCOPE.gearKinds],
+			},
+			unsupported: ['artifact.publish', 'artifact.restore'],
+		},
+		artifact: createArtifactCapabilities(),
+		manifest: {
+			browserSafe: true,
+			rootEntrypoint: '@openfairygui/backend',
+			nodeEntrypoint: '@openfairygui/backend/node',
+			adapters: {
+				fileSystem: {
+					injected: true,
+					requiredFor: ['openSession', 'saveSession', 'materializeSession'],
+				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: ['openProjectSession.writeback', 'saveSession', 'materializeSession'],
+					adapterFactory: 'createBackendStorageFileSystem',
+				},
+				host: {
+					injected: true,
+					requiredFor: ['advisoryLockMetadata'],
+				},
+			},
+			executionBoundaries: {
+				projectSession: 'in-process-browser-safe',
+				fileBackedSession: 'adapter-backed',
+				artifactPublish: ARTIFACT_BRIDGE_CAPABILITY,
+				artifactRestore: ARTIFACT_BRIDGE_CAPABILITY,
+			},
+			diagnostics: {
+				stableCodes: true,
+				errorDiagnosticMirror: true,
+			},
+		},
+		compatibilityPolicy: BACKEND_COMPATIBILITY_POLICY,
+		runtime: {
+			sessionRuntime: true,
+			advisoryLocking: true,
+			coordinatedSave: true,
+			atomicSave: false,
+			staleRevisionProtection: true,
+			pathPolicy: createRuntimePathPolicy(),
+			events: {
+				polling: true,
+				subscriptions: false,
+				retentionLimit: 1000,
+				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',
+			},
+		},
+	};
+}