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

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

@@ -0,0 +1,91 @@
+import { toTanStackChangeMessage } from "../protocol.js";
+import { FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY, shouldApplyOutboxCheckpoint } from "../checkpoint.js";
+import { BTreeIndex, createCollection } from "@tanstack/db";
+import { persistedCollectionOptions } from "@tanstack/db-sqlite-persistence-core";
+//#region src/coordinator/fragno-table-collection.ts
+/** One lazily registered TanStack collection backed by the shared Fragno persistence database. */
+var FragnoTableCollection = class {
+	collection;
+	constructor(options) {
+		const persistence = resolveCollectionPersistence(options.persistence, options.id, options.schemaVersion);
+		if (options.skipMissingTruncateDeletes && !persistence.adapter.scanRows) throw new Error(`Persistence for ${options.id} cannot retrieve keys required to skip missing truncate deletes.`);
+		this.collection = createCollection(persistedCollectionOptions({
+			id: options.id,
+			getKey: (row) => row[options.idColumnName],
+			persistence,
+			schemaVersion: options.schemaVersion,
+			syncMode: "eager",
+			gcTime: 0,
+			autoIndex: "eager",
+			defaultIndexType: BTreeIndex,
+			sync: {
+				rowUpdateMode: options.rowUpdateMode,
+				sync: (controls) => {
+					if (!controls.metadata?.persistence) throw new Error("Fragno table collections require TanStack persistence metadata.");
+					const syncPersistence = controls.metadata.persistence;
+					let presentKeys;
+					let preparation;
+					return options.outbox.register({
+						target: options.target,
+						...options.skipMissingTruncateDeletes ? { prepareCatchUp() {
+							preparation ??= (async () => {
+								const persistedRows = await syncPersistence.scanPersistedRows();
+								presentKeys = new Set(persistedRows.map(({ key }) => key));
+							})();
+							return preparation;
+						} } : {},
+						apply(delivery) {
+							return applyDeliveries(controls, [delivery], presentKeys, "live");
+						},
+						applyBatch(deliveries) {
+							return applyDeliveries(controls, deliveries, presentKeys, "catch-up");
+						},
+						truncate() {
+							controls.begin();
+							controls.truncate();
+							const visible = controls.commit();
+							presentKeys?.clear();
+							return visible;
+						},
+						markReady() {
+							controls.markReady();
+						}
+					});
+				}
+			}
+		}));
+	}
+};
+function applyDeliveries(controls, deliveries, presentKeys, deliveryMode) {
+	let appliedCheckpoint = controls.metadata.collection.get(FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY);
+	let nextCheckpoint;
+	const keyChanges = /* @__PURE__ */ new Map();
+	controls.begin();
+	for (const { checkpoint, changes } of deliveries) {
+		if (!shouldApplyOutboxCheckpoint(appliedCheckpoint, checkpoint)) continue;
+		for (const change of changes) {
+			if (deliveryMode === "catch-up" && change.type === "delete" && change.origin === "truncate" && presentKeys && !(keyChanges.get(change.key) ?? presentKeys.has(change.key))) continue;
+			controls.write(toTanStackChangeMessage(change));
+			if (presentKeys) keyChanges.set(change.key, change.type !== "delete");
+		}
+		appliedCheckpoint = checkpoint;
+		nextCheckpoint = checkpoint;
+	}
+	if (!nextCheckpoint) return controls.commit();
+	controls.metadata.collection.set(FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY, nextCheckpoint);
+	const visible = controls.commit();
+	if (presentKeys) for (const [key, present] of keyChanges) if (present) presentKeys.add(key);
+	else presentKeys.delete(key);
+	return visible;
+}
+function resolveCollectionPersistence(persistence, collectionId, schemaVersion) {
+	return persistence.resolvePersistenceForCollection?.({
+		collectionId,
+		mode: "sync-present",
+		schemaVersion
+	}) ?? persistence.resolvePersistenceForMode?.("sync-present") ?? persistence;
+}
+//#endregion
+export { FragnoTableCollection };
+
+//# sourceMappingURL=fragno-table-collection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fragno-table-collection.js","names":[],"sources":["../../src/coordinator/fragno-table-collection.ts"],"sourcesContent":["import {\n  BTreeIndex,\n  createCollection,\n  type Collection,\n  type SyncAppliedReceipt,\n  type SyncConfig,\n} from \"@tanstack/db\";\nimport {\n  persistedCollectionOptions,\n  type PersistedCollectionPersistence,\n} from \"@tanstack/db-sqlite-persistence-core\";\n\nimport {\n  FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY,\n  shouldApplyOutboxCheckpoint,\n  type FragnoOutboxCheckpoint,\n} from \"../checkpoint\";\nimport { toTanStackChangeMessage } from \"../protocol\";\nimport type {\n  FragnoOutboxDelivery,\n  FragnoOutboxSynchronizer,\n  FragnoOutboxTarget,\n} from \"./fragno-outbox-synchronizer\";\n\ntype FragnoTableRow = Record<string, unknown>;\ntype FragnoTableSyncControls = Parameters<SyncConfig<FragnoTableRow, string>[\"sync\"]>[0];\n\n/** One lazily registered TanStack collection backed by the shared Fragno persistence database. */\nexport class FragnoTableCollection {\n  readonly collection: Collection<FragnoTableRow, string>;\n\n  constructor(options: {\n    id: string;\n    idColumnName: string;\n    persistence: PersistedCollectionPersistence;\n    schemaVersion: number;\n    outbox: FragnoOutboxSynchronizer;\n    rowUpdateMode: \"partial\" | \"full\";\n    skipMissingTruncateDeletes: boolean;\n    target: FragnoOutboxTarget;\n  }) {\n    const persistence = resolveCollectionPersistence(\n      options.persistence,\n      options.id,\n      options.schemaVersion,\n    );\n    // TanStack scans persisted rows through `scanRows` and reports none without it, which would\n    // skip deletes of rows that exist.\n    if (options.skipMissingTruncateDeletes && !persistence.adapter.scanRows) {\n      throw new Error(\n        `Persistence for ${options.id} cannot retrieve keys required to skip missing truncate deletes.`,\n      );\n    }\n\n    this.collection = createCollection(\n      persistedCollectionOptions<FragnoTableRow, string>({\n        id: options.id,\n        getKey: (row) => row[options.idColumnName] as string,\n        persistence,\n        schemaVersion: options.schemaVersion,\n        syncMode: \"eager\",\n        gcTime: 0,\n        autoIndex: \"eager\",\n        defaultIndexType: BTreeIndex,\n        sync: {\n          rowUpdateMode: options.rowUpdateMode,\n          sync: (controls) => {\n            if (!controls.metadata?.persistence) {\n              throw new Error(\"Fragno table collections require TanStack persistence metadata.\");\n            }\n            const syncPersistence = controls.metadata.persistence;\n\n            // A new registration owns a fresh key index; rotating its transport does not.\n            let presentKeys: Set<string> | undefined;\n            let preparation: Promise<void> | undefined;\n            return options.outbox.register({\n              target: options.target,\n              ...(options.skipMissingTruncateDeletes\n                ? {\n                    prepareCatchUp() {\n                      preparation ??= (async () => {\n                        const persistedRows = await syncPersistence.scanPersistedRows();\n                        presentKeys = new Set(persistedRows.map(({ key }) => key));\n                      })();\n                      return preparation;\n                    },\n                  }\n                : {}),\n              apply(delivery) {\n                return applyDeliveries(controls, [delivery], presentKeys, \"live\");\n              },\n              applyBatch(deliveries) {\n                return applyDeliveries(controls, deliveries, presentKeys, \"catch-up\");\n              },\n              truncate() {\n                controls.begin();\n                controls.truncate();\n                const visible = controls.commit();\n                presentKeys?.clear();\n                return visible;\n              },\n              markReady() {\n                controls.markReady();\n              },\n            });\n          },\n        },\n      }),\n    );\n  }\n}\n\nfunction applyDeliveries(\n  controls: FragnoTableSyncControls,\n  deliveries: readonly FragnoOutboxDelivery[],\n  presentKeys: Set<string> | undefined,\n  deliveryMode: \"live\" | \"catch-up\",\n): SyncAppliedReceipt {\n  let appliedCheckpoint = controls.metadata!.collection.get(\n    FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY,\n  ) as FragnoOutboxCheckpoint | undefined;\n  let nextCheckpoint: FragnoOutboxCheckpoint | undefined;\n  // Stage only touched keys, not a copy of the whole index. Failed writes/commits must not\n  // advance it, while later changes in the same batch must see earlier inserts and deletes.\n  const keyChanges = new Map<string, boolean>();\n\n  controls.begin();\n  for (const { checkpoint, changes } of deliveries) {\n    if (!shouldApplyOutboxCheckpoint(appliedCheckpoint, checkpoint)) {\n      continue;\n    }\n\n    for (const change of changes) {\n      if (\n        deliveryMode === \"catch-up\" &&\n        change.type === \"delete\" &&\n        change.origin === \"truncate\" &&\n        presentKeys &&\n        !(keyChanges.get(change.key) ?? presentKeys.has(change.key))\n      ) {\n        continue;\n      }\n\n      controls.write(toTanStackChangeMessage(change));\n      if (presentKeys) {\n        keyChanges.set(change.key, change.type !== \"delete\");\n      }\n    }\n    appliedCheckpoint = checkpoint;\n    nextCheckpoint = checkpoint;\n  }\n\n  if (!nextCheckpoint) {\n    return controls.commit();\n  }\n\n  controls.metadata!.collection.set(\n    FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY,\n    nextCheckpoint,\n  );\n  const visible = controls.commit();\n  if (presentKeys) {\n    for (const [key, present] of keyChanges) {\n      if (present) {\n        presentKeys.add(key);\n      } else {\n        presentKeys.delete(key);\n      }\n    }\n  }\n  return visible;\n}\n\nfunction resolveCollectionPersistence(\n  persistence: PersistedCollectionPersistence,\n  collectionId: string,\n  schemaVersion: number,\n): PersistedCollectionPersistence {\n  return (\n    persistence.resolvePersistenceForCollection?.({\n      collectionId,\n      mode: \"sync-present\",\n      schemaVersion,\n    }) ??\n    persistence.resolvePersistenceForMode?.(\"sync-present\") ??\n    persistence\n  );\n}\n"],"mappings":";;;;;;AA4BA,IAAa,wBAAb,MAAmC;CACjC;CAEA,YAAY,SAST;EACD,MAAM,cAAc,6BAClB,QAAQ,aACR,QAAQ,IACR,QAAQ,aACV;EAGA,IAAI,QAAQ,8BAA8B,CAAC,YAAY,QAAQ,UAC7D,MAAM,IAAI,MACR,mBAAmB,QAAQ,GAAG,iEAChC;EAGF,KAAK,aAAa,iBAChB,2BAAmD;GACjD,IAAI,QAAQ;GACZ,SAAS,QAAQ,IAAI,QAAQ;GAC7B;GACA,eAAe,QAAQ;GACvB,UAAU;GACV,QAAQ;GACR,WAAW;GACX,kBAAkB;GAClB,MAAM;IACJ,eAAe,QAAQ;IACvB,OAAO,aAAa;KAClB,IAAI,CAAC,SAAS,UAAU,aACtB,MAAM,IAAI,MAAM,iEAAiE;KAEnF,MAAM,kBAAkB,SAAS,SAAS;KAG1C,IAAI;KACJ,IAAI;KACJ,OAAO,QAAQ,OAAO,SAAS;MAC7B,QAAQ,QAAQ;MAChB,GAAI,QAAQ,6BACR,EACE,iBAAiB;OACf,iBAAiB,YAAY;QAC3B,MAAM,gBAAgB,MAAM,gBAAgB,kBAAkB;QAC9D,cAAc,IAAI,IAAI,cAAc,KAAK,EAAE,UAAU,GAAG,CAAC;OAC3D,EAAA,CAAG;OACH,OAAO;MACT,EACF,IACA,CAAC;MACL,MAAM,UAAU;OACd,OAAO,gBAAgB,UAAU,CAAC,QAAQ,GAAG,aAAa,MAAM;MAClE;MACA,WAAW,YAAY;OACrB,OAAO,gBAAgB,UAAU,YAAY,aAAa,UAAU;MACtE;MACA,WAAW;OACT,SAAS,MAAM;OACf,SAAS,SAAS;OAClB,MAAM,UAAU,SAAS,OAAO;OAChC,aAAa,MAAM;OACnB,OAAO;MACT;MACA,YAAY;OACV,SAAS,UAAU;MACrB;KACF,CAAC;IACH;GACF;EACF,CAAC,CACH;CACF;AACF;AAEA,SAAS,gBACP,UACA,YACA,aACA,cACoB;CACpB,IAAI,oBAAoB,SAAS,SAAU,WAAW,IACpD,gDACF;CACA,IAAI;CAGJ,MAAM,6BAAa,IAAI,IAAqB;CAE5C,SAAS,MAAM;CACf,KAAK,MAAM,EAAE,YAAY,aAAa,YAAY;EAChD,IAAI,CAAC,4BAA4B,mBAAmB,UAAU,GAC5D;EAGF,KAAK,MAAM,UAAU,SAAS;GAC5B,IACE,iBAAiB,cACjB,OAAO,SAAS,YAChB,OAAO,WAAW,cAClB,eACA,EAAE,WAAW,IAAI,OAAO,GAAG,KAAK,YAAY,IAAI,OAAO,GAAG,IAE1D;GAGF,SAAS,MAAM,wBAAwB,MAAM,CAAC;GAC9C,IAAI,aACF,WAAW,IAAI,OAAO,KAAK,OAAO,SAAS,QAAQ;EAEvD;EACA,oBAAoB;EACpB,iBAAiB;CACnB;CAEA,IAAI,CAAC,gBACH,OAAO,SAAS,OAAO;CAGzB,SAAS,SAAU,WAAW,IAC5B,kDACA,cACF;CACA,MAAM,UAAU,SAAS,OAAO;CAChC,IAAI,aACF,KAAK,MAAM,CAAC,KAAK,YAAY,YAC3B,IAAI,SACF,YAAY,IAAI,GAAG;MAEnB,YAAY,OAAO,GAAG;CAI5B,OAAO;AACT;AAEA,SAAS,6BACP,aACA,cACA,eACgC;CAChC,OACE,YAAY,kCAAkC;EAC5C;EACA,MAAM;EACN;CACF,CAAC,KACD,YAAY,4BAA4B,cAAc,KACtD;AAEJ"}

package/dist/coordinator.d.ts

@@ -0,0 +1,113 @@
+import { FragnoBrowserPersistenceDiagnostics } from "./coordinator/fragno-browser-persistence-startup.js";
+import { FragnoOutboxCheckpoint } from "./checkpoint.js";
+import { FragnoInternalCollection, FragnoInternalRow, FragnoOutboxCoordinatorError, FragnoOutboxCoordinatorState } from "./coordinator/fragno-internal-collection.js";
+import { FragnoInternalDescription } from "./coordinator/fragno-internal-fetcher.js";
+import "./coordinator.js";
+import { Collection } from "@tanstack/db";
+import { PersistedCollectionPersistence } from "@tanstack/db-sqlite-persistence-core";
+import { TableToColumnValues } from "@fragno-dev/db/query";
+import { AnySchema, AnyTable, FragnoId, FragnoReference } from "@fragno-dev/db/schema";
+//#region src/coordinator.d.ts
+/**
+ * Problem statement
+ * -----------------
+ * One Fragno database produces one globally ordered outbox containing mutations for every schema
+ * and table stored in that database. The browser should mirror that outbox into one local database,
+ * not create an independent transport, checkpoint, or persistence database for every collection.
+ *
+ * `createFragnoOutboxCoordinator` therefore receives only:
+ *
+ * - the mounted Fragment base URL;
+ * - the Fetch implementation used to call it;
+ * - every Fragno schema represented by that outbox.
+ *
+ * From those inputs it owns the complete local database: source identity, persistence, one exact
+ * outbox checkpoint, one catch-up loop, one live stream, and every table collection registered
+ * before preload. Callers register typed collections but cannot configure synchronization
+ * independently.
+ *
+ * Data flow
+ * ---------
+ *
+ * createFragnoOutboxCoordinator({ baseUrl, fetch, schemas })
+ *   -> derive the Fragno internal outbox URL from baseUrl
+ *   -> resolve the physical database adapter identity
+ *   -> open one local persistence database for that base URL + adapter identity
+ *   -> coordinator.collection(schema, table) lazily registers each requested table collection
+ *   -> coordinator.preload() closes registration and preloads every registered collection
+ *   -> each collection's sync callback subscribes to the shared outbox synchronizer
+ *   -> read the database's one exact persisted outbox checkpoint
+ *   -> verify checkpoint UOW identity and stream strictly after its versionstamp
+ *   -> validate and decode each outbox entry once
+ *   -> route every operation to its schema/table collection
+ *   -> commit all affected collections before advancing the database checkpoint
+ *   -> mark every collection ready together
+ *   -> continue live delivery on the same response after its caught-up marker
+ *   -> TanStack live queries update the UI
+ *
+ * Invariants
+ * ----------
+ *
+ * - one outbox maps to exactly one local database;
+ * - every requested table collection is registered before catch-up starts;
+ * - one exact checkpoint describes the complete local database, not an individual collection;
+ * - an entry advances that checkpoint only after every affected collection has committed;
+ * - entries without relevant operations still advance the checkpoint;
+ * - reloads and stream rotations verify checkpoint identity without replaying old entries;
+ * - changing adapter identity discards the previous local database materialization;
+ * - persisted rows alone never make collections ready before network catch-up finishes;
+ * - cleanup stops the shared request, stream, persistence, and every generated collection.
+ */
+type MaterializedColumnValue<TValue> = TValue extends FragnoId | FragnoReference ? string : TValue;
+type VisibleTableValues<TTable extends AnyTable> = TableToColumnValues<TTable>;
+type FragnoCollectionRow<TTable extends AnyTable> = { [TColumnName in keyof VisibleTableValues<TTable> as [VisibleTableValues<TTable>[TColumnName]] extends [null] ? never : TColumnName]: MaterializedColumnValue<VisibleTableValues<TTable>[TColumnName]>; };
+declare const FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION = 2;
+declare function fetchFragnoOutboxDescription(options: {
+  baseUrl: string | URL;
+  fetch: typeof globalThis.fetch;
+  signal?: AbortSignal;
+}): Promise<FragnoInternalDescription>;
+type FragnoOutboxCatchUpProgress = {
+  completedPages: number;
+  totalPages: number;
+  percent: number;
+};
+type FragnoOutboxPersistenceResource = {
+  persistence: PersistedCollectionPersistence;
+  cleanup(): Promise<void>;
+};
+type FragnoOutboxCoordinatorDependencies = {
+  openPersistence(options: {
+    databaseName: string;
+  }): Promise<FragnoOutboxPersistenceResource>;
+};
+type FragnoCollectionOptions = {
+  /** Use `full` only for tables that never receive updates; Fragno update entries contain patches. */
+  rowUpdateMode?: "partial" | "full";
+  /** Scans persisted rows once per sync registration to skip missing catch-up truncate deletes. */
+  skipMissingTruncateDeletes?: boolean;
+};
+type FragnoOutboxCoordinator<TSchemas extends readonly AnySchema[]> = {
+  /** Persisted coordinator metadata and user-queryable lifecycle status. */
+  readonly internal: FragnoInternalCollection;
+  /** Current synchronization lifecycle state. */
+  readonly state: FragnoOutboxCoordinatorState;
+  collection<TSchema extends TSchemas[number], TTableName extends keyof TSchema["tables"] & string>(schema: TSchema, table: TTableName, options?: FragnoCollectionOptions): Collection<FragnoCollectionRow<TSchema["tables"][TTableName]>, string>;
+  /** Preloads every generated collection and resolves after shared initial catch-up. */
+  preload(): Promise<void>;
+  /** Waits until every accepted local persistence write is durable. */
+  flushPersistence(): Promise<void>;
+  /** Stops synchronization and closes every collection and local database resource. */
+  cleanup(): Promise<void>;
+};
+declare function createFragnoOutboxCoordinator<const TSchemas extends readonly AnySchema[]>(options: {
+  baseUrl: string | URL;
+  fetch: typeof globalThis.fetch;
+  schemas: TSchemas;
+  onCatchUpProgress?(progress: FragnoOutboxCatchUpProgress): void;
+  /** Receives recurring browser persistence diagnostics while startup remains stalled. */
+  onBrowserPersistenceDiagnostic?(diagnostics: FragnoBrowserPersistenceDiagnostics): void;
+}, dependencies?: FragnoOutboxCoordinatorDependencies): Promise<FragnoOutboxCoordinator<TSchemas>>;
+//#endregion
+export { FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION, type FragnoBrowserPersistenceDiagnostics, FragnoCollectionOptions, FragnoCollectionRow, FragnoInternalCollection, type FragnoInternalDescription, type FragnoInternalRow, FragnoOutboxCatchUpProgress, type FragnoOutboxCheckpoint, FragnoOutboxCoordinator, FragnoOutboxCoordinatorDependencies, type FragnoOutboxCoordinatorError, type FragnoOutboxCoordinatorState, createFragnoOutboxCoordinator, fetchFragnoOutboxDescription };
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","names":[],"sources":["../src/coordinator.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAwEK,wBAAwB,UAAU,eAAe,WAAW,2BAA2B;KAEvF,mBAAmB,eAAe,YAAY,oBAAoB;KAE3D,oBAAoB,eAAe,eAC5C,qBAAqB,mBAAmB,YACvC,mBAAmB,QAAQ,uCAGzB,cAAc,wBAAwB,mBAAmB,QAAQ;cAc1D;iBAMS,6BAA6B;EACjD,kBAAkB;EAClB,cAAc,WAAW;EACzB,SAAS;IACV,QADU;KAKC;EACV;EACA;EACA;;KAGG;EACH,aAAa;EACb,WAAW;;KAGD;EACV,gBAAgB;IAAW;MAAyB,QAAQ;;KAGlD;;EAEV;;EAEA;;KAGU,wBAAwB,0BAA0B;;WAEnD,UAAU;;WAGV,OAAO;EAEhB,WAAW,gBAAgB,kBAAkB,yBAAyB,4BACpE,QAAQ,SACR,OAAO,YACP,UAAU,0BACT,WAAW,oBAAoB,kBAAkB;;EAGpD,WAAW;;EAGX,oBAAoB;;EAGpB,WAAW;;iBAGS,oCAAoC,0BAA0B,aAClF;EACE,kBAAkB;EAClB,cAAc,WAAW;EACzB,SAAS;EACT,mBAAmB,UAAU;;EAE7B,gCAAgC,aAAa;GAE/C,eAAc,sCAGb,QAAQ,wBAAwB"}

package/dist/coordinator.js

@@ -0,0 +1,231 @@
+import { openFragnoBrowserPersistenceWithDiagnostics } from "./coordinator/fragno-browser-persistence-startup.js";
+import { FragnoOutboxTransportError } from "./outbox-transport-error.js";
+import { FragnoOutboxSynchronizer } from "./coordinator/fragno-outbox-synchronizer.js";
+import { FragnoCollectionRegistry } from "./coordinator/fragno-collection-registry.js";
+import { FragnoInternalCollection } from "./coordinator/fragno-internal-collection.js";
+import { FragnoInternalFetcher } from "./coordinator/fragno-internal-fetcher.js";
+import { orderFragnoPersistenceWrites } from "./coordinator/fragno-ordered-persistence.js";
+import { FRAGNO_OUTBOX_PAGE_SIZE } from "@fragno-dev/db/outbox";
+//#region src/coordinator.ts
+const FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION = 2;
+const FRAGNO_OUTBOX_STARTUP_TIMEOUT_MS = 5e3;
+async function fetchFragnoOutboxDescription(options) {
+	return await new FragnoInternalFetcher(options).describe({ signal: options.signal });
+}
+async function createFragnoOutboxCoordinator(options, dependencies = { openPersistence: openBrowserFragnoOutboxPersistence }) {
+	let state = "opening";
+	const internalFetcher = new FragnoInternalFetcher({
+		baseUrl: options.baseUrl,
+		fetch: options.fetch
+	});
+	const { adapterIdentity } = await internalFetcher.describe();
+	const databaseName = `fragno-v3-${(await sha256Hex(`${internalFetcher.baseUrl}\0${adapterIdentity}\0version:2`)).slice(0, 32)}.sqlite`;
+	const persistenceResource = await openFragnoBrowserPersistenceWithDiagnostics({
+		databaseName,
+		onDiagnostic: (diagnostics) => options.onBrowserPersistenceDiagnostic?.(diagnostics),
+		openPersistence: () => dependencies.openPersistence({ databaseName })
+	});
+	const persistence = orderFragnoPersistenceWrites(persistenceResource.persistence);
+	let completedCatchUpPages = 0;
+	let totalCatchUpPages = 1;
+	let internalCollection;
+	let outboxSynchronizer;
+	let collectionRegistry;
+	try {
+		internalCollection = new FragnoInternalCollection({
+			persistence,
+			schemaVersion: 2,
+			state
+		});
+		await waitForFragnoOutboxStartupStage(internalCollection.preload(), "preloading coordinator metadata");
+		outboxSynchronizer = new FragnoOutboxSynchronizer({
+			fetcher: internalFetcher,
+			adapterIdentity,
+			checkpointStore: internalCollection,
+			onCatchUpPage() {
+				completedCatchUpPages += 1;
+				options.onCatchUpProgress?.({
+					completedPages: completedCatchUpPages,
+					totalPages: totalCatchUpPages,
+					percent: totalCatchUpPages === 0 ? 100 : Math.min(100, Math.round(completedCatchUpPages / totalCatchUpPages * 100))
+				});
+			}
+		});
+		collectionRegistry = new FragnoCollectionRegistry({
+			schemas: options.schemas,
+			persistence,
+			schemaVersion: 2,
+			outbox: outboxSynchronizer
+		});
+	} catch (error) {
+		outboxSynchronizer?.dispose();
+		await internalCollection?.cleanup().catch(() => {});
+		await persistenceResource.cleanup().catch(() => {});
+		throw error;
+	}
+	if (!internalCollection || !outboxSynchronizer || !collectionRegistry) {
+		await persistenceResource.cleanup();
+		throw new Error("Fragno outbox coordinator initialization did not complete.");
+	}
+	const initializedInternalCollection = internalCollection;
+	const initializedOutboxSynchronizer = outboxSynchronizer;
+	const initializedCollectionRegistry = collectionRegistry;
+	let preloadPromise;
+	let streamPromise;
+	let cleanupPromise;
+	const transitionTo = (nextState, error = null) => {
+		state = nextState;
+		initializedInternalCollection.setState(nextState, error);
+	};
+	const transitionToFailed = (error) => {
+		if (state !== "disposed") transitionTo("failed", error);
+	};
+	transitionTo("idle");
+	const flushPersistence = async () => {
+		await initializedInternalCollection.flushPersistence();
+	};
+	const isDisposed = () => state === "disposed";
+	const firstCatchUp = Promise.withResolvers();
+	firstCatchUp.promise.catch(() => {});
+	const startStreaming = () => {
+		streamPromise ??= (async () => {
+			let retryAttempt = 0;
+			while (!isDisposed()) try {
+				await initializedOutboxSynchronizer.streamSession({
+					onStarted(targetVersionstamp) {
+						completedCatchUpPages = 0;
+						totalCatchUpPages = catchUpPageCount(initializedInternalCollection.getCheckpoint()?.versionstamp, targetVersionstamp);
+					},
+					onCaughtUp() {
+						retryAttempt = 0;
+						transitionTo("live");
+						firstCatchUp.resolve();
+					}
+				});
+				if (!isDisposed()) {
+					transitionTo("rotating");
+					transitionTo("replaying");
+				}
+			} catch (error) {
+				if (isDisposed()) return;
+				if (!(error instanceof FragnoOutboxTransportError)) {
+					firstCatchUp.reject(error);
+					transitionToFailed(error);
+					return;
+				}
+				transitionTo("retrying", error);
+				retryAttempt += 1;
+				await waitForRetry(retryAttempt);
+				if (isDisposed()) return;
+				transitionTo("replaying");
+			}
+		})();
+		streamPromise.catch((error) => {
+			firstCatchUp.reject(error);
+			transitionToFailed(error);
+		});
+	};
+	return {
+		internal: initializedInternalCollection,
+		get state() {
+			return state;
+		},
+		collection(schema, tableName, collectionOptions) {
+			return initializedCollectionRegistry.registerCollection(schema, tableName, state, collectionOptions);
+		},
+		preload() {
+			preloadPromise ??= (async () => {
+				if (state !== "idle") throw new Error(`Cannot preload Fragno collections while the coordinator is ${state}.`);
+				try {
+					transitionTo("registering");
+					const collectionsReady = initializedCollectionRegistry.preload();
+					const collectionsRegistered = initializedOutboxSynchronizer.waitUntilRegistered(initializedCollectionRegistry.registeredTargets());
+					await waitForFragnoOutboxStartupStage(Promise.race([collectionsRegistered, collectionsReady.then(() => {
+						throw new Error("Fragno collections became ready before outbox synchronization registration completed.");
+					})]), "registering synchronized collections");
+					transitionTo("catching-up");
+					startStreaming();
+					await firstCatchUp.promise;
+					await collectionsReady;
+				} catch (error) {
+					transitionToFailed(error);
+					throw error;
+				}
+			})();
+			return preloadPromise;
+		},
+		flushPersistence,
+		cleanup() {
+			cleanupPromise ??= (async () => {
+				transitionTo("disposed");
+				initializedOutboxSynchronizer.dispose();
+				firstCatchUp.reject(new DOMException("Fragno outbox coordinator disposed.", "AbortError"));
+				await preloadPromise?.catch(() => {});
+				await streamPromise?.catch(() => {});
+				const errors = [];
+				for (const cleanup of [
+					flushPersistence,
+					() => initializedCollectionRegistry.cleanup(),
+					() => initializedInternalCollection.cleanup(),
+					() => persistence.drain(),
+					() => persistenceResource.cleanup()
+				]) try {
+					await cleanup();
+				} catch (error) {
+					errors.push(error);
+				}
+				if (errors.length > 0) throw new AggregateError(errors, "Failed to clean up the Fragno outbox coordinator.");
+			})();
+			return cleanupPromise;
+		}
+	};
+}
+async function waitForFragnoOutboxStartupStage(stagePromise, stage) {
+	let timeout;
+	const timeoutPromise = new Promise((_, reject) => {
+		timeout = setTimeout(() => {
+			reject(/* @__PURE__ */ new Error(`Fragno outbox startup timed out after ${FRAGNO_OUTBOX_STARTUP_TIMEOUT_MS}ms while ${stage}.`));
+		}, FRAGNO_OUTBOX_STARTUP_TIMEOUT_MS);
+	});
+	try {
+		return await Promise.race([stagePromise, timeoutPromise]);
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+function waitForRetry(attempt) {
+	const delayMs = Math.min(1e3, 25 * 2 ** Math.min(attempt - 1, 5));
+	return new Promise((resolve) => {
+		setTimeout(resolve, delayMs);
+	});
+}
+function catchUpPageCount(checkpointVersionstamp, currentVersionstamp) {
+	if (!currentVersionstamp) return 1;
+	const checkpointVersion = checkpointVersionstamp ? BigInt(`0x${checkpointVersionstamp.slice(0, 20)}`) : -1n;
+	const currentVersion = BigInt(`0x${currentVersionstamp.slice(0, 20)}`);
+	const remainingEntries = currentVersion > checkpointVersion ? currentVersion - checkpointVersion : 0n;
+	return Math.max(1, Number((remainingEntries + BigInt(FRAGNO_OUTBOX_PAGE_SIZE) - 1n) / BigInt(FRAGNO_OUTBOX_PAGE_SIZE)));
+}
+async function sha256Hex(value) {
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function openBrowserFragnoOutboxPersistence(options) {
+	const { BrowserCollectionCoordinator, createBrowserWASQLitePersistence, openBrowserWASQLiteOPFSDatabase } = await import("@tanstack/browser-db-sqlite-persistence");
+	const database = await openBrowserWASQLiteOPFSDatabase({ databaseName: options.databaseName });
+	const coordinator = new BrowserCollectionCoordinator({ dbName: options.databaseName });
+	return {
+		persistence: createBrowserWASQLitePersistence({
+			database,
+			coordinator
+		}),
+		async cleanup() {
+			coordinator.dispose();
+			await database.close?.();
+		}
+	};
+}
+//#endregion
+export { FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION, FragnoInternalCollection, createFragnoOutboxCoordinator, fetchFragnoOutboxDescription };
+
+//# sourceMappingURL=coordinator.js.map

package/dist/coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.js","names":[],"sources":["../src/coordinator.ts"],"sourcesContent":["import { FRAGNO_OUTBOX_PAGE_SIZE } from \"@fragno-dev/db/outbox\";\nimport type { TableToColumnValues } from \"@fragno-dev/db/query\";\nimport type { AnySchema, AnyTable, FragnoId, FragnoReference } from \"@fragno-dev/db/schema\";\n\nimport type { Collection } from \"@tanstack/db\";\nimport type { PersistedCollectionPersistence } from \"@tanstack/db-sqlite-persistence-core\";\n\nimport {\n  openFragnoBrowserPersistenceWithDiagnostics,\n  type FragnoBrowserPersistenceDiagnostics,\n} from \"./coordinator/fragno-browser-persistence-startup\";\nimport { FragnoCollectionRegistry } from \"./coordinator/fragno-collection-registry\";\nimport {\n  FragnoInternalCollection,\n  type FragnoOutboxCoordinatorState,\n} from \"./coordinator/fragno-internal-collection\";\nimport { FragnoInternalFetcher } from \"./coordinator/fragno-internal-fetcher\";\nimport { orderFragnoPersistenceWrites } from \"./coordinator/fragno-ordered-persistence\";\nimport { FragnoOutboxSynchronizer } from \"./coordinator/fragno-outbox-synchronizer\";\nimport { FragnoOutboxTransportError } from \"./outbox-transport-error\";\n\n/**\n * Problem statement\n * -----------------\n * One Fragno database produces one globally ordered outbox containing mutations for every schema\n * and table stored in that database. The browser should mirror that outbox into one local database,\n * not create an independent transport, checkpoint, or persistence database for every collection.\n *\n * `createFragnoOutboxCoordinator` therefore receives only:\n *\n * - the mounted Fragment base URL;\n * - the Fetch implementation used to call it;\n * - every Fragno schema represented by that outbox.\n *\n * From those inputs it owns the complete local database: source identity, persistence, one exact\n * outbox checkpoint, one catch-up loop, one live stream, and every table collection registered\n * before preload. Callers register typed collections but cannot configure synchronization\n * independently.\n *\n * Data flow\n * ---------\n *\n * createFragnoOutboxCoordinator({ baseUrl, fetch, schemas })\n *   -> derive the Fragno internal outbox URL from baseUrl\n *   -> resolve the physical database adapter identity\n *   -> open one local persistence database for that base URL + adapter identity\n *   -> coordinator.collection(schema, table) lazily registers each requested table collection\n *   -> coordinator.preload() closes registration and preloads every registered collection\n *   -> each collection's sync callback subscribes to the shared outbox synchronizer\n *   -> read the database's one exact persisted outbox checkpoint\n *   -> verify checkpoint UOW identity and stream strictly after its versionstamp\n *   -> validate and decode each outbox entry once\n *   -> route every operation to its schema/table collection\n *   -> commit all affected collections before advancing the database checkpoint\n *   -> mark every collection ready together\n *   -> continue live delivery on the same response after its caught-up marker\n *   -> TanStack live queries update the UI\n *\n * Invariants\n * ----------\n *\n * - one outbox maps to exactly one local database;\n * - every requested table collection is registered before catch-up starts;\n * - one exact checkpoint describes the complete local database, not an individual collection;\n * - an entry advances that checkpoint only after every affected collection has committed;\n * - entries without relevant operations still advance the checkpoint;\n * - reloads and stream rotations verify checkpoint identity without replaying old entries;\n * - changing adapter identity discards the previous local database materialization;\n * - persisted rows alone never make collections ready before network catch-up finishes;\n * - cleanup stops the shared request, stream, persistence, and every generated collection.\n */\n\ntype MaterializedColumnValue<TValue> = TValue extends FragnoId | FragnoReference ? string : TValue;\n\ntype VisibleTableValues<TTable extends AnyTable> = TableToColumnValues<TTable>;\n\nexport type FragnoCollectionRow<TTable extends AnyTable> = {\n  [TColumnName in keyof VisibleTableValues<TTable> as [\n    VisibleTableValues<TTable>[TColumnName],\n  ] extends [null]\n    ? never\n    : TColumnName]: MaterializedColumnValue<VisibleTableValues<TTable>[TColumnName]>;\n};\n\nexport type { FragnoOutboxCheckpoint } from \"./checkpoint\";\nexport type { FragnoBrowserPersistenceDiagnostics } from \"./coordinator/fragno-browser-persistence-startup\";\n\nexport {\n  FragnoInternalCollection,\n  type FragnoInternalRow,\n  type FragnoOutboxCoordinatorError,\n  type FragnoOutboxCoordinatorState,\n} from \"./coordinator/fragno-internal-collection\";\n\n// Version 1 could persist checkpoints without a UOW identity, which cannot verify restored history.\nexport const FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION = 2;\n\nconst FRAGNO_OUTBOX_STARTUP_TIMEOUT_MS = 5_000;\n\nexport type { FragnoInternalDescription } from \"./coordinator/fragno-internal-fetcher\";\n\nexport async function fetchFragnoOutboxDescription(options: {\n  baseUrl: string | URL;\n  fetch: typeof globalThis.fetch;\n  signal?: AbortSignal;\n}) {\n  return await new FragnoInternalFetcher(options).describe({ signal: options.signal });\n}\n\nexport type FragnoOutboxCatchUpProgress = {\n  completedPages: number;\n  totalPages: number;\n  percent: number;\n};\n\ntype FragnoOutboxPersistenceResource = {\n  persistence: PersistedCollectionPersistence;\n  cleanup(): Promise<void>;\n};\n\nexport type FragnoOutboxCoordinatorDependencies = {\n  openPersistence(options: { databaseName: string }): Promise<FragnoOutboxPersistenceResource>;\n};\n\nexport type FragnoCollectionOptions = {\n  /** Use `full` only for tables that never receive updates; Fragno update entries contain patches. */\n  rowUpdateMode?: \"partial\" | \"full\";\n  /** Scans persisted rows once per sync registration to skip missing catch-up truncate deletes. */\n  skipMissingTruncateDeletes?: boolean;\n};\n\nexport type FragnoOutboxCoordinator<TSchemas extends readonly AnySchema[]> = {\n  /** Persisted coordinator metadata and user-queryable lifecycle status. */\n  readonly internal: FragnoInternalCollection;\n\n  /** Current synchronization lifecycle state. */\n  readonly state: FragnoOutboxCoordinatorState;\n\n  collection<TSchema extends TSchemas[number], TTableName extends keyof TSchema[\"tables\"] & string>(\n    schema: TSchema,\n    table: TTableName,\n    options?: FragnoCollectionOptions,\n  ): Collection<FragnoCollectionRow<TSchema[\"tables\"][TTableName]>, string>;\n\n  /** Preloads every generated collection and resolves after shared initial catch-up. */\n  preload(): Promise<void>;\n\n  /** Waits until every accepted local persistence write is durable. */\n  flushPersistence(): Promise<void>;\n\n  /** Stops synchronization and closes every collection and local database resource. */\n  cleanup(): Promise<void>;\n};\n\nexport async function createFragnoOutboxCoordinator<const TSchemas extends readonly AnySchema[]>(\n  options: {\n    baseUrl: string | URL;\n    fetch: typeof globalThis.fetch;\n    schemas: TSchemas;\n    onCatchUpProgress?(progress: FragnoOutboxCatchUpProgress): void;\n    /** Receives recurring browser persistence diagnostics while startup remains stalled. */\n    onBrowserPersistenceDiagnostic?(diagnostics: FragnoBrowserPersistenceDiagnostics): void;\n  },\n  dependencies: FragnoOutboxCoordinatorDependencies = {\n    openPersistence: openBrowserFragnoOutboxPersistence,\n  },\n): Promise<FragnoOutboxCoordinator<TSchemas>> {\n  // State transitions:\n  // opening -> idle -> registering -> catching-up -> live\n  // live -> rotating | retrying -> replaying -> live\n  // Only classified transport interruptions retry; protocol, HTTP, and application failures stop.\n  let state: FragnoOutboxCoordinatorState = \"opening\";\n\n  const internalFetcher = new FragnoInternalFetcher({\n    baseUrl: options.baseUrl,\n    fetch: options.fetch,\n  });\n\n  // Fetch the backend adapter identity before opening local persistence.\n  const { adapterIdentity } = await internalFetcher.describe();\n\n  // Derive one stable, filename-safe local database name from baseUrl and adapter identity.\n  const databaseHash = await sha256Hex(\n    `${internalFetcher.baseUrl}\\0${adapterIdentity}\\0version:${FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION}`,\n  );\n  // OPFSCoopSyncVFS fails to open filenames above 56 characters in some Electron/Chromium\n  // runtimes. A 128-bit hash keeps this deterministic and collision-resistant within that limit.\n  // The v3 prefix leaves behind databases created with the temporary single-process wiring.\n  const databaseName = `fragno-v3-${databaseHash.slice(0, 32)}.sqlite`;\n\n  const persistenceResource = await openFragnoBrowserPersistenceWithDiagnostics({\n    databaseName,\n    onDiagnostic: (diagnostics) => options.onBrowserPersistenceDiagnostic?.(diagnostics),\n    openPersistence: () => dependencies.openPersistence({ databaseName }),\n  });\n  const persistence = orderFragnoPersistenceWrites(persistenceResource.persistence);\n\n  let completedCatchUpPages = 0;\n  let totalCatchUpPages = 1;\n  let internalCollection: FragnoInternalCollection | undefined;\n  let outboxSynchronizer: FragnoOutboxSynchronizer | undefined;\n  let collectionRegistry: FragnoCollectionRegistry<TSchemas> | undefined;\n\n  try {\n    // Load the one exact outbox checkpoint stored for this database.\n    internalCollection = new FragnoInternalCollection({\n      persistence,\n      schemaVersion: FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION,\n      state,\n    });\n    await waitForFragnoOutboxStartupStage(\n      internalCollection.preload(),\n      \"preloading coordinator metadata\",\n    );\n\n    outboxSynchronizer = new FragnoOutboxSynchronizer({\n      fetcher: internalFetcher,\n      adapterIdentity,\n      checkpointStore: internalCollection,\n      onCatchUpPage() {\n        completedCatchUpPages += 1;\n        options.onCatchUpProgress?.({\n          completedPages: completedCatchUpPages,\n          totalPages: totalCatchUpPages,\n          percent:\n            totalCatchUpPages === 0\n              ? 100\n              : Math.min(100, Math.round((completedCatchUpPages / totalCatchUpPages) * 100)),\n        });\n      },\n    });\n    collectionRegistry = new FragnoCollectionRegistry({\n      schemas: options.schemas,\n      persistence,\n      schemaVersion: FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION,\n      outbox: outboxSynchronizer,\n    });\n  } catch (error) {\n    outboxSynchronizer?.dispose();\n    await internalCollection?.cleanup().catch(() => {});\n    await persistenceResource.cleanup().catch(() => {});\n    throw error;\n  }\n\n  if (!internalCollection || !outboxSynchronizer || !collectionRegistry) {\n    await persistenceResource.cleanup();\n    throw new Error(\"Fragno outbox coordinator initialization did not complete.\");\n  }\n\n  const initializedInternalCollection = internalCollection;\n  const initializedOutboxSynchronizer = outboxSynchronizer;\n  const initializedCollectionRegistry = collectionRegistry;\n\n  // The adapter identity is part of the local database name, so a changed backend opens a new\n  // database instead of reusing the previous source's persisted collections.\n\n  // Registered targets are not versioned in local metadata. When adding or removing a collection,\n  // delete this coordinator's local persistence database so every registered table catches up from\n  // the beginning against one fresh shared checkpoint.\n\n  // TanStack exposes no atomic cross-collection UI transaction. Every affected collection commits\n  // an applied-entry checkpoint atomically with its own row changes, making partial entry replay\n  // idempotent before the shared database checkpoint advances.\n\n  let preloadPromise: Promise<void> | undefined;\n  let streamPromise: Promise<void> | undefined;\n  let cleanupPromise: Promise<void> | undefined;\n\n  const transitionTo = (nextState: FragnoOutboxCoordinatorState, error: unknown = null) => {\n    state = nextState;\n    // The status row only reports state, so its receipt is not awaited. A persistence failure in\n    // the internal collection also fails the next checkpoint commit, which fails the stream.\n    void initializedInternalCollection.setState(nextState, error);\n  };\n\n  const transitionToFailed = (error: unknown) => {\n    if (state !== \"disposed\") {\n      transitionTo(\"failed\", error);\n    }\n  };\n\n  transitionTo(\"idle\");\n\n  const flushPersistence = async () => {\n    await initializedInternalCollection.flushPersistence();\n  };\n\n  const isDisposed = () => state === \"disposed\";\n\n  const firstCatchUp = Promise.withResolvers<void>();\n  // Cleanup may reject readiness before a caller has started preload.\n  void firstCatchUp.promise.catch(() => {});\n\n  const startStreaming = () => {\n    streamPromise ??= (async () => {\n      let retryAttempt = 0;\n\n      while (!isDisposed()) {\n        try {\n          await initializedOutboxSynchronizer.streamSession({\n            onStarted(targetVersionstamp) {\n              completedCatchUpPages = 0;\n              totalCatchUpPages = catchUpPageCount(\n                initializedInternalCollection.getCheckpoint()?.versionstamp,\n                targetVersionstamp,\n              );\n            },\n            onCaughtUp() {\n              retryAttempt = 0;\n              transitionTo(\"live\");\n              firstCatchUp.resolve();\n            },\n          });\n          if (!isDisposed()) {\n            transitionTo(\"rotating\");\n            transitionTo(\"replaying\");\n          }\n        } catch (error) {\n          if (isDisposed()) {\n            return;\n          }\n\n          if (!(error instanceof FragnoOutboxTransportError)) {\n            firstCatchUp.reject(error);\n            transitionToFailed(error);\n            return;\n          }\n          transitionTo(\"retrying\", error);\n          retryAttempt += 1;\n          await waitForRetry(retryAttempt);\n          if (isDisposed()) {\n            return;\n          }\n\n          transitionTo(\"replaying\");\n        }\n      }\n    })();\n    void streamPromise.catch((error: unknown) => {\n      firstCatchUp.reject(error);\n      transitionToFailed(error);\n    });\n  };\n\n  return {\n    internal: initializedInternalCollection,\n\n    get state() {\n      return state;\n    },\n\n    collection(schema, tableName, collectionOptions) {\n      return initializedCollectionRegistry.registerCollection(\n        schema,\n        tableName,\n        state,\n        collectionOptions,\n      );\n    },\n\n    preload() {\n      preloadPromise ??= (async () => {\n        if (state !== \"idle\") {\n          throw new Error(`Cannot preload Fragno collections while the coordinator is ${state}.`);\n        }\n\n        try {\n          transitionTo(\"registering\");\n          const collectionsReady = initializedCollectionRegistry.preload();\n          const collectionsRegistered = initializedOutboxSynchronizer.waitUntilRegistered(\n            initializedCollectionRegistry.registeredTargets(),\n          );\n          await waitForFragnoOutboxStartupStage(\n            Promise.race([\n              collectionsRegistered,\n              collectionsReady.then(() => {\n                throw new Error(\n                  \"Fragno collections became ready before outbox synchronization registration completed.\",\n                );\n              }),\n            ]),\n            \"registering synchronized collections\",\n          );\n\n          transitionTo(\"catching-up\");\n          startStreaming();\n          await firstCatchUp.promise;\n          await collectionsReady;\n        } catch (error) {\n          transitionToFailed(error);\n          throw error;\n        }\n      })();\n\n      return preloadPromise;\n    },\n\n    flushPersistence,\n\n    cleanup() {\n      cleanupPromise ??= (async () => {\n        transitionTo(\"disposed\");\n        initializedOutboxSynchronizer.dispose();\n        firstCatchUp.reject(new DOMException(\"Fragno outbox coordinator disposed.\", \"AbortError\"));\n        await preloadPromise?.catch(() => {});\n        await streamPromise?.catch(() => {});\n\n        const errors: unknown[] = [];\n        for (const cleanup of [\n          flushPersistence,\n          () => initializedCollectionRegistry.cleanup(),\n          () => initializedInternalCollection.cleanup(),\n          () => persistence.drain(),\n          () => persistenceResource.cleanup(),\n        ]) {\n          try {\n            await cleanup();\n          } catch (error) {\n            errors.push(error);\n          }\n        }\n\n        if (errors.length > 0) {\n          throw new AggregateError(errors, \"Failed to clean up the Fragno outbox coordinator.\");\n        }\n      })();\n\n      return cleanupPromise;\n    },\n  };\n}\n\nasync function waitForFragnoOutboxStartupStage<T>(\n  stagePromise: Promise<T>,\n  stage: string,\n): Promise<T> {\n  let timeout: ReturnType<typeof setTimeout> | undefined;\n  const timeoutPromise = new Promise<never>((_, reject) => {\n    timeout = setTimeout(() => {\n      reject(\n        new Error(\n          `Fragno outbox startup timed out after ${FRAGNO_OUTBOX_STARTUP_TIMEOUT_MS}ms while ${stage}.`,\n        ),\n      );\n    }, FRAGNO_OUTBOX_STARTUP_TIMEOUT_MS);\n  });\n\n  try {\n    return await Promise.race([stagePromise, timeoutPromise]);\n  } finally {\n    clearTimeout(timeout);\n  }\n}\n\nfunction waitForRetry(attempt: number): Promise<void> {\n  const delayMs = Math.min(1_000, 25 * 2 ** Math.min(attempt - 1, 5));\n  return new Promise<void>((resolve) => {\n    setTimeout(resolve, delayMs);\n  });\n}\n\nfunction catchUpPageCount(\n  checkpointVersionstamp: string | undefined,\n  currentVersionstamp: string | null,\n): number {\n  if (!currentVersionstamp) {\n    return 1;\n  }\n\n  const checkpointVersion = checkpointVersionstamp\n    ? BigInt(`0x${checkpointVersionstamp.slice(0, 20)}`)\n    : -1n;\n  const currentVersion = BigInt(`0x${currentVersionstamp.slice(0, 20)}`);\n  const remainingEntries =\n    currentVersion > checkpointVersion ? currentVersion - checkpointVersion : 0n;\n  return Math.max(\n    1,\n    Number(\n      (remainingEntries + BigInt(FRAGNO_OUTBOX_PAGE_SIZE) - 1n) / BigInt(FRAGNO_OUTBOX_PAGE_SIZE),\n    ),\n  );\n}\n\nasync function sha256Hex(value: string): Promise<string> {\n  const digest = await globalThis.crypto.subtle.digest(\"SHA-256\", new TextEncoder().encode(value));\n  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\nasync function openBrowserFragnoOutboxPersistence(options: { databaseName: string }): Promise<{\n  persistence: PersistedCollectionPersistence;\n  cleanup(): Promise<void>;\n}> {\n  const {\n    BrowserCollectionCoordinator,\n    createBrowserWASQLitePersistence,\n    openBrowserWASQLiteOPFSDatabase,\n  } = await import(\"@tanstack/browser-db-sqlite-persistence\");\n  const database = await openBrowserWASQLiteOPFSDatabase({ databaseName: options.databaseName });\n  const coordinator = new BrowserCollectionCoordinator({ dbName: options.databaseName });\n\n  return {\n    persistence: createBrowserWASQLitePersistence({ database, coordinator }),\n    async cleanup() {\n      coordinator.dispose();\n      await database.close?.();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/outbox-stream.js

@@ -0,0 +1,85 @@
+import { FragnoOutboxTransportError, rethrowOutboxNetworkFailure } from "./outbox-transport-error.js";
+import { parseOutboxStreamFrame } from "@fragno-dev/db/outbox-stream";
+//#region src/outbox-stream.ts
+/** Protocol violations are terminal: retrying cannot repair an incompatible or changed source. */
+var FragnoOutboxProtocolError = class extends Error {};
+/** Consumes one ordered stream session; only a final rotate frame permits normal completion. */
+async function consumeNdjsonOutboxStream(body, consumer) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let completed = false;
+	let started = false;
+	let caughtUp = false;
+	let rotated = false;
+	let target = null;
+	let previousVersionstamp = consumer.afterVersionstamp;
+	const cancelReader = () => {
+		reader.cancel(consumer.signal.reason).catch(() => {});
+	};
+	if (consumer.signal.aborted) cancelReader();
+	else consumer.signal.addEventListener("abort", cancelReader, { once: true });
+	async function consumeFrame(line) {
+		let frame;
+		try {
+			frame = parseOutboxStreamFrame(JSON.parse(line));
+		} catch (cause) {
+			throw new FragnoOutboxProtocolError("Invalid Fragno outbox stream frame.", { cause });
+		}
+		if (rotated || !started && frame.type !== "started") throw new FragnoOutboxProtocolError("Invalid Fragno outbox stream frame order.");
+		switch (frame.type) {
+			case "started":
+				if (started) throw new FragnoOutboxProtocolError("Duplicate Fragno outbox started frame.");
+				started = true;
+				target = frame.catchUpTargetVersionstamp;
+				break;
+			case "entry":
+				if (previousVersionstamp !== void 0 && frame.entry.versionstamp <= previousVersionstamp || !caughtUp && (target === null || frame.entry.versionstamp > target)) throw new FragnoOutboxProtocolError("Fragno outbox stream entries are not strictly ordered around the catch-up boundary.");
+				previousVersionstamp = frame.entry.versionstamp;
+				break;
+			case "caught-up":
+				if (caughtUp || frame.throughVersionstamp !== target || target !== null && previousVersionstamp !== target) throw new FragnoOutboxProtocolError("Invalid Fragno outbox caught-up boundary.");
+				caughtUp = true;
+				break;
+			case "rotate":
+				rotated = true;
+				break;
+			case "heartbeat": break;
+		}
+		await consumer.onFrame(frame);
+	}
+	try {
+		while (!consumer.signal.aborted) {
+			let result;
+			try {
+				result = await reader.read();
+			} catch (cause) {
+				rethrowOutboxNetworkFailure(cause, consumer.signal);
+			}
+			const { done, value } = result;
+			if (done) {
+				completed = true;
+				break;
+			}
+			buffer += decoder.decode(value, { stream: true });
+			let newline;
+			while (!consumer.signal.aborted && (newline = buffer.indexOf("\n")) !== -1) {
+				const line = buffer.slice(0, newline);
+				buffer = buffer.slice(newline + 1);
+				await consumeFrame(line);
+			}
+		}
+		if (consumer.signal.aborted) throw new DOMException("Fragno outbox streaming was aborted.", "AbortError");
+		buffer += decoder.decode();
+		if (!rotated) throw new FragnoOutboxTransportError("Fragno outbox stream closed unexpectedly.");
+		if (buffer.length > 0) throw new FragnoOutboxProtocolError("Fragno outbox stream contains data after rotation.");
+	} finally {
+		consumer.signal.removeEventListener("abort", cancelReader);
+		if (!completed) await reader.cancel().catch(() => {});
+		reader.releaseLock();
+	}
+}
+//#endregion
+export { FragnoOutboxProtocolError, consumeNdjsonOutboxStream };
+
+//# sourceMappingURL=outbox-stream.js.map

package/dist/outbox-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-stream.js","names":[],"sources":["../src/outbox-stream.ts"],"sourcesContent":["import { parseOutboxStreamFrame, type OutboxStreamFrame } from \"@fragno-dev/db/outbox-stream\";\n\nimport { FragnoOutboxTransportError, rethrowOutboxNetworkFailure } from \"./outbox-transport-error\";\n\n/** Protocol violations are terminal: retrying cannot repair an incompatible or changed source. */\nexport class FragnoOutboxProtocolError extends Error {}\n\ntype FragnoOutboxStreamConsumer = {\n  signal: AbortSignal;\n  afterVersionstamp: string | undefined;\n  onFrame(frame: OutboxStreamFrame): void | Promise<void>;\n};\n\n/** Consumes one ordered stream session; only a final rotate frame permits normal completion. */\nexport async function consumeNdjsonOutboxStream(\n  body: ReadableStream<Uint8Array>,\n  consumer: FragnoOutboxStreamConsumer,\n): Promise<void> {\n  const reader = body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = \"\";\n  let completed = false;\n  let started = false;\n  let caughtUp = false;\n  let rotated = false;\n  let target: string | null = null;\n  let previousVersionstamp = consumer.afterVersionstamp;\n  const cancelReader = () => {\n    void reader.cancel(consumer.signal.reason).catch(() => {});\n  };\n  if (consumer.signal.aborted) {\n    cancelReader();\n  } else {\n    consumer.signal.addEventListener(\"abort\", cancelReader, { once: true });\n  }\n\n  async function consumeFrame(line: string): Promise<void> {\n    let frame: OutboxStreamFrame;\n    try {\n      frame = parseOutboxStreamFrame(JSON.parse(line));\n    } catch (cause) {\n      throw new FragnoOutboxProtocolError(\"Invalid Fragno outbox stream frame.\", { cause });\n    }\n    if (rotated || (!started && frame.type !== \"started\")) {\n      throw new FragnoOutboxProtocolError(\"Invalid Fragno outbox stream frame order.\");\n    }\n    switch (frame.type) {\n      case \"started\":\n        if (started) {\n          throw new FragnoOutboxProtocolError(\"Duplicate Fragno outbox started frame.\");\n        }\n        started = true;\n        target = frame.catchUpTargetVersionstamp;\n        break;\n      case \"entry\":\n        if (\n          (previousVersionstamp !== undefined &&\n            frame.entry.versionstamp <= previousVersionstamp) ||\n          (!caughtUp && (target === null || frame.entry.versionstamp > target))\n        ) {\n          throw new FragnoOutboxProtocolError(\n            \"Fragno outbox stream entries are not strictly ordered around the catch-up boundary.\",\n          );\n        }\n        previousVersionstamp = frame.entry.versionstamp;\n        break;\n      case \"caught-up\":\n        if (\n          caughtUp ||\n          frame.throughVersionstamp !== target ||\n          (target !== null && previousVersionstamp !== target)\n        ) {\n          throw new FragnoOutboxProtocolError(\"Invalid Fragno outbox caught-up boundary.\");\n        }\n        caughtUp = true;\n        break;\n      case \"rotate\":\n        rotated = true;\n        break;\n      case \"heartbeat\":\n        break;\n    }\n    await consumer.onFrame(frame);\n  }\n\n  try {\n    while (!consumer.signal.aborted) {\n      let result: ReadableStreamReadResult<Uint8Array>;\n      try {\n        result = await reader.read();\n      } catch (cause) {\n        rethrowOutboxNetworkFailure(cause, consumer.signal);\n      }\n      const { done, value } = result;\n      if (done) {\n        completed = true;\n        break;\n      }\n      buffer += decoder.decode(value, { stream: true });\n      let newline: number;\n      while (!consumer.signal.aborted && (newline = buffer.indexOf(\"\\n\")) !== -1) {\n        const line = buffer.slice(0, newline);\n        buffer = buffer.slice(newline + 1);\n        await consumeFrame(line);\n      }\n    }\n    if (consumer.signal.aborted) {\n      throw new DOMException(\"Fragno outbox streaming was aborted.\", \"AbortError\");\n    }\n    buffer += decoder.decode();\n    if (!rotated) {\n      throw new FragnoOutboxTransportError(\"Fragno outbox stream closed unexpectedly.\");\n    }\n    if (buffer.length > 0) {\n      throw new FragnoOutboxProtocolError(\"Fragno outbox stream contains data after rotation.\");\n    }\n  } finally {\n    consumer.signal.removeEventListener(\"abort\", cancelReader);\n    if (!completed) {\n      await reader.cancel().catch(() => {});\n    }\n    reader.releaseLock();\n  }\n}\n"],"mappings":";;;;AAKA,IAAa,4BAAb,cAA+C,MAAM,CAAC;;AAStD,eAAsB,0BACpB,MACA,UACe;CACf,MAAM,SAAS,KAAK,UAAU;CAC9B,MAAM,UAAU,IAAI,YAAY;CAChC,IAAI,SAAS;CACb,IAAI,YAAY;CAChB,IAAI,UAAU;CACd,IAAI,WAAW;CACf,IAAI,UAAU;CACd,IAAI,SAAwB;CAC5B,IAAI,uBAAuB,SAAS;CACpC,MAAM,qBAAqB;EACzB,OAAY,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;CAC3D;CACA,IAAI,SAAS,OAAO,SAClB,aAAa;MAEb,SAAS,OAAO,iBAAiB,SAAS,cAAc,EAAE,MAAM,KAAK,CAAC;CAGxE,eAAe,aAAa,MAA6B;EACvD,IAAI;EACJ,IAAI;GACF,QAAQ,uBAAuB,KAAK,MAAM,IAAI,CAAC;EACjD,SAAS,OAAO;GACd,MAAM,IAAI,0BAA0B,uCAAuC,EAAE,MAAM,CAAC;EACtF;EACA,IAAI,WAAY,CAAC,WAAW,MAAM,SAAS,WACzC,MAAM,IAAI,0BAA0B,2CAA2C;EAEjF,QAAQ,MAAM,MAAd;GACE,KAAK;IACH,IAAI,SACF,MAAM,IAAI,0BAA0B,wCAAwC;IAE9E,UAAU;IACV,SAAS,MAAM;IACf;GACF,KAAK;IACH,IACG,yBAAyB,KAAA,KACxB,MAAM,MAAM,gBAAgB,wBAC7B,CAAC,aAAa,WAAW,QAAQ,MAAM,MAAM,eAAe,SAE7D,MAAM,IAAI,0BACR,qFACF;IAEF,uBAAuB,MAAM,MAAM;IACnC;GACF,KAAK;IACH,IACE,YACA,MAAM,wBAAwB,UAC7B,WAAW,QAAQ,yBAAyB,QAE7C,MAAM,IAAI,0BAA0B,2CAA2C;IAEjF,WAAW;IACX;GACF,KAAK;IACH,UAAU;IACV;GACF,KAAK,aACH;EACJ;EACA,MAAM,SAAS,QAAQ,KAAK;CAC9B;CAEA,IAAI;EACF,OAAO,CAAC,SAAS,OAAO,SAAS;GAC/B,IAAI;GACJ,IAAI;IACF,SAAS,MAAM,OAAO,KAAK;GAC7B,SAAS,OAAO;IACd,4BAA4B,OAAO,SAAS,MAAM;GACpD;GACA,MAAM,EAAE,MAAM,UAAU;GACxB,IAAI,MAAM;IACR,YAAY;IACZ;GACF;GACA,UAAU,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC;GAChD,IAAI;GACJ,OAAO,CAAC,SAAS,OAAO,YAAY,UAAU,OAAO,QAAQ,IAAI,OAAO,IAAI;IAC1E,MAAM,OAAO,OAAO,MAAM,GAAG,OAAO;IACpC,SAAS,OAAO,MAAM,UAAU,CAAC;IACjC,MAAM,aAAa,IAAI;GACzB;EACF;EACA,IAAI,SAAS,OAAO,SAClB,MAAM,IAAI,aAAa,wCAAwC,YAAY;EAE7E,UAAU,QAAQ,OAAO;EACzB,IAAI,CAAC,SACH,MAAM,IAAI,2BAA2B,2CAA2C;EAElF,IAAI,OAAO,SAAS,GAClB,MAAM,IAAI,0BAA0B,oDAAoD;CAE5F,UAAU;EACR,SAAS,OAAO,oBAAoB,SAAS,YAAY;EACzD,IAAI,CAAC,WACH,MAAM,OAAO,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC;EAEtC,OAAO,YAAY;CACrB;AACF"}

package/dist/outbox-transport-error.js

@@ -0,0 +1,12 @@
+//#region src/outbox-transport-error.ts
+/** Only transport interruptions permit retrying an outbox stream session. */
+var FragnoOutboxTransportError = class extends Error {};
+/** Classify network errors only at Fetch/read boundaries, never around decoding or application. */
+function rethrowOutboxNetworkFailure(cause, signal) {
+	if (!signal?.aborted && (cause instanceof TypeError || cause instanceof DOMException && cause.name === "NetworkError")) throw new FragnoOutboxTransportError("Fragno outbox stream transport interrupted.", { cause });
+	throw cause;
+}
+//#endregion
+export { FragnoOutboxTransportError, rethrowOutboxNetworkFailure };
+
+//# sourceMappingURL=outbox-transport-error.js.map

package/dist/outbox-transport-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-transport-error.js","names":[],"sources":["../src/outbox-transport-error.ts"],"sourcesContent":["/** Only transport interruptions permit retrying an outbox stream session. */\nexport class FragnoOutboxTransportError extends Error {}\n\n/** Classify network errors only at Fetch/read boundaries, never around decoding or application. */\nexport function rethrowOutboxNetworkFailure(\n  cause: unknown,\n  signal: AbortSignal | undefined,\n): never {\n  // Fetch reports network failures as TypeError (or NetworkError in some stream implementations).\n  // Construct and validate requests outside this boundary so request errors remain terminal.\n  if (\n    !signal?.aborted &&\n    (cause instanceof TypeError || (cause instanceof DOMException && cause.name === \"NetworkError\"))\n  ) {\n    throw new FragnoOutboxTransportError(\"Fragno outbox stream transport interrupted.\", { cause });\n  }\n  throw cause;\n}\n"],"mappings":";;AACA,IAAa,6BAAb,cAAgD,MAAM,CAAC;;AAGvD,SAAgB,4BACd,OACA,QACO;CAGP,IACE,CAAC,QAAQ,YACR,iBAAiB,aAAc,iBAAiB,gBAAgB,MAAM,SAAS,iBAEhF,MAAM,IAAI,2BAA2B,+CAA+C,EAAE,MAAM,CAAC;CAE/F,MAAM;AACR"}