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

package/README.md

@@ -12,6 +12,7 @@ It owns:
 - revisioned request handling
 - coordinated but non-atomic save semantics
 - browser-safe project sessions
+- browser-safe async project storage adapter
 - adapter-backed file sessions and backend-local advisory locking
 - capability discovery
 - transport-neutral bootstrap
@@ -31,8 +32,16 @@ It also provides:
 
 It does **not** redefine transaction grammar or expose `Document`.
 It also does **not** implement MCP or any transport-specific wire protocol.
-The root `@openfairygui/backend` entrypoint is browser-safe: file-backed sessions require an injected
-`BackendFileSystem`, while the default Node filesystem/runtime lives under `@openfairygui/backend/node`.
+The root `@openfairygui/backend` entrypoint is browser-safe: pure authoring sessions can run in memory,
+and browser editors can inject an async storage adapter for OPFS, IndexedDB, ZIP-backed virtual filesystems,
+or File System Access API bridges. Storage adapters must implement `unlink()` so resource rename/move/remove
+can clean up stale source files. The default Node filesystem/runtime lives under `@openfairygui/backend/node`.
+File-backed `openSession` hydrates primary resource bytes so browser-safe transactions can rename/move
+assets or add/replace/remove binary resources. `saveSession` writes replacement bytes before it removes
+stale source files, preserving the prior file when a write fails.
+It also compares the source project with a UAM round trip through `ProjectWriter`; sessions with
+unrepresented persisted properties expose `uamFidelity: 'unsupported'`, and write attempts fail with
+`uam_fidelity_unsupported`. Transactions, saves, and materialization are serialized per session.
 
 ## Relationship to other packages
 
@@ -58,6 +67,43 @@ const applied = await runtime.applyTransaction({
 });
 ```
 
+Browser-safe project session with injected storage:
+
+```ts
+import { BackendRuntime, createBackendStorageFileSystem } from '@openfairygui/backend';
+
+const fileSystem = createBackendStorageFileSystem({
+	async readFile(filePath) { return storage.readText(filePath); },
+	async readFileRaw(filePath) { return storage.readBytes(filePath); },
+	async writeFile(filePath, content) { await storage.writeText(filePath, content); },
+	async writeFileRaw(filePath, data) { await storage.writeBytes(filePath, data); },
+	async mkdir(dirPath) { await storage.mkdir(dirPath); },
+	async readdir(dirPath) { return storage.readdir(dirPath); },
+	async exists(filePath) { return storage.exists(filePath); },
+	async unlink(filePath) { await storage.remove(filePath); },
+});
+
+const runtime = new BackendRuntime();
+const opened = runtime.openProjectSession({
+	project: uamProject,
+	storage: {
+		fileSystem,
+		fairyPath: 'Project.fairy',
+	},
+});
+if (!opened.ok) throw new Error(opened.error.message);
+
+const bootstrapped = await runtime.materializeSession({
+	sessionId: opened.data.sessionId,
+	expectedRevision: opened.data.revision,
+	mode: 'fullProject',
+	reason: 'workspace_bootstrap',
+});
+if (!bootstrapped.ok) throw new Error(bootstrapped.error.message);
+
+console.log(bootstrapped.data.writtenPaths);
+```
+
 Node file-backed session:
 
 ```ts

package/dist/index.cjs

@@ -1,6 +1,151 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_runtime = require("./runtime-BL9Pkfc7.cjs");
+const require_runtime = require("./runtime-D3bShb1X.cjs");
+//#region src/storage.ts
+var StorageFileStat = class {
+	constructor(kind) {
+		this.kind = kind;
+	}
+	isFile() {
+		return this.kind === "file";
+	}
+	isDirectory() {
+		return this.kind === "directory";
+	}
+};
+function createPathError(code, message) {
+	const error = new Error(message);
+	error.code = code;
+	return error;
+}
+function normalizeStoragePath(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
+	const absolute = normalized.startsWith("/");
+	const rawSegments = normalized.split("/").filter((segment) => segment.length > 0);
+	const segments = [];
+	for (const segment of rawSegments) {
+		if (segment === ".") continue;
+		if (segment === "..") {
+			if (segments.length > 0) segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+	const joined = segments.join("/");
+	if (absolute) return joined ? `/${joined}` : "/";
+	return joined || ".";
+}
+function joinStoragePath(...paths) {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join("/"));
+}
+function dirnameStoragePath(filePath) {
+	const normalized = normalizeStoragePath(filePath);
+	if (normalized === "/" || normalized === ".") return ".";
+	const absolute = normalized.startsWith("/");
+	const parts = normalized.split("/").filter((part) => part.length > 0);
+	parts.pop();
+	if (parts.length === 0) return absolute ? "/" : ".";
+	return `${absolute ? "/" : ""}${parts.join("/")}`;
+}
+function statFromLike(stat) {
+	if (typeof stat.isFile === "function" && typeof stat.isDirectory === "function") return stat;
+	const kind = stat.kind ?? stat.type;
+	if (kind === "file" || kind === "directory") return new StorageFileStat(kind);
+	throw createPathError("EINVAL", "Storage stat must provide kind/type or isFile()/isDirectory().");
+}
+async function inferStat(storage, filePath) {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat("directory");
+	} catch {}
+	try {
+		await storage.readFileRaw(filePath);
+		return new StorageFileStat("file");
+	} catch {
+		try {
+			await storage.readFile(filePath);
+			return new StorageFileStat("file");
+		} catch {
+			throw createPathError("ENOENT", `Storage path not found: ${filePath}`);
+		}
+	}
+}
+function createBackendStorageFileSystem(storage) {
+	if (typeof storage.unlink !== "function") throw createPathError("ENOTSUP", "Storage adapter must provide unlink() for project resource lifecycle writes.");
+	const lockedPaths = /* @__PURE__ */ new Set();
+	const fileSystem = {
+		stat(filePath) {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath) {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath) {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath) {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath, content) {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath, data) {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath, options) {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath) {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
+		},
+		async openExclusive(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			if (storage.openExclusive) return storage.openExclusive(resolved);
+			if (lockedPaths.has(resolved) || await fileSystem.exists(resolved)) throw createPathError("EEXIST", `Storage path already exists: ${resolved}`);
+			lockedPaths.add(resolved);
+			let closed = false;
+			return {
+				async writeFile(content) {
+					if (closed) throw createPathError("EBADF", `Storage lock handle is closed: ${resolved}`);
+					await fileSystem.mkdir(fileSystem.dirname(resolved), { recursive: true });
+					await storage.writeFile(resolved, content);
+				},
+				async close() {
+					closed = true;
+					lockedPaths.delete(resolved);
+				}
+			};
+		},
+		unlink(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			lockedPaths.delete(resolved);
+			return storage.unlink(resolved);
+		},
+		join(...paths) {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath) {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths) {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		}
+	};
+	return fileSystem;
+}
+//#endregion
 exports.BACKEND_CAPABILITY_SCHEMA_VERSION = require_runtime.BACKEND_CAPABILITY_SCHEMA_VERSION;
 exports.BACKEND_COMPATIBILITY_POLICY = require_runtime.BACKEND_COMPATIBILITY_POLICY;
 exports.BACKEND_CONTRACT_VERSION = require_runtime.BACKEND_CONTRACT_VERSION;
 exports.BackendRuntime = require_runtime.BackendRuntime;
+exports.createBackendStorageFileSystem = createBackendStorageFileSystem;

package/dist/index.d.cts

@@ -1,2 +1,33 @@
-import { A as BackendSuccess, B as OpenProjectSessionInput, C as BackendJobProgress, D as BackendRuntime, E as BackendResult, F as GetEventsInput, G as BACKEND_CAPABILITY_SCHEMA_VERSION, H as SavePartialFailureError, I as GetEventsSnapshot, J as BackendDiagnostic, K as BACKEND_COMPATIBILITY_POLICY, L as GetJobInput, M as CancelJobInput, N as EventCursorInvalidError, O as BackendRuntimeOptions, P as GetCacheSnapshotInput, R as InProcessLockConflictError, S as BackendJobNotFoundError, T as BackendJobStatus, U as SessionNotFoundError, V as RefreshCacheInput, W as SessionStaleWriteError, X as BackendResponseMeta, Y as BackendMessage, Z as BackendStage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as CacheRefreshFailedError, k as BackendSessionSnapshot, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CONTRACT_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as ListJobsInput } from "./runtime-qcSlD_9-.cjs";
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SessionNotFoundError, type SessionStaleWriteError };
+import { $ as BACKEND_COMPATIBILITY_POLICY, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobNotFoundError, D as BackendProjectSessionStorage, E as BackendJobStatus, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendResult, P as EventCursorInvalidError, Q as BACKEND_CAPABILITY_SCHEMA_VERSION, R as GetJobInput, S as BackendJobNotCancellableError, T as BackendJobSnapshot, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as UamFidelityUnsupportedError, _ as BackendHostAdapter, a as BackendCacheEntry, b as BackendJobListSnapshot, c as BackendCapabilityManifest, d as BackendEvent, et as BACKEND_CONTRACT_VERSION, f as BackendEventKind, g as BackendFileSystem, h as BackendFileStat, i as BackendArtifactBridgeCapability, it as BackendStage, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendCapabilityUnavailableError, m as BackendFileHandle, n as AdvisoryLockConflictError, nt as BackendMessage, o as BackendCacheSnapshot, p as BackendFailure, q as SavePartialFailureError, r as ApplySessionTransactionInput, rt as BackendResponseMeta, s as BackendCapabilities, t as BackendRuntime, tt as BackendDiagnostic, u as BackendError, v as BackendJobErrors, w as BackendJobProgress, x as BackendJobListStatusFilter, y as BackendJobKind, z as InProcessLockConflictError } from "./runtime-BB_3Ws5y.cjs";
+import { FileSystem } from "@openfairygui/core/project-io";
+
+//#region src/storage.d.ts
+type StorageStatKind = 'file' | 'directory';
+interface BackendStorageStatLike {
+  kind?: StorageStatKind;
+  type?: StorageStatKind;
+  isFile?(): boolean;
+  isDirectory?(): boolean;
+}
+interface BackendAsyncStorageAdapter {
+  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>;
+  readdir(dirPath: string): Promise<string[]>;
+  exists?(filePath: string): Promise<boolean>;
+  stat?(filePath: string): Promise<BackendStorageStatLike>;
+  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;
+}
+type BackendStorageFileSystem = BackendFileSystem & FileSystem;
+declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
+//#endregion
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, 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, createBackendStorageFileSystem };

package/dist/index.d.mts

@@ -1,2 +1,33 @@
-import { A as BackendSuccess, B as OpenProjectSessionInput, C as BackendJobProgress, D as BackendRuntime, E as BackendResult, F as GetEventsInput, G as BACKEND_CAPABILITY_SCHEMA_VERSION, H as SavePartialFailureError, I as GetEventsSnapshot, J as BackendDiagnostic, K as BACKEND_COMPATIBILITY_POLICY, L as GetJobInput, M as CancelJobInput, N as EventCursorInvalidError, O as BackendRuntimeOptions, P as GetCacheSnapshotInput, R as InProcessLockConflictError, S as BackendJobNotFoundError, T as BackendJobStatus, U as SessionNotFoundError, V as RefreshCacheInput, W as SessionStaleWriteError, X as BackendResponseMeta, Y as BackendMessage, Z as BackendStage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as CacheRefreshFailedError, k as BackendSessionSnapshot, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CONTRACT_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as ListJobsInput } from "./runtime-OO1sHuCl.mjs";
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SessionNotFoundError, type SessionStaleWriteError };
+import { $ as BACKEND_COMPATIBILITY_POLICY, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobNotFoundError, D as BackendProjectSessionStorage, E as BackendJobStatus, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendResult, P as EventCursorInvalidError, Q as BACKEND_CAPABILITY_SCHEMA_VERSION, R as GetJobInput, S as BackendJobNotCancellableError, T as BackendJobSnapshot, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as UamFidelityUnsupportedError, _ as BackendHostAdapter, a as BackendCacheEntry, b as BackendJobListSnapshot, c as BackendCapabilityManifest, d as BackendEvent, et as BACKEND_CONTRACT_VERSION, f as BackendEventKind, g as BackendFileSystem, h as BackendFileStat, i as BackendArtifactBridgeCapability, it as BackendStage, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendCapabilityUnavailableError, m as BackendFileHandle, n as AdvisoryLockConflictError, nt as BackendMessage, o as BackendCacheSnapshot, p as BackendFailure, q as SavePartialFailureError, r as ApplySessionTransactionInput, rt as BackendResponseMeta, s as BackendCapabilities, t as BackendRuntime, tt as BackendDiagnostic, u as BackendError, v as BackendJobErrors, w as BackendJobProgress, x as BackendJobListStatusFilter, y as BackendJobKind, z as InProcessLockConflictError } from "./runtime-B4SwHTRC.mjs";
+import { FileSystem } from "@openfairygui/core/project-io";
+
+//#region src/storage.d.ts
+type StorageStatKind = 'file' | 'directory';
+interface BackendStorageStatLike {
+  kind?: StorageStatKind;
+  type?: StorageStatKind;
+  isFile?(): boolean;
+  isDirectory?(): boolean;
+}
+interface BackendAsyncStorageAdapter {
+  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>;
+  readdir(dirPath: string): Promise<string[]>;
+  exists?(filePath: string): Promise<boolean>;
+  stat?(filePath: string): Promise<BackendStorageStatLike>;
+  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;
+}
+type BackendStorageFileSystem = BackendFileSystem & FileSystem;
+declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
+//#endregion
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, 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, createBackendStorageFileSystem };

package/dist/index.mjs

@@ -1,2 +1,146 @@
-import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-BPWzx-Tv.mjs";
-export { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, BackendRuntime };
+import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-CqGK_D9A.mjs";
+//#region src/storage.ts
+var StorageFileStat = class {
+	constructor(kind) {
+		this.kind = kind;
+	}
+	isFile() {
+		return this.kind === "file";
+	}
+	isDirectory() {
+		return this.kind === "directory";
+	}
+};
+function createPathError(code, message) {
+	const error = new Error(message);
+	error.code = code;
+	return error;
+}
+function normalizeStoragePath(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
+	const absolute = normalized.startsWith("/");
+	const rawSegments = normalized.split("/").filter((segment) => segment.length > 0);
+	const segments = [];
+	for (const segment of rawSegments) {
+		if (segment === ".") continue;
+		if (segment === "..") {
+			if (segments.length > 0) segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+	const joined = segments.join("/");
+	if (absolute) return joined ? `/${joined}` : "/";
+	return joined || ".";
+}
+function joinStoragePath(...paths) {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join("/"));
+}
+function dirnameStoragePath(filePath) {
+	const normalized = normalizeStoragePath(filePath);
+	if (normalized === "/" || normalized === ".") return ".";
+	const absolute = normalized.startsWith("/");
+	const parts = normalized.split("/").filter((part) => part.length > 0);
+	parts.pop();
+	if (parts.length === 0) return absolute ? "/" : ".";
+	return `${absolute ? "/" : ""}${parts.join("/")}`;
+}
+function statFromLike(stat) {
+	if (typeof stat.isFile === "function" && typeof stat.isDirectory === "function") return stat;
+	const kind = stat.kind ?? stat.type;
+	if (kind === "file" || kind === "directory") return new StorageFileStat(kind);
+	throw createPathError("EINVAL", "Storage stat must provide kind/type or isFile()/isDirectory().");
+}
+async function inferStat(storage, filePath) {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat("directory");
+	} catch {}
+	try {
+		await storage.readFileRaw(filePath);
+		return new StorageFileStat("file");
+	} catch {
+		try {
+			await storage.readFile(filePath);
+			return new StorageFileStat("file");
+		} catch {
+			throw createPathError("ENOENT", `Storage path not found: ${filePath}`);
+		}
+	}
+}
+function createBackendStorageFileSystem(storage) {
+	if (typeof storage.unlink !== "function") throw createPathError("ENOTSUP", "Storage adapter must provide unlink() for project resource lifecycle writes.");
+	const lockedPaths = /* @__PURE__ */ new Set();
+	const fileSystem = {
+		stat(filePath) {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath) {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath) {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath) {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath, content) {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath, data) {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath, options) {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath) {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
+		},
+		async openExclusive(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			if (storage.openExclusive) return storage.openExclusive(resolved);
+			if (lockedPaths.has(resolved) || await fileSystem.exists(resolved)) throw createPathError("EEXIST", `Storage path already exists: ${resolved}`);
+			lockedPaths.add(resolved);
+			let closed = false;
+			return {
+				async writeFile(content) {
+					if (closed) throw createPathError("EBADF", `Storage lock handle is closed: ${resolved}`);
+					await fileSystem.mkdir(fileSystem.dirname(resolved), { recursive: true });
+					await storage.writeFile(resolved, content);
+				},
+				async close() {
+					closed = true;
+					lockedPaths.delete(resolved);
+				}
+			};
+		},
+		unlink(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			lockedPaths.delete(resolved);
+			return storage.unlink(resolved);
+		},
+		join(...paths) {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath) {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths) {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		}
+	};
+	return fileSystem;
+}
+//#endregion
+export { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, BackendRuntime, createBackendStorageFileSystem };

package/dist/node.cjs

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_runtime = require("./runtime-BL9Pkfc7.cjs");
+const require_runtime = require("./runtime-D3bShb1X.cjs");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises);
 let node_path = require("node:path");

package/dist/node.d.cts

@@ -1,4 +1,4 @@
-import { D as BackendRuntime, O as BackendRuntimeOptions, g as BackendHostAdapter, h as BackendFileSystem, m as BackendFileStat, p as BackendFileHandle } from "./runtime-qcSlD_9-.cjs";
+import { _ as BackendHostAdapter, g as BackendFileSystem, h as BackendFileStat, k as BackendRuntimeOptions, m as BackendFileHandle, t as BackendRuntime } from "./runtime-BB_3Ws5y.cjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { D as BackendRuntime, O as BackendRuntimeOptions, g as BackendHostAdapter, h as BackendFileSystem, m as BackendFileStat, p as BackendFileHandle } from "./runtime-OO1sHuCl.mjs";
+import { _ as BackendHostAdapter, g as BackendFileSystem, h as BackendFileStat, k as BackendRuntimeOptions, m as BackendFileHandle, t as BackendRuntime } from "./runtime-B4SwHTRC.mjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { t as BackendRuntime } from "./runtime-BPWzx-Tv.mjs";
+import { t as BackendRuntime } from "./runtime-CqGK_D9A.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 //#region src/node.ts