@fragno-dev/tanstack-db-adapter 0.0.0-stage → 0.0.0

package/dist/coordinator/fragno-browser-persistence-startup.js

@@ -0,0 +1,366 @@
+//#region src/coordinator/fragno-browser-persistence-startup.ts
+const FRAGNO_BROWSER_PERSISTENCE_DIAGNOSTICS_INTERVAL_MS = 3e3;
+const FRAGNO_BROWSER_PERSISTENCE_INSPECTION_TIMEOUT_MS = 1e3;
+/** Opens browser persistence immediately while an observational worker probe reports startup diagnostics. */
+async function openFragnoBrowserPersistenceWithDiagnostics(options) {
+	const startedAt = Date.now();
+	const workerProbe = startFragnoBrowserWorkerProbe();
+	const diagnosticsInspectors = createFragnoBrowserPersistenceDiagnosticInspectors(options.databaseName);
+	let settled = false;
+	let expectedDiagnosticsElapsedMs = FRAGNO_BROWSER_PERSISTENCE_DIAGNOSTICS_INTERVAL_MS;
+	let diagnosticsTimer;
+	function scheduleDiagnostics() {
+		diagnosticsTimer = setTimeout(() => {
+			const elapsedMs = Date.now() - startedAt;
+			collectFragnoBrowserPersistenceDiagnostics({
+				databaseName: options.databaseName,
+				elapsedMs,
+				timerDriftMs: Math.max(0, elapsedMs - expectedDiagnosticsElapsedMs),
+				workerProbe: workerProbe.snapshot(),
+				inspectors: diagnosticsInspectors
+			}).then((diagnostics) => {
+				if (settled) return;
+				console.warn(`Fragno outbox browser persistence is still opening after ${diagnostics.elapsedMs}ms. ${diagnostics.likelyCause} Initialization will keep waiting.`, diagnostics);
+				try {
+					options.onDiagnostic?.(diagnostics);
+				} catch (error) {
+					console.error("Fragno browser persistence diagnostic listener failed.", error);
+				}
+				expectedDiagnosticsElapsedMs += FRAGNO_BROWSER_PERSISTENCE_DIAGNOSTICS_INTERVAL_MS;
+				scheduleDiagnostics();
+			});
+		}, FRAGNO_BROWSER_PERSISTENCE_DIAGNOSTICS_INTERVAL_MS);
+	}
+	scheduleDiagnostics();
+	try {
+		return await options.openPersistence();
+	} finally {
+		settled = true;
+		clearTimeout(diagnosticsTimer);
+		workerProbe.cleanup();
+	}
+}
+function startFragnoBrowserWorkerProbe() {
+	const browserGlobal = globalThis;
+	if (typeof browserGlobal.Worker !== "function" || typeof browserGlobal.Blob !== "function" || typeof browserGlobal.URL?.createObjectURL !== "function") return {
+		snapshot: () => ({
+			status: "unsupported",
+			reason: "Dedicated worker probing is unavailable in this runtime."
+		}),
+		cleanup() {}
+	};
+	const startedAt = Date.now();
+	let snapshot = {
+		status: "starting",
+		elapsedMs: 0
+	};
+	let worker = null;
+	let workerUrl = null;
+	function cleanup() {
+		worker?.terminate();
+		worker = null;
+		if (workerUrl) {
+			browserGlobal.URL.revokeObjectURL(workerUrl);
+			workerUrl = null;
+		}
+	}
+	try {
+		workerUrl = browserGlobal.URL.createObjectURL(new browserGlobal.Blob([`globalThis.postMessage({
+      type: "fragno-browser-worker-ready",
+      timerAvailable: typeof globalThis.setTimeout === "function",
+      opfsAvailable: typeof globalThis.navigator?.storage?.getDirectory === "function",
+      fileSystemFileHandleGlobalAvailable: typeof globalThis.FileSystemFileHandle === "function",
+      syncAccessHandlePrototypeAvailable:
+        typeof globalThis.FileSystemFileHandle?.prototype?.createSyncAccessHandle === "function",
+    });`], { type: "text/javascript" }));
+		worker = new browserGlobal.Worker(workerUrl);
+		worker.addEventListener("message", (event) => {
+			const runtime = event.data;
+			snapshot = {
+				status: "responsive",
+				responseMs: Date.now() - startedAt,
+				runtime: {
+					timerAvailable: runtime.timerAvailable,
+					opfsAvailable: runtime.opfsAvailable,
+					fileSystemFileHandleGlobalAvailable: runtime.fileSystemFileHandleGlobalAvailable,
+					syncAccessHandlePrototypeAvailable: runtime.syncAccessHandlePrototypeAvailable
+				}
+			};
+			cleanup();
+		});
+		worker.addEventListener("error", (event) => {
+			snapshot = {
+				status: "failed",
+				error: event.message || "Dedicated worker probe failed without an error message."
+			};
+			cleanup();
+		});
+		worker.addEventListener("messageerror", () => {
+			snapshot = {
+				status: "failed",
+				error: "Dedicated worker probe response could not be deserialized."
+			};
+			cleanup();
+		});
+	} catch (error) {
+		snapshot = {
+			status: "failed",
+			error: describeFragnoBrowserDiagnosticError(error)
+		};
+		cleanup();
+	}
+	return {
+		snapshot() {
+			if (snapshot.status !== "starting") return snapshot;
+			return {
+				status: "starting",
+				elapsedMs: Date.now() - startedAt
+			};
+		},
+		cleanup
+	};
+}
+function createFragnoBrowserPersistenceDiagnosticInspectors(databaseName) {
+	return {
+		webLocks: createRecurringFragnoBrowserDiagnosticInspector("Web Locks inspection", () => inspectFragnoBrowserLocks(databaseName)),
+		storageEstimate: createRecurringFragnoBrowserDiagnosticInspector("Storage estimate inspection", inspectFragnoBrowserStorageEstimate),
+		persistedStorage: createRecurringFragnoBrowserDiagnosticInspector("Persisted storage inspection", inspectFragnoBrowserPersistedStorage),
+		opfsEntries: createRecurringFragnoBrowserDiagnosticInspector("OPFS inspection", () => inspectFragnoBrowserOPFSEntries(databaseName))
+	};
+}
+function createRecurringFragnoBrowserDiagnosticInspector(inspectionName, inspect) {
+	let activeInspection = null;
+	return function inspectFragnoBrowserDiagnostic() {
+		if (activeInspection === null) activeInspection = inspect().finally(() => {
+			activeInspection = null;
+		});
+		return waitForFragnoBrowserDiagnosticInspection(inspectionName, activeInspection);
+	};
+}
+function waitForFragnoBrowserDiagnosticInspection(inspectionName, inspection) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const timeout = setTimeout(() => {
+			settled = true;
+			resolve({
+				status: "failed",
+				error: `${inspectionName} timed out after ${FRAGNO_BROWSER_PERSISTENCE_INSPECTION_TIMEOUT_MS}ms.`
+			});
+		}, FRAGNO_BROWSER_PERSISTENCE_INSPECTION_TIMEOUT_MS);
+		inspection.then((diagnostic) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			resolve(diagnostic);
+		}, (error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			resolve({
+				status: "failed",
+				error: describeFragnoBrowserDiagnosticError(error)
+			});
+		});
+	});
+}
+async function collectFragnoBrowserPersistenceDiagnostics(options) {
+	const browserGlobal = globalThis;
+	const browserNavigator = browserGlobal.navigator;
+	const browserDocument = browserGlobal.document;
+	const browserLocation = browserGlobal.location;
+	const [webLocks, storageEstimate, persistedStorage, opfsEntries] = await Promise.all([
+		options.inspectors.webLocks(),
+		options.inspectors.storageEstimate(),
+		options.inspectors.persistedStorage(),
+		options.inspectors.opfsEntries()
+	]);
+	const visibilityState = browserDocument?.visibilityState ?? null;
+	const likelyCause = diagnoseFragnoBrowserPersistenceStall({
+		visibilityState,
+		workerProbe: options.workerProbe,
+		webLocks
+	});
+	return {
+		databaseName: options.databaseName,
+		elapsedMs: options.elapsedMs,
+		timerDriftMs: options.timerDriftMs,
+		collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		likelyCause,
+		workerProbe: options.workerProbe,
+		runtime: {
+			href: browserLocation?.href ?? null,
+			origin: browserLocation?.origin ?? null,
+			userAgent: browserNavigator?.userAgent ?? null,
+			visibilityState,
+			readyState: browserDocument?.readyState ?? null,
+			documentHasFocus: browserDocument?.hasFocus() ?? null,
+			isSecureContext: browserGlobal.isSecureContext ?? false,
+			crossOriginIsolated: browserGlobal.crossOriginIsolated ?? false,
+			online: browserNavigator?.onLine ?? null,
+			hardwareConcurrency: browserNavigator?.hardwareConcurrency ?? null,
+			workerAvailable: typeof browserGlobal.Worker === "function",
+			broadcastChannelAvailable: typeof browserGlobal.BroadcastChannel === "function",
+			webLocksAvailable: typeof browserNavigator?.locks?.query === "function",
+			opfsAvailable: typeof browserNavigator?.storage?.getDirectory === "function",
+			fileSystemFileHandleGlobalAvailable: typeof browserGlobal.FileSystemFileHandle === "function"
+		},
+		webLocks,
+		storageEstimate,
+		persistedStorage,
+		opfsEntries
+	};
+}
+function diagnoseFragnoBrowserPersistenceStall(options) {
+	const hasRelevantLocks = options.webLocks.status === "available" && (options.webLocks.value.relevantHeld.length > 0 || options.webLocks.value.relevantPending.length > 0);
+	if (options.workerProbe.status === "starting" && !hasRelevantLocks) {
+		if (options.visibilityState === "hidden") return "The diagnostic worker has not responded and OPFS has created no locks. The document is hidden, which may be contributing to worker scheduling delays in this Electron runtime; the SQLite persistence worker may also be waiting to execute.";
+		return "The diagnostic worker has not responded and OPFS has created no locks. The SQLite persistence worker may also be waiting to execute.";
+	}
+	if (options.workerProbe.status === "failed") return `Diagnostic worker startup failed: ${options.workerProbe.error}`;
+	if (options.webLocks.status === "available") return options.webLocks.value.interpretation;
+	return "The upstream persistence API has not completed and exposes no finer-grained initialization progress.";
+}
+async function inspectFragnoBrowserLocks(databaseName) {
+	try {
+		const lockManager = globalThis.navigator?.locks;
+		if (!lockManager?.query) return {
+			status: "unavailable",
+			reason: "Web Locks query is unavailable."
+		};
+		const snapshot = await lockManager.query();
+		const held = snapshot.held.map(materializeFragnoBrowserLock);
+		const pending = snapshot.pending.map(materializeFragnoBrowserLock);
+		const databaseLockName = `ahp:/${databaseName}`;
+		const isRelevantLock = (lock) => lock.name === databaseLockName || lock.name.startsWith(".ahp-");
+		const relevantHeld = held.filter(isRelevantLock);
+		const relevantPending = pending.filter(isRelevantLock);
+		let interpretation = "OPFS did not expose an active initialization lock.";
+		if (relevantPending.some((lock) => lock.name === databaseLockName)) interpretation = "OPFS is waiting to acquire the database access-handle lock.";
+		else if (relevantHeld.some((lock) => lock.name === databaseLockName)) interpretation = "OPFS acquired the database access-handle lock but did not finish opening SQLite.";
+		else if (relevantHeld.some((lock) => lock.name.startsWith(".ahp-"))) interpretation = "OPFS created its temporary VFS lock but has not requested the database access-handle lock.";
+		return {
+			status: "available",
+			value: {
+				held,
+				pending,
+				relevantHeld,
+				relevantPending,
+				interpretation
+			}
+		};
+	} catch (error) {
+		return {
+			status: "failed",
+			error: describeFragnoBrowserDiagnosticError(error)
+		};
+	}
+}
+async function inspectFragnoBrowserStorageEstimate() {
+	try {
+		const storage = globalThis.navigator?.storage;
+		if (!storage?.estimate) return {
+			status: "unavailable",
+			reason: "Storage estimate is unavailable."
+		};
+		const estimate = await storage.estimate();
+		return {
+			status: "available",
+			value: {
+				quota: estimate.quota ?? null,
+				usage: estimate.usage ?? null,
+				usageDetails: estimate.usageDetails ? { ...estimate.usageDetails } : null
+			}
+		};
+	} catch (error) {
+		return {
+			status: "failed",
+			error: describeFragnoBrowserDiagnosticError(error)
+		};
+	}
+}
+async function inspectFragnoBrowserPersistedStorage() {
+	try {
+		const storage = globalThis.navigator?.storage;
+		if (!storage?.persisted) return {
+			status: "unavailable",
+			reason: "Persisted storage status is unavailable."
+		};
+		return {
+			status: "available",
+			value: await storage.persisted()
+		};
+	} catch (error) {
+		return {
+			status: "failed",
+			error: describeFragnoBrowserDiagnosticError(error)
+		};
+	}
+}
+async function inspectFragnoBrowserOPFSEntries(databaseName) {
+	try {
+		const browserNavigator = globalThis.navigator;
+		const getDirectory = browserNavigator?.storage?.getDirectory;
+		if (!getDirectory) return {
+			status: "unavailable",
+			reason: "OPFS directory inspection is unavailable."
+		};
+		const root = await getDirectory.call(browserNavigator.storage);
+		const entries = [];
+		for await (const entry of iterateFragnoFileSystemDirectory(root)) {
+			if (!entry.name.startsWith(".ahp-") && !entry.name.startsWith(databaseName)) continue;
+			if (entry.kind === "file") {
+				entries.push({
+					kind: "file",
+					name: entry.name
+				});
+				continue;
+			}
+			try {
+				const children = [];
+				for await (const child of iterateFragnoFileSystemDirectory(entry)) children.push({
+					name: child.name,
+					kind: child.kind
+				});
+				entries.push({
+					kind: "directory",
+					name: entry.name,
+					entries: children,
+					inspectionError: null
+				});
+			} catch (error) {
+				entries.push({
+					kind: "directory",
+					name: entry.name,
+					entries: [],
+					inspectionError: describeFragnoBrowserDiagnosticError(error)
+				});
+			}
+		}
+		return {
+			status: "available",
+			value: entries
+		};
+	} catch (error) {
+		return {
+			status: "failed",
+			error: describeFragnoBrowserDiagnosticError(error)
+		};
+	}
+}
+function iterateFragnoFileSystemDirectory(directory) {
+	return directory.values();
+}
+function materializeFragnoBrowserLock(lock) {
+	return {
+		name: lock.name,
+		mode: lock.mode,
+		clientId: lock.clientId ?? null
+	};
+}
+function describeFragnoBrowserDiagnosticError(error) {
+	return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+//#endregion
+export { openFragnoBrowserPersistenceWithDiagnostics };
+
+//# sourceMappingURL=fragno-browser-persistence-startup.js.map

package/dist/coordinator/fragno-browser-persistence-startup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragno-browser-persistence-startup.js","names":[],"sources":["../../src/coordinator/fragno-browser-persistence-startup.ts"],"sourcesContent":["const FRAGNO_BROWSER_PERSISTENCE_DIAGNOSTICS_INTERVAL_MS = 3_000;\nconst FRAGNO_BROWSER_PERSISTENCE_INSPECTION_TIMEOUT_MS = 1_000;\n\ntype FragnoBrowserDiagnostic<TValue> =\n  | { status: \"available\"; value: TValue }\n  | { status: \"unavailable\"; reason: string }\n  | { status: \"failed\"; error: string };\n\ntype FragnoBrowserLock = {\n  name: string;\n  mode: string;\n  clientId: string | null;\n};\n\ntype FragnoBrowserLockSnapshot = {\n  held: FragnoBrowserLock[];\n  pending: FragnoBrowserLock[];\n  relevantHeld: FragnoBrowserLock[];\n  relevantPending: FragnoBrowserLock[];\n  interpretation: string;\n};\n\ntype FragnoBrowserStorageEstimate = {\n  quota: number | null;\n  usage: number | null;\n  usageDetails: Record<string, number> | null;\n};\n\ntype FragnoBrowserWorkerProbeSnapshot =\n  | { status: \"unsupported\"; reason: string }\n  | { status: \"starting\"; elapsedMs: number }\n  | {\n      status: \"responsive\";\n      responseMs: number;\n      runtime: {\n        timerAvailable: boolean;\n        opfsAvailable: boolean;\n        fileSystemFileHandleGlobalAvailable: boolean;\n        syncAccessHandlePrototypeAvailable: boolean;\n      };\n    }\n  | { status: \"failed\"; error: string };\n\ntype FragnoBrowserWorkerProbe = {\n  snapshot(): FragnoBrowserWorkerProbeSnapshot;\n  cleanup(): void;\n};\n\ntype FragnoOPFSEntry =\n  | { kind: \"file\"; name: string }\n  | {\n      kind: \"directory\";\n      name: string;\n      entries: Array<{ name: string; kind: string }>;\n      inspectionError: string | null;\n    };\n\ntype FragnoBrowserDiagnosticsGlobal = typeof globalThis & {\n  FileSystemFileHandle?: {\n    prototype?: { createSyncAccessHandle?: unknown };\n  };\n  navigator?: Navigator & {\n    storage?: StorageManager & {\n      getDirectory?: () => Promise<FileSystemDirectoryHandle>;\n    };\n  };\n};\n\n/** Captures worker, runtime, storage, Web Locks, and OPFS state during a stalled browser startup. */\nexport type FragnoBrowserPersistenceDiagnostics = {\n  databaseName: string;\n  elapsedMs: number;\n  timerDriftMs: number;\n  collectedAt: string;\n  likelyCause: string;\n  workerProbe: FragnoBrowserWorkerProbeSnapshot;\n  runtime: {\n    href: string | null;\n    origin: string | null;\n    userAgent: string | null;\n    visibilityState: DocumentVisibilityState | null;\n    readyState: DocumentReadyState | null;\n    documentHasFocus: boolean | null;\n    isSecureContext: boolean;\n    crossOriginIsolated: boolean;\n    online: boolean | null;\n    hardwareConcurrency: number | null;\n    workerAvailable: boolean;\n    broadcastChannelAvailable: boolean;\n    webLocksAvailable: boolean;\n    opfsAvailable: boolean;\n    fileSystemFileHandleGlobalAvailable: boolean;\n  };\n  webLocks: FragnoBrowserDiagnostic<FragnoBrowserLockSnapshot>;\n  storageEstimate: FragnoBrowserDiagnostic<FragnoBrowserStorageEstimate>;\n  persistedStorage: FragnoBrowserDiagnostic<boolean>;\n  opfsEntries: FragnoBrowserDiagnostic<FragnoOPFSEntry[]>;\n};\n\ntype FragnoBrowserPersistenceStartupOptions<TResource> = {\n  databaseName: string;\n  onDiagnostic: ((diagnostics: FragnoBrowserPersistenceDiagnostics) => void) | null;\n  openPersistence(): Promise<TResource>;\n};\n\ntype FragnoBrowserPersistenceDiagnosticInspectors = {\n  webLocks(): Promise<FragnoBrowserDiagnostic<FragnoBrowserLockSnapshot>>;\n  storageEstimate(): Promise<FragnoBrowserDiagnostic<FragnoBrowserStorageEstimate>>;\n  persistedStorage(): Promise<FragnoBrowserDiagnostic<boolean>>;\n  opfsEntries(): Promise<FragnoBrowserDiagnostic<FragnoOPFSEntry[]>>;\n};\n\n/** Opens browser persistence immediately while an observational worker probe reports startup diagnostics. */\nexport async function openFragnoBrowserPersistenceWithDiagnostics<TResource>(\n  options: FragnoBrowserPersistenceStartupOptions<TResource>,\n): Promise<TResource> {\n  const startedAt = Date.now();\n  const workerProbe = startFragnoBrowserWorkerProbe();\n  const diagnosticsInspectors = createFragnoBrowserPersistenceDiagnosticInspectors(\n    options.databaseName,\n  );\n  let settled = false;\n  let expectedDiagnosticsElapsedMs = FRAGNO_BROWSER_PERSISTENCE_DIAGNOSTICS_INTERVAL_MS;\n  let diagnosticsTimer: ReturnType<typeof setTimeout> | undefined;\n\n  function scheduleDiagnostics() {\n    diagnosticsTimer = setTimeout(() => {\n      const elapsedMs = Date.now() - startedAt;\n      void collectFragnoBrowserPersistenceDiagnostics({\n        databaseName: options.databaseName,\n        elapsedMs,\n        timerDriftMs: Math.max(0, elapsedMs - expectedDiagnosticsElapsedMs),\n        workerProbe: workerProbe.snapshot(),\n        inspectors: diagnosticsInspectors,\n      }).then((diagnostics) => {\n        if (settled) {\n          return;\n        }\n\n        console.warn(\n          `Fragno outbox browser persistence is still opening after ${diagnostics.elapsedMs}ms. ${diagnostics.likelyCause} Initialization will keep waiting.`,\n          diagnostics,\n        );\n        try {\n          options.onDiagnostic?.(diagnostics);\n        } catch (error) {\n          console.error(\"Fragno browser persistence diagnostic listener failed.\", error);\n        }\n        expectedDiagnosticsElapsedMs += FRAGNO_BROWSER_PERSISTENCE_DIAGNOSTICS_INTERVAL_MS;\n        scheduleDiagnostics();\n      });\n    }, FRAGNO_BROWSER_PERSISTENCE_DIAGNOSTICS_INTERVAL_MS);\n  }\n\n  scheduleDiagnostics();\n  try {\n    return await options.openPersistence();\n  } finally {\n    settled = true;\n    clearTimeout(diagnosticsTimer);\n    workerProbe.cleanup();\n  }\n}\n\nfunction startFragnoBrowserWorkerProbe(): FragnoBrowserWorkerProbe {\n  const browserGlobal = globalThis as FragnoBrowserDiagnosticsGlobal;\n  if (\n    typeof browserGlobal.Worker !== \"function\" ||\n    typeof browserGlobal.Blob !== \"function\" ||\n    typeof browserGlobal.URL?.createObjectURL !== \"function\"\n  ) {\n    return {\n      snapshot: () => ({\n        status: \"unsupported\",\n        reason: \"Dedicated worker probing is unavailable in this runtime.\",\n      }),\n      cleanup() {},\n    };\n  }\n\n  const startedAt = Date.now();\n  let snapshot: FragnoBrowserWorkerProbeSnapshot = { status: \"starting\", elapsedMs: 0 };\n  let worker: Worker | null = null;\n  let workerUrl: string | null = null;\n\n  function cleanup() {\n    worker?.terminate();\n    worker = null;\n    if (workerUrl) {\n      browserGlobal.URL.revokeObjectURL(workerUrl);\n      workerUrl = null;\n    }\n  }\n\n  try {\n    const source = `globalThis.postMessage({\n      type: \"fragno-browser-worker-ready\",\n      timerAvailable: typeof globalThis.setTimeout === \"function\",\n      opfsAvailable: typeof globalThis.navigator?.storage?.getDirectory === \"function\",\n      fileSystemFileHandleGlobalAvailable: typeof globalThis.FileSystemFileHandle === \"function\",\n      syncAccessHandlePrototypeAvailable:\n        typeof globalThis.FileSystemFileHandle?.prototype?.createSyncAccessHandle === \"function\",\n    });`;\n    workerUrl = browserGlobal.URL.createObjectURL(\n      new browserGlobal.Blob([source], { type: \"text/javascript\" }),\n    );\n    worker = new browserGlobal.Worker(workerUrl);\n    worker.addEventListener(\"message\", (event: MessageEvent<unknown>) => {\n      const runtime = event.data as {\n        type: \"fragno-browser-worker-ready\";\n        timerAvailable: boolean;\n        opfsAvailable: boolean;\n        fileSystemFileHandleGlobalAvailable: boolean;\n        syncAccessHandlePrototypeAvailable: boolean;\n      };\n      snapshot = {\n        status: \"responsive\",\n        responseMs: Date.now() - startedAt,\n        runtime: {\n          timerAvailable: runtime.timerAvailable,\n          opfsAvailable: runtime.opfsAvailable,\n          fileSystemFileHandleGlobalAvailable: runtime.fileSystemFileHandleGlobalAvailable,\n          syncAccessHandlePrototypeAvailable: runtime.syncAccessHandlePrototypeAvailable,\n        },\n      };\n      cleanup();\n    });\n    worker.addEventListener(\"error\", (event: ErrorEvent) => {\n      snapshot = {\n        status: \"failed\",\n        error: event.message || \"Dedicated worker probe failed without an error message.\",\n      };\n      cleanup();\n    });\n    worker.addEventListener(\"messageerror\", () => {\n      snapshot = {\n        status: \"failed\",\n        error: \"Dedicated worker probe response could not be deserialized.\",\n      };\n      cleanup();\n    });\n  } catch (error) {\n    snapshot = { status: \"failed\", error: describeFragnoBrowserDiagnosticError(error) };\n    cleanup();\n  }\n\n  return {\n    snapshot() {\n      if (snapshot.status !== \"starting\") {\n        return snapshot;\n      }\n      return { status: \"starting\", elapsedMs: Date.now() - startedAt };\n    },\n    cleanup,\n  };\n}\n\nfunction createFragnoBrowserPersistenceDiagnosticInspectors(\n  databaseName: string,\n): FragnoBrowserPersistenceDiagnosticInspectors {\n  return {\n    webLocks: createRecurringFragnoBrowserDiagnosticInspector(\"Web Locks inspection\", () =>\n      inspectFragnoBrowserLocks(databaseName),\n    ),\n    storageEstimate: createRecurringFragnoBrowserDiagnosticInspector(\n      \"Storage estimate inspection\",\n      inspectFragnoBrowserStorageEstimate,\n    ),\n    persistedStorage: createRecurringFragnoBrowserDiagnosticInspector(\n      \"Persisted storage inspection\",\n      inspectFragnoBrowserPersistedStorage,\n    ),\n    opfsEntries: createRecurringFragnoBrowserDiagnosticInspector(\"OPFS inspection\", () =>\n      inspectFragnoBrowserOPFSEntries(databaseName),\n    ),\n  };\n}\n\nfunction createRecurringFragnoBrowserDiagnosticInspector<TValue>(\n  inspectionName: string,\n  inspect: () => Promise<FragnoBrowserDiagnostic<TValue>>,\n): () => Promise<FragnoBrowserDiagnostic<TValue>> {\n  let activeInspection: Promise<FragnoBrowserDiagnostic<TValue>> | null = null;\n\n  return function inspectFragnoBrowserDiagnostic() {\n    if (activeInspection === null) {\n      activeInspection = inspect().finally(() => {\n        activeInspection = null;\n      });\n    }\n\n    return waitForFragnoBrowserDiagnosticInspection(inspectionName, activeInspection);\n  };\n}\n\nfunction waitForFragnoBrowserDiagnosticInspection<TValue>(\n  inspectionName: string,\n  inspection: Promise<FragnoBrowserDiagnostic<TValue>>,\n): Promise<FragnoBrowserDiagnostic<TValue>> {\n  return new Promise((resolve) => {\n    let settled = false;\n    const timeout = setTimeout(() => {\n      settled = true;\n      resolve({\n        status: \"failed\",\n        error: `${inspectionName} timed out after ${FRAGNO_BROWSER_PERSISTENCE_INSPECTION_TIMEOUT_MS}ms.`,\n      });\n    }, FRAGNO_BROWSER_PERSISTENCE_INSPECTION_TIMEOUT_MS);\n\n    void inspection.then(\n      (diagnostic) => {\n        if (settled) {\n          return;\n        }\n        settled = true;\n        clearTimeout(timeout);\n        resolve(diagnostic);\n      },\n      (error: unknown) => {\n        if (settled) {\n          return;\n        }\n        settled = true;\n        clearTimeout(timeout);\n        resolve({ status: \"failed\", error: describeFragnoBrowserDiagnosticError(error) });\n      },\n    );\n  });\n}\n\nasync function collectFragnoBrowserPersistenceDiagnostics(options: {\n  databaseName: string;\n  elapsedMs: number;\n  timerDriftMs: number;\n  workerProbe: FragnoBrowserWorkerProbeSnapshot;\n  inspectors: FragnoBrowserPersistenceDiagnosticInspectors;\n}): Promise<FragnoBrowserPersistenceDiagnostics> {\n  const browserGlobal = globalThis as FragnoBrowserDiagnosticsGlobal;\n  const browserNavigator = browserGlobal.navigator;\n  const browserDocument = browserGlobal.document;\n  const browserLocation = browserGlobal.location;\n\n  const [webLocks, storageEstimate, persistedStorage, opfsEntries] = await Promise.all([\n    options.inspectors.webLocks(),\n    options.inspectors.storageEstimate(),\n    options.inspectors.persistedStorage(),\n    options.inspectors.opfsEntries(),\n  ]);\n\n  const visibilityState = browserDocument?.visibilityState ?? null;\n  const likelyCause = diagnoseFragnoBrowserPersistenceStall({\n    visibilityState,\n    workerProbe: options.workerProbe,\n    webLocks,\n  });\n\n  return {\n    databaseName: options.databaseName,\n    elapsedMs: options.elapsedMs,\n    timerDriftMs: options.timerDriftMs,\n    collectedAt: new Date().toISOString(),\n    likelyCause,\n    workerProbe: options.workerProbe,\n    runtime: {\n      href: browserLocation?.href ?? null,\n      origin: browserLocation?.origin ?? null,\n      userAgent: browserNavigator?.userAgent ?? null,\n      visibilityState,\n      readyState: browserDocument?.readyState ?? null,\n      documentHasFocus: browserDocument?.hasFocus() ?? null,\n      isSecureContext: browserGlobal.isSecureContext ?? false,\n      crossOriginIsolated: browserGlobal.crossOriginIsolated ?? false,\n      online: browserNavigator?.onLine ?? null,\n      hardwareConcurrency: browserNavigator?.hardwareConcurrency ?? null,\n      workerAvailable: typeof browserGlobal.Worker === \"function\",\n      broadcastChannelAvailable: typeof browserGlobal.BroadcastChannel === \"function\",\n      webLocksAvailable: typeof browserNavigator?.locks?.query === \"function\",\n      opfsAvailable: typeof browserNavigator?.storage?.getDirectory === \"function\",\n      fileSystemFileHandleGlobalAvailable: typeof browserGlobal.FileSystemFileHandle === \"function\",\n    },\n    webLocks,\n    storageEstimate,\n    persistedStorage,\n    opfsEntries,\n  };\n}\n\nfunction diagnoseFragnoBrowserPersistenceStall(options: {\n  visibilityState: DocumentVisibilityState | null;\n  workerProbe: FragnoBrowserWorkerProbeSnapshot;\n  webLocks: Awaited<ReturnType<typeof inspectFragnoBrowserLocks>>;\n}): string {\n  const hasRelevantLocks =\n    options.webLocks.status === \"available\" &&\n    (options.webLocks.value.relevantHeld.length > 0 ||\n      options.webLocks.value.relevantPending.length > 0);\n\n  if (options.workerProbe.status === \"starting\" && !hasRelevantLocks) {\n    if (options.visibilityState === \"hidden\") {\n      return \"The diagnostic worker has not responded and OPFS has created no locks. The document is hidden, which may be contributing to worker scheduling delays in this Electron runtime; the SQLite persistence worker may also be waiting to execute.\";\n    }\n    return \"The diagnostic worker has not responded and OPFS has created no locks. The SQLite persistence worker may also be waiting to execute.\";\n  }\n\n  if (options.workerProbe.status === \"failed\") {\n    return `Diagnostic worker startup failed: ${options.workerProbe.error}`;\n  }\n\n  if (options.webLocks.status === \"available\") {\n    return options.webLocks.value.interpretation;\n  }\n\n  return \"The upstream persistence API has not completed and exposes no finer-grained initialization progress.\";\n}\n\nasync function inspectFragnoBrowserLocks(\n  databaseName: string,\n): Promise<FragnoBrowserDiagnostic<FragnoBrowserLockSnapshot>> {\n  try {\n    const lockManager = globalThis.navigator?.locks;\n    if (!lockManager?.query) {\n      return { status: \"unavailable\", reason: \"Web Locks query is unavailable.\" };\n    }\n\n    const snapshot = (await lockManager.query()) as {\n      held: Array<{ name: string; mode: string; clientId?: string }>;\n      pending: Array<{ name: string; mode: string; clientId?: string }>;\n    };\n    const held = snapshot.held.map(materializeFragnoBrowserLock);\n    const pending = snapshot.pending.map(materializeFragnoBrowserLock);\n    const databaseLockName = `ahp:/${databaseName}`;\n    const isRelevantLock = (lock: FragnoBrowserLock) =>\n      lock.name === databaseLockName || lock.name.startsWith(\".ahp-\");\n    const relevantHeld = held.filter(isRelevantLock);\n    const relevantPending = pending.filter(isRelevantLock);\n\n    let interpretation = \"OPFS did not expose an active initialization lock.\";\n    if (relevantPending.some((lock) => lock.name === databaseLockName)) {\n      interpretation = \"OPFS is waiting to acquire the database access-handle lock.\";\n    } else if (relevantHeld.some((lock) => lock.name === databaseLockName)) {\n      interpretation =\n        \"OPFS acquired the database access-handle lock but did not finish opening SQLite.\";\n    } else if (relevantHeld.some((lock) => lock.name.startsWith(\".ahp-\"))) {\n      interpretation =\n        \"OPFS created its temporary VFS lock but has not requested the database access-handle lock.\";\n    }\n\n    return {\n      status: \"available\",\n      value: { held, pending, relevantHeld, relevantPending, interpretation },\n    };\n  } catch (error) {\n    return { status: \"failed\", error: describeFragnoBrowserDiagnosticError(error) };\n  }\n}\n\nasync function inspectFragnoBrowserStorageEstimate(): Promise<\n  FragnoBrowserDiagnostic<FragnoBrowserStorageEstimate>\n> {\n  try {\n    const storage = globalThis.navigator?.storage;\n    if (!storage?.estimate) {\n      return { status: \"unavailable\", reason: \"Storage estimate is unavailable.\" };\n    }\n\n    const estimate = (await storage.estimate()) as StorageEstimate & {\n      usageDetails?: Record<string, number>;\n    };\n    return {\n      status: \"available\",\n      value: {\n        quota: estimate.quota ?? null,\n        usage: estimate.usage ?? null,\n        usageDetails: estimate.usageDetails ? { ...estimate.usageDetails } : null,\n      },\n    };\n  } catch (error) {\n    return { status: \"failed\", error: describeFragnoBrowserDiagnosticError(error) };\n  }\n}\n\nasync function inspectFragnoBrowserPersistedStorage(): Promise<FragnoBrowserDiagnostic<boolean>> {\n  try {\n    const storage = globalThis.navigator?.storage;\n    if (!storage?.persisted) {\n      return { status: \"unavailable\", reason: \"Persisted storage status is unavailable.\" };\n    }\n\n    return { status: \"available\", value: await storage.persisted() };\n  } catch (error) {\n    return { status: \"failed\", error: describeFragnoBrowserDiagnosticError(error) };\n  }\n}\n\nasync function inspectFragnoBrowserOPFSEntries(\n  databaseName: string,\n): Promise<FragnoBrowserDiagnostic<FragnoOPFSEntry[]>> {\n  try {\n    const browserNavigator = (globalThis as FragnoBrowserDiagnosticsGlobal).navigator;\n    const getDirectory = browserNavigator?.storage?.getDirectory;\n    if (!getDirectory) {\n      return { status: \"unavailable\", reason: \"OPFS directory inspection is unavailable.\" };\n    }\n\n    const root = await getDirectory.call(browserNavigator.storage);\n    const entries: FragnoOPFSEntry[] = [];\n    for await (const entry of iterateFragnoFileSystemDirectory(root)) {\n      if (!entry.name.startsWith(\".ahp-\") && !entry.name.startsWith(databaseName)) {\n        continue;\n      }\n\n      if (entry.kind === \"file\") {\n        // Reading file metadata can contend with the sync access handles whose startup we are\n        // diagnosing. Directory names reveal the relevant OPFS state without perturbing it.\n        entries.push({ kind: \"file\", name: entry.name });\n        continue;\n      }\n\n      try {\n        const children = [];\n        for await (const child of iterateFragnoFileSystemDirectory(\n          entry as FileSystemDirectoryHandle,\n        )) {\n          children.push({ name: child.name, kind: child.kind });\n        }\n        entries.push({\n          kind: \"directory\",\n          name: entry.name,\n          entries: children,\n          inspectionError: null,\n        });\n      } catch (error) {\n        entries.push({\n          kind: \"directory\",\n          name: entry.name,\n          entries: [],\n          inspectionError: describeFragnoBrowserDiagnosticError(error),\n        });\n      }\n    }\n\n    return { status: \"available\", value: entries };\n  } catch (error) {\n    return { status: \"failed\", error: describeFragnoBrowserDiagnosticError(error) };\n  }\n}\n\nfunction iterateFragnoFileSystemDirectory(\n  directory: FileSystemDirectoryHandle,\n): AsyncIterable<FileSystemHandle> {\n  return (\n    directory as FileSystemDirectoryHandle & {\n      values(): AsyncIterable<FileSystemHandle>;\n    }\n  ).values();\n}\n\nfunction materializeFragnoBrowserLock(lock: {\n  name: string;\n  mode: string;\n  clientId?: string;\n}): FragnoBrowserLock {\n  return { name: lock.name, mode: lock.mode, clientId: lock.clientId ?? null };\n}\n\nfunction describeFragnoBrowserDiagnosticError(error: unknown): string {\n  return error instanceof Error ? `${error.name}: ${error.message}` : String(error);\n}\n"],"mappings":"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"}

package/dist/coordinator/fragno-collection-registry.js

@@ -0,0 +1,85 @@
+import { fragnoOutboxTargetKey } from "./fragno-outbox-synchronizer.js";
+import { FragnoTableCollection } from "./fragno-table-collection.js";
+import { resolveDatabaseNamespace } from "@fragno-dev/db/database-namespace";
+//#region src/coordinator/fragno-collection-registry.ts
+/** Owns the table collections registered against one Fragno outbox coordinator. */
+var FragnoCollectionRegistry = class {
+	#schemas;
+	#persistence;
+	#schemaVersion;
+	#outbox;
+	#registrations = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.#schemas = validateSchemas(options.schemas);
+		this.#persistence = options.persistence;
+		this.#schemaVersion = options.schemaVersion;
+		this.#outbox = options.outbox;
+	}
+	registerCollection(schema, tableName, coordinatorState, collectionOptions = {}) {
+		if (!this.#schemas.has(schema)) throw new Error(`Schema ${schema.name} was not supplied to this Fragno coordinator.`);
+		const table = schema.tables[tableName];
+		if (!table) throw new Error(`Table ${schema.name}.${tableName} does not exist.`);
+		const namespace = resolveDatabaseNamespace(schema.name) ?? "";
+		const targetKey = fragnoOutboxTargetKey(namespace, tableName);
+		const existing = this.#registrations.get(targetKey);
+		if (existing) return existing.collection;
+		if (coordinatorState !== "idle") throw new Error(`Fragno collection ${schema.name}.${tableName} cannot be registered while the coordinator is ${coordinatorState}.`);
+		const tableCollection = new FragnoTableCollection({
+			id: fragnoTableCollectionId(namespace, tableName),
+			idColumnName: table.getIdColumn().name,
+			persistence: this.#persistence,
+			schemaVersion: this.#schemaVersion,
+			outbox: this.#outbox,
+			rowUpdateMode: collectionOptions.rowUpdateMode ?? "partial",
+			skipMissingTruncateDeletes: collectionOptions.skipMissingTruncateDeletes ?? false,
+			target: {
+				key: targetKey,
+				namespace,
+				schema,
+				tableName
+			}
+		});
+		this.#registrations.set(targetKey, tableCollection);
+		return tableCollection.collection;
+	}
+	registeredTargets() {
+		return [...this.#registrations.keys()].sort();
+	}
+	preload() {
+		if (this.#registrations.size === 0) return Promise.reject(/* @__PURE__ */ new Error("At least one Fragno collection must be registered before preload()."));
+		return Promise.all([...this.#registrations.values()].map(({ collection }) => collection.preload())).then(() => {});
+	}
+	async cleanup() {
+		await Promise.all([...this.#registrations.values()].map(({ collection }) => collection.cleanup()));
+	}
+};
+function validateSchemas(schemas) {
+	if (schemas.length === 0) throw new Error("createFragnoOutboxCoordinator requires at least one schema.");
+	const suppliedSchemas = /* @__PURE__ */ new Set();
+	const schemaNames = /* @__PURE__ */ new Set();
+	const physicalTargets = /* @__PURE__ */ new Map();
+	for (const schema of schemas) {
+		if (suppliedSchemas.has(schema)) throw new Error(`Duplicate Fragno schema ${schema.name}.`);
+		if (schemaNames.has(schema.name)) throw new Error(`Duplicate Fragno schema name ${schema.name}.`);
+		suppliedSchemas.add(schema);
+		schemaNames.add(schema.name);
+		const namespace = resolveDatabaseNamespace(schema.name) ?? "";
+		for (const tableName of Object.keys(schema.tables)) {
+			const targetKey = fragnoOutboxTargetKey(namespace, tableName);
+			const existingTarget = physicalTargets.get(targetKey);
+			if (existingTarget) throw new Error(`Fragno schemas ${existingTarget.schemaName} and ${schema.name} both target ${namespace}.${tableName}.`);
+			physicalTargets.set(targetKey, {
+				schemaName: schema.name,
+				tableName
+			});
+		}
+	}
+	return suppliedSchemas;
+}
+function fragnoTableCollectionId(namespace, tableName) {
+	return `fragno.outbox.table.v1:${fragnoOutboxTargetKey(namespace, tableName)}`;
+}
+//#endregion
+export { FragnoCollectionRegistry };
+
+//# sourceMappingURL=fragno-collection-registry.js.map

package/dist/coordinator/fragno-collection-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragno-collection-registry.js","names":["#schemas","#persistence","#schemaVersion","#outbox","#registrations"],"sources":["../../src/coordinator/fragno-collection-registry.ts"],"sourcesContent":["import { resolveDatabaseNamespace } from \"@fragno-dev/db/database-namespace\";\nimport type { AnySchema } from \"@fragno-dev/db/schema\";\n\nimport type { Collection } from \"@tanstack/db\";\nimport type { PersistedCollectionPersistence } from \"@tanstack/db-sqlite-persistence-core\";\n\nimport type {\n  FragnoCollectionOptions,\n  FragnoCollectionRow,\n  FragnoOutboxCoordinatorState,\n} from \"../coordinator\";\nimport { fragnoOutboxTargetKey, type FragnoOutboxSynchronizer } from \"./fragno-outbox-synchronizer\";\nimport { FragnoTableCollection } from \"./fragno-table-collection\";\n\n/** Owns the table collections registered against one Fragno outbox coordinator. */\nexport class FragnoCollectionRegistry<TSchemas extends readonly AnySchema[]> {\n  readonly #schemas: Set<AnySchema>;\n  readonly #persistence: PersistedCollectionPersistence;\n  readonly #schemaVersion: number;\n  readonly #outbox: FragnoOutboxSynchronizer;\n  readonly #registrations = new Map<string, FragnoTableCollection>();\n\n  constructor(options: {\n    schemas: TSchemas;\n    persistence: PersistedCollectionPersistence;\n    schemaVersion: number;\n    outbox: FragnoOutboxSynchronizer;\n  }) {\n    this.#schemas = validateSchemas(options.schemas);\n    this.#persistence = options.persistence;\n    this.#schemaVersion = options.schemaVersion;\n    this.#outbox = options.outbox;\n  }\n\n  registerCollection<\n    TSchema extends TSchemas[number],\n    TTableName extends keyof TSchema[\"tables\"] & string,\n  >(\n    schema: TSchema,\n    tableName: TTableName,\n    coordinatorState: FragnoOutboxCoordinatorState,\n    collectionOptions: FragnoCollectionOptions = {},\n  ): Collection<FragnoCollectionRow<TSchema[\"tables\"][TTableName]>, string> {\n    if (!this.#schemas.has(schema)) {\n      throw new Error(`Schema ${schema.name} was not supplied to this Fragno coordinator.`);\n    }\n\n    const table = schema.tables[tableName];\n    if (!table) {\n      throw new Error(`Table ${schema.name}.${tableName} does not exist.`);\n    }\n\n    const namespace = resolveDatabaseNamespace(schema.name) ?? \"\";\n    const targetKey = fragnoOutboxTargetKey(namespace, tableName);\n    const existing = this.#registrations.get(targetKey);\n    if (existing) {\n      return existing.collection as unknown as Collection<\n        FragnoCollectionRow<TSchema[\"tables\"][TTableName]>,\n        string\n      >;\n    }\n\n    if (coordinatorState !== \"idle\") {\n      throw new Error(\n        `Fragno collection ${schema.name}.${tableName} cannot be registered while the coordinator is ${coordinatorState}.`,\n      );\n    }\n\n    const tableCollection = new FragnoTableCollection({\n      id: fragnoTableCollectionId(namespace, tableName),\n      idColumnName: table.getIdColumn().name,\n      persistence: this.#persistence,\n      schemaVersion: this.#schemaVersion,\n      outbox: this.#outbox,\n      rowUpdateMode: collectionOptions.rowUpdateMode ?? \"partial\",\n      skipMissingTruncateDeletes: collectionOptions.skipMissingTruncateDeletes ?? false,\n      target: {\n        key: targetKey,\n        namespace,\n        schema,\n        tableName,\n      },\n    });\n    this.#registrations.set(targetKey, tableCollection);\n\n    return tableCollection.collection as unknown as Collection<\n      FragnoCollectionRow<TSchema[\"tables\"][TTableName]>,\n      string\n    >;\n  }\n\n  registeredTargets(): readonly string[] {\n    return [...this.#registrations.keys()].sort();\n  }\n\n  preload(): Promise<void> {\n    if (this.#registrations.size === 0) {\n      return Promise.reject(\n        new Error(\"At least one Fragno collection must be registered before preload().\"),\n      );\n    }\n\n    return Promise.all(\n      [...this.#registrations.values()].map(({ collection }) => collection.preload()),\n    ).then(() => {});\n  }\n\n  async cleanup(): Promise<void> {\n    await Promise.all(\n      [...this.#registrations.values()].map(({ collection }) => collection.cleanup()),\n    );\n  }\n}\n\nfunction validateSchemas(schemas: readonly AnySchema[]): Set<AnySchema> {\n  if (schemas.length === 0) {\n    throw new Error(\"createFragnoOutboxCoordinator requires at least one schema.\");\n  }\n\n  const suppliedSchemas = new Set<AnySchema>();\n  const schemaNames = new Set<string>();\n  const physicalTargets = new Map<string, { schemaName: string; tableName: string }>();\n\n  for (const schema of schemas) {\n    if (suppliedSchemas.has(schema)) {\n      throw new Error(`Duplicate Fragno schema ${schema.name}.`);\n    }\n    if (schemaNames.has(schema.name)) {\n      throw new Error(`Duplicate Fragno schema name ${schema.name}.`);\n    }\n    suppliedSchemas.add(schema);\n    schemaNames.add(schema.name);\n\n    const namespace = resolveDatabaseNamespace(schema.name) ?? \"\";\n    for (const tableName of Object.keys(schema.tables)) {\n      const targetKey = fragnoOutboxTargetKey(namespace, tableName);\n      const existingTarget = physicalTargets.get(targetKey);\n      if (existingTarget) {\n        throw new Error(\n          `Fragno schemas ${existingTarget.schemaName} and ${schema.name} both target ${namespace}.${tableName}.`,\n        );\n      }\n      physicalTargets.set(targetKey, { schemaName: schema.name, tableName });\n    }\n  }\n\n  return suppliedSchemas;\n}\n\nfunction fragnoTableCollectionId(namespace: string, tableName: string): string {\n  return `fragno.outbox.table.v1:${fragnoOutboxTargetKey(namespace, tableName)}`;\n}\n"],"mappings":"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"}

package/dist/coordinator/fragno-internal-collection.d.ts

@@ -0,0 +1,40 @@
+import { FragnoOutboxCheckpoint } from "../checkpoint.js";
+import { Collection, SyncAppliedReceipt } from "@tanstack/db";
+import { PersistedCollectionPersistence } from "@tanstack/db-sqlite-persistence-core";
+//#region src/coordinator/fragno-internal-collection.d.ts
+declare const FRAGNO_INTERNAL_STATUS_ID: "coordinator";
+type FragnoOutboxCoordinatorState = "opening" | "idle" | "registering" | "catching-up" | "replaying" | "live" | "retrying" | "rotating" | "failed" | "disposed";
+type FragnoOutboxCoordinatorError = {
+  name: string;
+  message: string;
+};
+type FragnoInternalRow = {
+  id: typeof FRAGNO_INTERNAL_STATUS_ID;
+  state: FragnoOutboxCoordinatorState;
+  checkpoint: FragnoOutboxCheckpoint | null;
+  error: FragnoOutboxCoordinatorError | null;
+};
+/** Persisted and user-queryable coordinator state for one Fragno outbox database. */
+declare class FragnoInternalCollection {
+  #private;
+  readonly collection: Collection<FragnoInternalRow, string>;
+  constructor(options: {
+    persistence: PersistedCollectionPersistence;
+    schemaVersion?: number;
+    state?: FragnoOutboxCoordinatorState;
+  });
+  preload(): Promise<void>;
+  getCheckpoint(): FragnoOutboxCheckpoint | undefined;
+  setCheckpoint(checkpoint: FragnoOutboxCheckpoint): SyncAppliedReceipt;
+  /**
+   * Settles once every earlier write in the shared persistence database is durable: a persisted
+   * commit's receipt settles with its durable write, and writes persist in order.
+   */
+  flushPersistence(): SyncAppliedReceipt;
+  clearCheckpoint(): SyncAppliedReceipt;
+  setState(state: FragnoOutboxCoordinatorState, error?: unknown): SyncAppliedReceipt;
+  cleanup(): Promise<void>;
+}
+//#endregion
+export { FRAGNO_INTERNAL_STATUS_ID, FragnoInternalCollection, FragnoInternalRow, FragnoOutboxCoordinatorError, FragnoOutboxCoordinatorState };
+//# sourceMappingURL=fragno-internal-collection.d.ts.map

package/dist/coordinator/fragno-internal-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragno-internal-collection.d.ts","names":[],"sources":["../../src/coordinator/fragno-internal-collection.ts"],"mappings":";;;;cAca;KAID;KAYA;EACV;EACA;;KAGU;EACV,WAAW;EACX,OAAO;EACP,YAAY;EACZ,OAAO;;;cAMI;;WACF,YAAY,WAAW;cAOpB;IACV,aAAa;IACb;IACA,QAAQ;;EAiDV,WAAW;EAUX,iBAAiB;EAIjB,cAAc,YAAY,yBAAyB;;;;;EAenD,oBAAoB;EAWpB,mBAAmB;EAWnB,SAAS,OAAO,8BAA8B,kBAAwB;EAStE,WAAW"}