@openfairygui/backend 0.2.0-alpha.2 → 0.2.0-alpha.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/backend",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.21",
   "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.2",
-    "@openfairygui/functions": "0.2.0-alpha.2"
+    "@openfairygui/functions": "0.2.0-alpha.21",
+    "@openfairygui/core": "0.2.0-alpha.21"
   },
   "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/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',
+			},
+		},
+	};
+}