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

package/dist/runtime-qcSlD_9-.d.cts

@@ -0,0 +1,424 @@
+import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
+import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
+
+//#region src/contracts.d.ts
+declare const BACKEND_CONTRACT_VERSION: "1.1.0-p2";
+declare const BACKEND_CAPABILITY_SCHEMA_VERSION: 2;
+declare const BACKEND_COMPATIBILITY_POLICY: {
+  readonly incompatibleChange: "requires contractVersion bump";
+  readonly capabilitySchemaChange: "requires capabilitySchemaVersion bump";
+  readonly additiveChange: "allowed without breaking existing consumers";
+};
+type BackendStage = 'read' | 'authoring' | 'runtime';
+interface BackendMessage {
+  code: string;
+  message: string;
+}
+interface BackendDiagnostic {
+  code: string;
+  message: string;
+  severity: 'info' | 'warning' | 'error';
+}
+interface BackendResponseMeta {
+  requestId: string;
+  sessionId?: string;
+  revision?: number;
+  durationMs: number;
+  warnings: BackendMessage[];
+  diagnostics: BackendDiagnostic[];
+  stage: BackendStage;
+  contractVersion: typeof BACKEND_CONTRACT_VERSION;
+  capabilitySchemaVersion: typeof BACKEND_CAPABILITY_SCHEMA_VERSION;
+}
+//#endregion
+//#region src/path-policy.d.ts
+interface PathPolicyViolationError {
+  code: 'path_policy_violation';
+  message: string;
+  policy: 'save_target';
+  attemptedPath: string;
+  allowedPath: string;
+}
+//#endregion
+//#region src/runtime.d.ts
+interface BackendFileHandle {
+  writeFile(content: string): Promise<void>;
+  close(): Promise<void>;
+}
+interface BackendFileStat {
+  isFile(): boolean;
+  isDirectory(): boolean;
+}
+interface BackendFileSystem {
+  stat(filePath: string): Promise<BackendFileStat>;
+  readdir(dirPath: string): Promise<string[]>;
+  readFile(filePath: string): Promise<string>;
+  readFileRaw(filePath: string): Promise<Uint8Array>;
+  writeFile(filePath: string, content: string): Promise<void>;
+  writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
+  mkdir(dirPath: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  resolvePath(filePath: string): Promise<string>;
+  openExclusive(filePath: string): Promise<BackendFileHandle>;
+  unlink(filePath: string): Promise<void>;
+  join(...paths: string[]): string;
+  dirname(filePath: string): string;
+  resolve(...paths: string[]): string;
+}
+interface BackendHostAdapter {
+  lockMetadata?(input: {
+    canonicalPathKey: string;
+    canonicalProjectPath: string;
+    lockFilePath: string;
+  }): unknown;
+}
+interface BackendArtifactBridgeCapability {
+  available: false;
+  requiredHost: 'node';
+  executionBoundary: 'external-bridge';
+  bridgeEntrypoint: '@openfairygui/backend/node';
+  reason: string;
+}
+interface BackendCapabilityManifest {
+  browserSafe: true;
+  rootEntrypoint: '@openfairygui/backend';
+  nodeEntrypoint: '@openfairygui/backend/node';
+  adapters: {
+    fileSystem: {
+      injected: true;
+      requiredFor: readonly ['openSession', 'saveSession'];
+    };
+    host: {
+      injected: true;
+      requiredFor: readonly ['advisoryLockMetadata'];
+    };
+  };
+  executionBoundaries: {
+    projectSession: 'in-process-browser-safe';
+    fileBackedSession: 'adapter-backed';
+    artifactPublish: BackendArtifactBridgeCapability;
+    artifactRestore: BackendArtifactBridgeCapability;
+  };
+  diagnostics: {
+    stableCodes: true;
+    errorDiagnosticMirror: true;
+  };
+}
+interface BackendCapabilities {
+  contractVersion: typeof BACKEND_CONTRACT_VERSION;
+  capabilitySchemaVersion: typeof BACKEND_CAPABILITY_SCHEMA_VERSION;
+  transactionKernelOwner: '@openfairygui/core';
+  appSeamOwner: '@openfairygui/functions';
+  runtimeOwner: '@openfairygui/backend';
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  read: {
+    capabilitySnapshot: true;
+    sessionSnapshot: true;
+  };
+  authoring: {
+    applyTransaction: true;
+    saveSession: true;
+    resourceKinds: readonly string[];
+    nodeKinds: readonly string[];
+    gearKinds: readonly string[];
+    unsupported: readonly ['artifact.publish', 'artifact.restore'];
+  };
+  artifact: {
+    publish: false;
+    restore: false;
+    status: 'bridge-required';
+    publishBridge: BackendArtifactBridgeCapability;
+    restoreBridge: BackendArtifactBridgeCapability;
+  };
+  manifest: BackendCapabilityManifest;
+  compatibilityPolicy: typeof BACKEND_COMPATIBILITY_POLICY;
+  runtime: {
+    sessionRuntime: true;
+    advisoryLocking: true;
+    coordinatedSave: true;
+    atomicSave: false;
+    staleRevisionProtection: true;
+    pathPolicy: {
+      canonicalization: 'realpath+normalized-casefold';
+      sessionIdentity: 'project-root';
+      saveTarget: 'opened-project-only';
+      outputTargets: 'deferred';
+      workspaceBoundary: 'project-root-only';
+    };
+    events: {
+      polling: true;
+      subscriptions: false;
+      retentionLimit: 1000;
+      sequenceScope: 'runtime';
+    };
+    jobs: {
+      inMemory: true;
+      cooperativeCancel: true;
+      persistent: false;
+      supportedKinds: readonly ['cache.refresh'];
+      artifactJobs: false;
+      completedRetentionLimit: 100;
+    };
+    cache: {
+      derivedReadOnly: true;
+      keyedBy: 'canonicalPathKey';
+      sourceOfTruth: false;
+      refreshMethod: 'refreshCache';
+    };
+  };
+}
+interface BackendSessionSnapshot {
+  sessionId: string;
+  canonicalProjectPath: string;
+  revision: number;
+  lastSavedRevision: number;
+  dirty: boolean;
+  lockHeld: boolean;
+  capabilities: BackendCapabilities;
+}
+interface BackendSuccess<T> {
+  ok: true;
+  meta: BackendResponseMeta;
+  data: T;
+}
+interface BackendFailure<E extends BackendError = BackendError> {
+  ok: false;
+  meta: BackendResponseMeta;
+  error: E;
+  session?: BackendSessionSnapshot;
+}
+type BackendResult<T, E extends BackendError = BackendError> = BackendSuccess<T> | BackendFailure<E>;
+interface SessionNotFoundError {
+  code: 'session_not_found';
+  message: string;
+  sessionId: string;
+}
+interface SessionStaleWriteError {
+  code: 'stale_write';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  expectedRevision: number;
+  actualRevision: number;
+}
+interface InProcessLockConflictError {
+  code: 'lock_conflict';
+  kind: 'in_process_session_exists';
+  message: string;
+  canonicalPathKey: string;
+  holderSessionId: string;
+  lockFilePath?: string;
+}
+interface AdvisoryLockConflictError {
+  code: 'lock_conflict';
+  kind: 'advisory_lock_conflict';
+  message: string;
+  canonicalPathKey: string;
+  holderSessionId?: string;
+  lockFilePath: string;
+}
+interface SavePartialFailureError {
+  code: 'save_partial_failure';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  attemptedRevision: number;
+  lastSavedRevision: number;
+  committedPaths: string[];
+  failedPaths: string[];
+  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;
+  kind: BackendEventKind;
+  timestamp: string;
+  sessionId?: string;
+  canonicalPathKey?: string;
+  revision?: number;
+  cacheRevision?: number;
+  jobId?: string;
+  diagnostics: BackendDiagnostic[];
+  payload?: unknown;
+}
+interface GetEventsInput {
+  sessionId: string;
+  after?: string;
+  limit?: number;
+}
+interface GetEventsSnapshot {
+  events: BackendEvent[];
+  oldestSequence: number;
+  currentSequence: number;
+  cursorExpired: boolean;
+}
+interface EventCursorInvalidError {
+  code: 'event_cursor_invalid';
+  message: string;
+  sessionId: string;
+  after: string;
+}
+type BackendJobStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+type BackendJobKind = 'cache.refresh';
+type BackendJobListStatusFilter = BackendJobStatus | 'active' | 'terminal';
+interface BackendJobProgress {
+  completed: number;
+  total?: number;
+  message?: string;
+}
+interface BackendJobSnapshot {
+  jobId: string;
+  kind: BackendJobKind;
+  status: BackendJobStatus;
+  createdAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  sessionId?: string;
+  canonicalPathKey?: string;
+  revision?: number;
+  cacheRevision?: number;
+  diagnostics: BackendDiagnostic[];
+  progress?: BackendJobProgress;
+  result?: unknown;
+  error?: BackendError;
+}
+interface BackendJobListSnapshot {
+  jobs: BackendJobSnapshot[];
+}
+interface GetJobInput {
+  sessionId: string;
+  jobId: string;
+}
+interface ListJobsInput {
+  sessionId: string;
+  status?: BackendJobListStatusFilter;
+  kind?: BackendJobKind;
+  limit?: number;
+}
+interface CancelJobInput {
+  sessionId: string;
+  jobId: string;
+}
+interface BackendJobNotFoundError {
+  code: 'job_not_found';
+  message: string;
+  sessionId: string;
+  jobId: string;
+}
+interface BackendJobNotCancellableError {
+  code: 'job_not_cancellable';
+  message: string;
+  sessionId: string;
+  jobId: string;
+  status: 'completed' | 'failed' | 'cancelled';
+}
+interface BackendJobCancelledError {
+  code: 'job_cancelled';
+  message: string;
+  sessionId: string;
+  jobId: string;
+}
+interface CacheRefreshFailedError {
+  code: 'cache_refresh_failed';
+  message: string;
+  sessionId: string;
+  jobId: string;
+  causeCode?: string;
+}
+interface BackendCapabilityUnavailableError {
+  code: 'capability_unavailable';
+  message: string;
+  capability: 'fileSystem' | 'artifact.publish' | 'artifact.restore';
+  requiredAdapter?: 'BackendFileSystem';
+  requiredHost?: 'node';
+  bridgeBoundary?: 'external-bridge';
+}
+type BackendJobErrors = BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError;
+interface BackendCacheSnapshot {
+  cacheRevision: number;
+  entries: BackendCacheEntry[];
+}
+interface BackendCacheEntry {
+  canonicalPathKey: string;
+  sessionId?: string;
+  revision: number;
+  lastSavedRevision: number;
+  dirty: boolean;
+  valid: boolean;
+  indexedAt: string;
+  summary: {
+    resourceCount: number;
+    packageCount?: number;
+    diagnostics: BackendDiagnostic[];
+  };
+}
+interface GetCacheSnapshotInput {
+  sessionId: string;
+}
+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;
+interface ApplySessionTransactionInput {
+  sessionId: string;
+  expectedRevision: number;
+  operations: UamTransactionOperation[];
+}
+interface OpenProjectSessionInput {
+  project: UamProject;
+  sessionId?: string;
+  canonicalProjectPath?: string;
+  canonicalPathKey?: string;
+}
+interface BackendRuntimeOptions {
+  fileSystem?: BackendFileSystem;
+  host?: BackendHostAdapter;
+}
+declare class BackendRuntime {
+  private readonly fileSystem?;
+  private readonly capabilities;
+  private readonly sessions;
+  private readonly sessionsByPath;
+  private readonly eventsBySession;
+  private readonly jobsBySession;
+  private readonly cacheBySession;
+  private eventSequence;
+  private readonly context;
+  private readonly readService;
+  private readonly runtimeService;
+  private readonly authoringService;
+  private readonly cacheService;
+  private readonly eventService;
+  private readonly jobService;
+  constructor(options?: BackendRuntimeOptions);
+  getCapabilities(): BackendSuccess<BackendCapabilities>;
+  openSession(input: {
+    projectPath: string;
+  }): Promise<BackendResult<BackendSessionSnapshot, InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError>>;
+  openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot>;
+  getSession(input: {
+    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>>;
+  closeSession(input: {
+    sessionId: string;
+  }): Promise<BackendResult<{
+    sessionId: string;
+    closed: true;
+  }, SessionNotFoundError>>;
+  getEvents(input: GetEventsInput): BackendResult<GetEventsSnapshot, SessionNotFoundError | EventCursorInvalidError>;
+  getJob(input: GetJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError>;
+  listJobs(input: ListJobsInput): BackendResult<BackendJobListSnapshot, SessionNotFoundError>;
+  cancelJob(input: CancelJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError | BackendJobNotCancellableError>;
+  getCacheSnapshot(input: GetCacheSnapshotInput): BackendResult<BackendCacheSnapshot, SessionNotFoundError>;
+  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 };

package/package.json

@@ -1,54 +1,66 @@
 {
-	"name": "@openfairygui/backend",
-	"version": "0.2.0-alpha.0",
-	"description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
-	"author": "OpenFairyGUI Contributors",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/OpenFairyGUI/OpenFairyGUI.git",
-		"directory": "packages/backend"
-	},
-	"homepage": "https://github.com/OpenFairyGUI/OpenFairyGUI#readme",
-	"bugs": {
-		"url": "https://github.com/OpenFairyGUI/OpenFairYGUI/issues"
-	},
-	"type": "module",
-	"sideEffects": false,
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.mjs",
-	"types": "./dist/index.d.mts",
-	"exports": {
-		"require": {
-			"types": "./dist/index.d.cts",
-			"default": "./dist/index.cjs"
-		},
-		"default": {
-			"types": "./dist/index.d.mts",
-			"default": "./dist/index.mjs"
-		}
-	},
-	"scripts": {
-		"build": "tsdown --format esm,cjs --platform node --external node:fs --external node:fs/promises --external node:path --env.PACKAGE_VERSION=$npm_package_version",
-		"build:watch": "tsdown --watch --format esm,cjs --platform node --env.PACKAGE_VERSION=$npm_package_version"
-	},
-	"files": [
-		"dist/",
-		"src/"
-	],
-	"keywords": [
-		"fairygui",
-		"backend",
-		"session",
-		"authoring",
-		"runtime"
-	],
-	"dependencies": {
-		"@openfairygui/core": "workspace:*",
-		"@openfairygui/functions": "workspace:*"
-	},
-	"devDependencies": {
-		"ava": "^7.0.0",
-		"tsx": "^4.0.0"
-	}
-}
+  "name": "@openfairygui/backend",
+  "version": "0.2.0-alpha.2",
+  "description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
+  "author": "OpenFairyGUI Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenFairyGUI/OpenFairyGUI.git",
+    "directory": "packages/backend"
+  },
+  "homepage": "https://github.com/OpenFairyGUI/OpenFairyGUI#readme",
+  "bugs": {
+    "url": "https://github.com/OpenFairyGUI/OpenFairYGUI/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "default": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./node": {
+      "require": {
+        "types": "./dist/node.d.cts",
+        "default": "./dist/node.cjs"
+      },
+      "default": {
+        "types": "./dist/node.d.mts",
+        "default": "./dist/node.mjs"
+      }
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "keywords": [
+    "fairygui",
+    "backend",
+    "session",
+    "authoring",
+    "runtime"
+  ],
+  "dependencies": {
+    "@openfairygui/core": "0.2.0-alpha.2",
+    "@openfairygui/functions": "0.2.0-alpha.2"
+  },
+  "devDependencies": {
+    "ava": "^7.0.0",
+    "tsx": "^4.0.0"
+  },
+  "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",
+    "build:watch": "tsdown src/index.ts src/node.ts --watch --format esm,cjs --platform node --external node:fs --external node:fs/promises --external node:path --env.PACKAGE_VERSION=$npm_package_version"
+  }
+}

package/src/index.ts

@@ -1,17 +1,21 @@
 export {
 	BackendRuntime,
-	createNodeBackendFileSystem,
 	type AdvisoryLockConflictError,
 	type ApplySessionTransactionInput,
+	type BackendArtifactBridgeCapability,
 	type BackendCacheEntry,
 	type BackendCacheSnapshot,
+	type BackendCapabilityManifest,
+	type BackendCapabilityUnavailableError,
 	type BackendCapabilities,
 	type BackendError,
 	type BackendEvent,
 	type BackendEventKind,
 	type BackendFailure,
 	type BackendFileHandle,
+	type BackendFileStat,
 	type BackendFileSystem,
+	type BackendHostAdapter,
 	type BackendJobKind,
 	type BackendJobListSnapshot,
 	type BackendJobListStatusFilter,
@@ -34,6 +38,7 @@ export {
 	type GetJobInput,
 	type InProcessLockConflictError,
 	type ListJobsInput,
+	type OpenProjectSessionInput,
 	type RefreshCacheInput,
 	type SavePartialFailureError,
 	type SessionNotFoundError,

package/src/node.ts

@@ -0,0 +1,96 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+	BackendRuntime,
+	type BackendFileHandle,
+	type BackendFileStat,
+	type BackendFileSystem,
+	type BackendHostAdapter,
+	type BackendRuntimeOptions,
+} from './runtime.js';
+
+export function createNodeBackendFileSystem(): BackendFileSystem {
+	return {
+		stat(filePath: string): Promise<BackendFileStat> {
+			return fs.stat(filePath);
+		},
+		readdir(dirPath: string): Promise<string[]> {
+			return fs.readdir(dirPath);
+		},
+		readFile(filePath: string): Promise<string> {
+			return fs.readFile(filePath, 'utf-8');
+		},
+		async readFileRaw(filePath: string): Promise<Uint8Array> {
+			const buffer = await fs.readFile(filePath);
+			return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+		},
+		writeFile(filePath: string, content: string): Promise<void> {
+			return fs.writeFile(filePath, content, 'utf-8');
+		},
+		writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			return fs.writeFile(filePath, data);
+		},
+		async mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void> {
+			await fs.mkdir(dirPath, { recursive: options?.recursive ?? false });
+		},
+		async resolvePath(filePath: string): Promise<string> {
+			try {
+				return await fs.realpath(filePath);
+			} catch {
+				return path.resolve(filePath);
+			}
+		},
+		async openExclusive(filePath: string): Promise<BackendFileHandle> {
+			const handle = await fs.open(filePath, 'wx');
+			return {
+				writeFile(content: string): Promise<void> {
+					return handle.writeFile(content, 'utf-8');
+				},
+				close(): Promise<void> {
+					return handle.close();
+				},
+			};
+		},
+		unlink(filePath: string): Promise<void> {
+			return fs.unlink(filePath);
+		},
+		join(...paths: string[]): string {
+			return path.join(...paths);
+		},
+		dirname(filePath: string): string {
+			return path.dirname(filePath);
+		},
+		resolve(...paths: string[]): string {
+			return path.resolve(...paths);
+		},
+	};
+}
+
+export function createNodeBackendHostAdapter(): BackendHostAdapter {
+	return {
+		lockMetadata(input) {
+			return {
+				pid: process.pid,
+				createdAt: new Date().toISOString(),
+				canonicalPathKey: input.canonicalPathKey,
+			};
+		},
+	};
+}
+
+export function createNodeBackendRuntime(options: BackendRuntimeOptions = {}): BackendRuntime {
+	return new BackendRuntime({
+		...options,
+		fileSystem: options.fileSystem ?? createNodeBackendFileSystem(),
+		host: options.host ?? createNodeBackendHostAdapter(),
+	});
+}
+
+export { BackendRuntime };
+export type {
+	BackendFileHandle,
+	BackendFileStat,
+	BackendFileSystem,
+	BackendHostAdapter,
+	BackendRuntimeOptions,
+} from './runtime.js';