@spooky-sync/core 0.0.1-canary.323 → 0.0.1-canary.325

package/dist/index.js

@@ -2188,8 +2188,8 @@ function trimHistory(history, cap) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.323";
-const WASM_VERSION = "0.0.1-canary.323";
+const CORE_VERSION = "0.0.1-canary.325";
+const WASM_VERSION = "0.0.1-canary.325";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	version = CORE_VERSION;
@@ -3814,6 +3814,14 @@ function listRefTable(env, s) {
 	const userId = s.userId ?? (env.anonLive ? ANON_USER_ID : null);
 	return listRefTableFor(env.refMode, userId);
 }
+/**
+* Whether this session can be sent a view's membership at all. A signed-out
+* session reads edges only from `_00_list_ref_anon`, and only with
+* `enableAnonymousLiveQueries`: without it the SSP files its views under no
+* identity in `_00_list_ref`, whose rule shows those edges to no caller. Such
+* a view can register and report its row count, but never its rows.
+*/
+const receivesMembership = (env, s) => s.userId !== null || env.anonLive;
 function columnsFor(env, table) {
 	const found = env.schema.tables.find((t) => t.name === table);
 	if (found) return found.columns;
@@ -5629,6 +5637,12 @@ function* refreshFailedCount() {
 }
 const ERR = (r) => r && r.status === "ERR" ? r.error : null;
 /**
+* A CRDT edit-log row (`<table>__crdt_log`) is written once and never changes,
+* so a CREATE retried after its first attempt committed (and only the answer
+* was lost) finds it already there: that is a success, not a rejection.
+*/
+const isRepeatedLogCreate = (row, err) => row.mutationType === "create" && row.tableName.endsWith("__crdt_log") && /already exists/i.test(err);
+/**
 * Drain the outbox: one serial lane, FIFO, up to `outboxBatchSize` statements
 * per request, per-statement outcome. Accepted rows are acked (they stay in
 * the overlay until membership names them), rejected rows are rolled back,
@@ -5692,7 +5706,7 @@ function* drain(env) {
 				break;
 			}
 			const err = ERR(r);
-			if (err === null) {
+			if (err === null || isRepeatedLogCreate(row, err)) {
 				const del = deletePendingRow(row.id);
 				try {
 					yield fx.local.query(del.sql, del.vars);
@@ -6025,10 +6039,16 @@ var PreloadFailedError = class extends Error {
 * Never resolved: blocks until the server's membership and every body are
 * local and the first materialization ran. The entry is evicted like any
 * other query a ttl after it was last watched (or registered).
+*
+* A session that cannot be sent membership (signed out, without anonymous
+* live queries) does not wait either: a view with rows would never settle,
+* and an app that gates its first paint on a preload showed its loading
+* screen forever, signed-out landing page included.
 */
 function* preload(env, input) {
 	const hash = yield* registerLocal(env, input);
-	if ((yield fx.state.read((s) => s.queries.get(hash)?.lifecycle.phase)) !== "cold") return {
+	const [phase, reachable] = yield fx.state.read((s) => [s.queries.get(hash)?.lifecycle.phase, receivesMembership(env, s)]);
+	if (phase !== "cold" || !reachable) return {
 		hash,
 		waited: false
 	};
@@ -6419,7 +6439,7 @@ function rowsFromResult(effect, result) {
 * the SurrealDB one. `null` for a row that carries none (a projection
 * without `id`, a `SELECT VALUE`).
 */
-function rowKey(row) {
+function rowKey$1(row) {
 	const id = row !== null && typeof row === "object" ? row.id : void 0;
 	if (typeof id === "string") return id;
 	if (id !== null && typeof id === "object" && "table" in id && "id" in id) return encodeRecordId(id);
@@ -6519,7 +6539,7 @@ function* materialize(hash) {
 	let rows;
 	try {
 		rows = rowsFromResult(effect, yield effect);
-		if (ids === null) rows = rows.filter((row) => paints(rowKey(row)));
+		if (ids === null) rows = rows.filter((row) => paints(rowKey$1(row)));
 	} catch (error) {
 		yield fx.state.update(compose(recordError(hash), clearDirty(hash)));
 		yield fx.emit({
@@ -8097,7 +8117,7 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 			try {
 				await client.close();
 			} catch {}
-			await delay(150 * attempt);
+			await delay$1(150 * attempt);
 			try {
 				await this.openStore(client, storeUrl, namespace, database);
 				this.logger.info({
@@ -8176,7 +8196,7 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 		this.logger.debug({ Category: "sp00ky-client::LocalDatabaseService::connect" }, "[LocalDatabaseService] client.use returned");
 	}
 };
-function delay(ms) {
+function delay$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /** True for the SurrealDB-WASM error raised when its IndexedDB-backed key-value
@@ -8841,13 +8861,15 @@ const sha1 = async (str) => {
 };
 /**
 * Local-only state a schema change must not throw away: the outbox, the
-* failed-mutation tray and debounced patches not yet in the outbox. Cached
-* rows refill from the server; these exist nowhere else.
+* failed-mutation tray, debounced patches not yet in the outbox and CRDT
+* documents with edits not yet sent. Cached rows refill from the server;
+* these exist nowhere else.
 */
 const KEPT_TABLES = [
 	"_00_pending_mutations",
 	"_00_failed_mutations",
-	"_00_pending_writes"
+	"_00_pending_writes",
+	"_00_crdt_local"
 ];
 var LocalMigrator = class {
 	logger;
@@ -8865,7 +8887,7 @@ var LocalMigrator = class {
 		}
 		const kept = await this.readKeptRows();
 		await this.recreateDatabase(database);
-		const fullSchema = schemaSurql + "\n\n      DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_view SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_window SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_failed_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_writes SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_blob SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n    ";
+		const fullSchema = schemaSurql + "\n\n      DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_view SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_window SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_failed_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_writes SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_blob SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_crdt_local SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n    ";
 		const statements = this.splitStatements(fullSchema);
 		for (let i = 0; i < statements.length; i++) {
 			const statement = statements[i];
@@ -9739,6 +9761,7 @@ const SYSTEM_TABLES = [
 	"_00_pending_mutations",
 	"_00_pending_writes",
 	"_00_blob",
+	"_00_crdt_local",
 	"_00_user_feature",
 	"_00_app_release"
 ];
@@ -12168,6 +12191,109 @@ var AuthService = class {
 	}
 };
 
+//#endregion
+//#region src/modules/crdt/acceptance.ts
+/** The largest blob a row may carry (the generated column's cap). */
+const MAX_DELTA_BYTES = 256 * 1024;
+const PEER = /^\d{1,20}$/;
+/** `"loro"`: every Loro blob starts with it. */
+const MAGIC = [
+	108,
+	111,
+	114,
+	111
+];
+/** Header bytes 20..22 (big-endian) carry the encoding mode; 4 is an update. */
+const MODE_UPDATES = 4;
+function check(loro, blob, peer, maxBytes = MAX_DELTA_BYTES) {
+	if (!blob || blob.length === 0) return {
+		ok: false,
+		reason: "empty"
+	};
+	if (blob.length > maxBytes) return {
+		ok: false,
+		reason: "too_large"
+	};
+	if (typeof peer !== "string" || !PEER.test(peer)) return {
+		ok: false,
+		reason: "bad_peer"
+	};
+	if (blob.length < 22 || MAGIC.some((b, i) => blob[i] !== b)) return {
+		ok: false,
+		reason: "header"
+	};
+	if ((blob[20] << 8 | blob[21]) !== MODE_UPDATES) return {
+		ok: false,
+		reason: "not_an_update"
+	};
+	let meta;
+	try {
+		meta = loro.decodeImportBlobMeta(blob, true);
+	} catch {
+		return {
+			ok: false,
+			reason: "undecodable"
+		};
+	}
+	if (meta.mode !== "update") return {
+		ok: false,
+		reason: "not_an_update"
+	};
+	const start = meta.partialStartVersionVector.toJSON();
+	const authors = [];
+	for (const [p, end] of meta.partialEndVersionVector.toJSON()) if (end > (start.get(p) ?? 0)) authors.push([String(p), end]);
+	if (authors.length === 0) return {
+		ok: false,
+		reason: "no_ops"
+	};
+	if (authors.length > 1 || BigInt(authors[0][0]) !== BigInt(peer)) return {
+		ok: false,
+		reason: "foreign_peer"
+	};
+	return {
+		ok: true,
+		accepted: {
+			peer,
+			end: authors[0][1]
+		}
+	};
+}
+
+//#endregion
+//#region src/modules/crdt/bytes.ts
+/**
+* Byte columns reach the client in several shapes depending on the engine and
+* the path: `Uint8Array` (SQLite, a fresh local write), `ArrayBuffer` (the
+* surrealdb SDK's CBOR decode), a typed-array view, or a `number[]` (bytes
+* nested in a FLEXIBLE object on the SurrealDB-WASM engine). Normalize all of
+* them; anything else is not bytes.
+*/
+function asBytes(value) {
+	if (value instanceof Uint8Array) return value;
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+	if (Array.isArray(value) && value.length > 0 && value.every((n) => typeof n === "number")) return Uint8Array.from(value);
+}
+function encodeBase64(bytes) {
+	if (typeof btoa === "function") {
+		let binary = "";
+		for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+		return btoa(binary);
+	}
+	return Buffer.from(bytes).toString("base64");
+}
+/**
+* A random Loro peer id below 2^53 (so it is exact as a JS number), as the
+* decimal string Loro uses for `PeerID`. Each tab picks a new one per session
+* and claims it in `_00_crdt_peer` before any of its edits are sent.
+*/
+function randomPeer() {
+	const words = new Uint32Array(2);
+	crypto.getRandomValues(words);
+	const id = (words[0] & 2097151) * 4294967296 + words[1];
+	return String(id === 0 ? 1 : id);
+}
+
 //#endregion
 //#region src/modules/crdt/crdt-field.ts
 const CURSOR_COLORS = [
@@ -12185,222 +12311,139 @@ function cursorColorFromName(name) {
 	for (let i = 0; i < name.length; i++) hash = (hash << 5) - hash + name.charCodeAt(i) | 0;
 	return CURSOR_COLORS[Math.abs(hash) % CURSOR_COLORS.length];
 }
+/**
+* An open collaborative field: the Loro document an editor binds to. Edits
+* made on it are sent as the client's own edit-log rows; other clients' rows
+* are imported into it as they arrive. Every open of the same field in one tab
+* shares this document.
+*/
 var CrdtField = class {
-	doc;
-	pushTimer = null;
-	local = null;
-	remote = null;
-	recordId = null;
-	sessionId = "";
-	unsubscribe = null;
-	lastPushTime = 0;
-	lastCursorPushTime = 0;
-	loadedFromCrdt = false;
-	pushRetryCount = 0;
-	logger;
-	cursorsEnabled;
-	/** Remote-push debounce. Local writes happen immediately on every Loro
-	*  update; the remote UPSERT is coalesced over this window. Configured
-	*  via `Sp00kyConfig.crdtDebounceMs`, default 500. */
-	remoteDebounceMs = 500;
 	_onCursorUpdate = null;
 	pendingCursorUpdate = null;
-	/** Callback set by the editor to receive remote cursor updates.
-	*  Any cursor data that arrived before this callback was set will be replayed. */
-	set onCursorUpdate(cb) {
-		this._onCursorUpdate = cb;
-		if (cb && this.pendingCursorUpdate) {
-			try {
-				cb(this.pendingCursorUpdate);
-			} catch (e) {
-				this.logger?.warn({
-					error: e,
-					Category: "sp00ky-client::CrdtField::onCursorUpdate"
-				}, "Failed to replay pending cursor update");
-			}
-			this.pendingCursorUpdate = null;
-		}
-	}
-	get onCursorUpdate() {
-		return this._onCursorUpdate;
-	}
-	/**
-	* @param LoroDocClass the `LoroDoc` constructor, injected by the caller after
-	*   awaiting {@link loadLoro} — keeps `loro-crdt` out of this module's static
-	*   import graph so it only ships to apps that use CRDT fields.
-	*/
-	constructor(fieldName, cursorsEnabled, LoroDocClass, initialState, logger) {
+	constructor(table, recordId, fieldName, kind, cursorsEnabled, doc, host) {
+		this.table = table;
+		this.recordId = recordId;
 		this.fieldName = fieldName;
-		if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(fieldName)) throw new Error(`CrdtField: refusing unsafe field identifier '${fieldName}' — must match [a-zA-Z_][a-zA-Z0-9_]*`);
-		this.logger = logger ?? null;
+		this.kind = kind;
 		this.cursorsEnabled = cursorsEnabled;
-		this.doc = new LoroDocClass();
-		if (initialState && initialState.length > 0) try {
-			this.doc.import(initialState);
-			this.loadedFromCrdt = true;
-		} catch (e) {
-			this.logger?.warn({
-				error: e,
-				fieldName,
-				Category: "sp00ky-client::CrdtField::constructor"
-			}, "Initial CRDT state is not a valid LoroDoc snapshot — starting empty and will seed from fallback text");
-		}
+		this.doc = doc;
+		this.host = host;
 	}
 	getDoc() {
 		return this.doc;
 	}
-	/** Whether the LoroDoc was loaded from saved CRDT state */
+	/** Whether the document holds anything yet (local state or edits). */
 	hasContent() {
-		return this.loadedFromCrdt;
+		return this.doc.oplogVersion().length() > 0;
 	}
-	startSync(local, remote, recordId, sessionId, debounceMs) {
-		this.local = local;
-		this.remote = remote;
-		this.recordId = recordId;
-		this.sessionId = sessionId;
-		this.remoteDebounceMs = debounceMs;
-		this.unsubscribe = this.doc.subscribeLocalUpdates(() => {
-			this.persistLocal();
-			this.scheduleRemotePush();
-		});
+	/** Publish this session's presence (an `EphemeralStore` encoding, e.g. the
+	*  editor's cursor). No-op unless the field is `@cursor`. */
+	pushCursorState(encoded) {
+		if (this.cursorsEnabled) this.host.pushPresence(encoded);
 	}
-	/**
-	* Stop syncing this field. Flushes one final remote push by default so the
-	* last keystrokes aren't lost. Pass `{ flush: false }` on a bucket switch —
-	* the remote session already belongs to the NEXT user, and pushing this
-	* (previous user's) snapshot under it would clobber the record remotely.
-	*/
-	stopSync(options = {}) {
-		const flush = options.flush ?? true;
-		if (this.unsubscribe) {
-			this.unsubscribe();
-			this.unsubscribe = null;
-		}
-		if (this.pushTimer) {
-			clearTimeout(this.pushTimer);
-			this.pushTimer = null;
-		}
-		if (flush && this.remote && this.recordId) this.pushToRemote();
-	}
-	importRemote(state) {
-		if (Date.now() - this.lastPushTime < this.remoteDebounceMs + 200) return;
-		try {
-			this.doc.import(state);
-			this.persistLocal();
-		} catch (e) {
-			this.logger?.warn({
-				error: e,
-				Category: "sp00ky-client::CrdtField::importRemote"
-			}, "Failed to import remote CRDT state");
-		}
-	}
-	exportSnapshot() {
-		return this.doc.export({ mode: "snapshot" });
-	}
-	/** Push this session's cursor blob into the parent row at
-	*  `<field>.cursors[$sid]`. No-op when cursors aren't enabled on this
-	*  field — the editor still calls this method optimistically, but
-	*  without `@cursor` on the schema there's nowhere to store the blob.
-	*  The UPDATE itself fires the parent table's LIVE feed, so other
-	*  browsers receive the cursor change without a separate `_00_rv` bump. */
-	async pushCursorState(encoded) {
-		if (!this.remote || !this.recordId) return;
-		if (!this.cursorsEnabled) return;
-		this.lastCursorPushTime = Date.now();
-		try {
-			const state = encodeBase64(encoded);
-			await this.remote.query(`UPDATE $id SET ${this.fieldName}.cursors[$sid] = $state RETURN NONE;`, {
-				id: parseRecordIdString(this.recordId),
-				sid: this.sessionId,
-				state
-			});
-		} catch (e) {
-			this.logger?.warn({
-				error: e,
-				Category: "sp00ky-client::CrdtField::pushCursorState"
-			}, "Failed to push cursor state");
+	/** Called with every other session's presence blob. A blob that arrives
+	*  before the editor sets this is replayed when it does. */
+	set onCursorUpdate(cb) {
+		this._onCursorUpdate = cb;
+		if (cb && this.pendingCursorUpdate) {
+			const data = this.pendingCursorUpdate;
+			this.pendingCursorUpdate = null;
+			try {
+				cb(data);
+			} catch {}
 		}
 	}
-	/** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
-	importRemoteCursor(base64State) {
-		if (Date.now() - this.lastCursorPushTime < 300) return;
-		try {
-			const data = decodeBase64(base64State);
-			if (this._onCursorUpdate) this._onCursorUpdate(data);
-			else this.pendingCursorUpdate = data;
-		} catch (e) {
-			this.logger?.warn({
-				error: e,
-				Category: "sp00ky-client::CrdtField::importRemoteCursor"
-			}, "Failed to apply remote cursor data");
-		}
-	}
-	scheduleRemotePush() {
-		if (this.pushTimer) clearTimeout(this.pushTimer);
-		this.pushTimer = setTimeout(() => void this.pushToRemote(), this.remoteDebounceMs);
-	}
-	/** SET path inside a parent row for the current snapshot. `@crdt`-only
-	*  fields hold the snapshot directly (`<field>`); `@crdt @cursor`
-	*  fields hold a `{ state, cursors }` object so the snapshot lives at
-	*  `<field>.state` next to per-session cursor blobs. */
-	statePath() {
-		return this.cursorsEnabled ? `${this.fieldName}.state` : this.fieldName;
-	}
-	/** Mirror the LoroDoc snapshot into the parent row locally. Runs on
-	*  every local update and every remote import so reloads (online or
-	*  offline) see the freshest content immediately. Failures are
-	*  swallowed — a stale local write must never block user input. */
-	async persistLocal() {
-		if (!this.local || !this.recordId) return;
-		try {
-			await this.local.query(`UPDATE $id SET ${this.statePath()} = $state RETURN NONE;`, {
-				id: parseRecordIdString(this.recordId),
-				state: this.exportSnapshot()
-			});
-		} catch (e) {
-			this.logger?.debug({
-				error: e,
-				Category: "sp00ky-client::CrdtField::persistLocal"
-			}, "Local CRDT persist failed (best-effort)");
-		}
+	get onCursorUpdate() {
+		return this._onCursorUpdate;
 	}
-	async pushToRemote() {
-		if (!this.remote || !this.recordId) return;
-		this.lastPushTime = Date.now();
-		try {
-			await this.remote.query(`UPDATE $id SET ${this.statePath()} = $state RETURN NONE;`, {
-				id: parseRecordIdString(this.recordId),
-				state: this.exportSnapshot()
-			});
-			this.pushRetryCount = 0;
-		} catch (e) {
-			this.logger?.warn({
-				error: e,
-				Category: "sp00ky-client::CrdtField::pushToRemote"
-			}, "Failed to push CRDT state to remote");
-			if (this.pushRetryCount < 2) {
-				this.pushRetryCount++;
-				this.scheduleRemotePush();
-			}
-		}
+	/** @internal Deliver one remote presence blob. */
+	deliverPresence(data) {
+		if (this._onCursorUpdate) this._onCursorUpdate(data);
+		else this.pendingCursorUpdate = data;
 	}
 };
-function decodeBase64(b64) {
-	if (typeof atob === "function") {
-		const binary = atob(b64);
-		const bytes = new Uint8Array(binary.length);
-		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-		return bytes;
-	}
-	return new Uint8Array(Buffer.from(b64, "base64"));
+
+//#endregion
+//#region src/modules/crdt/hash.ts
+/**
+* Canonical state hash of a document: the same function as the server fold's
+* (`packages/ssp-node/src/crdt/hash.rs`), checked against the shared vectors in
+* `packages/ssp-node/tests/fixtures/crdt_state_hash.json`.
+*
+*   stateHash(doc) = hex(SHA-256(utf8(JCS(roots(doc)))))
+*
+* JCS is RFC 8785 (keys in UTF-16 order, `JSON.stringify` strings,
+* `Number#toString` numbers). Loro values map as: integers to numbers,
+* NaN/Infinity to `{"$f64": ...}`, bytes to `{"$bytes": "<base64>"}`, a text
+* to its string (marks are not hashed). Root keys holding `""`, `{}`, `[]` or
+* `0` are left out: touching a root creates it, but a document built from
+* update blobs alone does not have it.
+*/
+async function stateHash(loro, doc) {
+	const bytes = new TextEncoder().encode(canonicalState(loro, doc));
+	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+	return Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** The canonical JSON {@link stateHash} is taken over. */
+function canonicalState(loro, doc) {
+	const roots = Object.create(null);
+	for (const [name, id] of Object.entries(doc.getShallowValue())) {
+		const value = walk(loro, doc.getContainerById(id));
+		if (!isEmptyRoot(value)) roots[name] = value;
+	}
+	return canonicalize(roots);
+}
+function walk(loro, v) {
+	if (!loro.isContainer(v)) return v;
+	const c = v;
+	switch (c.kind()) {
+		case "Map": {
+			const map = c;
+			const out = Object.create(null);
+			for (const k of map.keys()) out[k] = walk(loro, map.get(k));
+			return out;
+		}
+		case "List":
+		case "MovableList": return c.toArray().map((item) => walk(loro, item));
+		case "Text": return c.toString();
+		case "Counter": return c.value;
+		case "Tree": return c.roots().map((n) => walkTreeNode(loro, n));
+		default: throw new Error(`unsupported Loro container ${c.kind()}`);
+	}
+}
+function walkTreeNode(loro, n) {
+	const out = Object.create(null);
+	out.parent = n.parent()?.id ?? null;
+	out.index = n.index();
+	out.meta = walk(loro, n.data);
+	out.id = n.id;
+	out.fractional_index = n.fractionalIndex();
+	out.children = (n.children() ?? []).map((child) => walkTreeNode(loro, child));
+	return out;
 }
-function encodeBase64(bytes) {
-	if (typeof btoa === "function") {
-		let binary = "";
-		for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
-		return btoa(binary);
+function isEmptyRoot(v) {
+	if (v === "" || v === 0) return true;
+	if (Array.isArray(v)) return v.length === 0;
+	if (v && typeof v === "object" && !(v instanceof Uint8Array)) return Object.keys(v).length === 0;
+	return false;
+}
+function canonicalize(v) {
+	if (v === null || v === void 0) return "null";
+	switch (typeof v) {
+		case "boolean": return v ? "true" : "false";
+		case "number":
+			if (!Number.isFinite(v)) return canonicalize({ $f64: String(v) });
+			return Object.is(v, -0) ? "0" : String(v);
+		case "string": return JSON.stringify(v);
+		case "bigint": return canonicalize(Number(v));
+		case "object": {
+			if (v instanceof Uint8Array) return canonicalize({ $bytes: encodeBase64(v) });
+			if (Array.isArray(v)) return "[" + v.map(canonicalize).join(",") + "]";
+			const obj = v;
+			return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k])).join(",") + "}";
+		}
+		default: throw new Error(`unsupported value type ${typeof v}`);
 	}
-	return Buffer.from(bytes).toString("base64");
 }
 
 //#endregion
@@ -12418,319 +12461,559 @@ function loadLoro() {
 
 //#endregion
 //#region src/modules/crdt/index.ts
-/**
-* CrdtManager manages active CrdtField instances and their sync channels.
-*
-* Collaborative state lives in two dedicated tables (defined in
-* `apps/cli/src/meta_tables_remote.surql`):
-*   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
-*   - `_00_cursor` { record_id, session_id, field, state } — one row per
-*                    (record, session, field)
-*
-* Splitting them off the parent row is what makes offline edits mergeable:
-* each (record, field) gets its own row, so concurrent offline writes don't
-* collide on the parent's last-write-wins semantics.
-*
-* Cross-browser delivery still rides the parent table's existing LIVE feed
-* to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
-* (issues 3602, 4026). On every meta UPSERT the writer also bumps the
-* parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
-* feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
-* via subquery. Permission inheritance happens server-side via
-* `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
-*/
+const LOCAL_TABLE = "_00_crdt_local";
+const LOG_SUFFIX = "__crdt_log";
+const PRESENCE_SUFFIX = "__crdt_presence";
+/** Longest a burst of typing waits before its edits go out. */
+const MAX_WAIT_MS = 2e3;
+const PERSIST_DEBOUNCE_MS = 400;
+const PRESENCE_THROTTLE_MS = 250;
+const CLAIM_RETRY_MS = 5e3;
+/** How long an open of a field with nothing local waits for the server's
+*  first answer before handing out the (still empty) document. */
+const FIRST_ANSWER_TIMEOUT_MS = 4e3;
+/** Pause after a fold is noticed before checking the published document. */
+const VERIFY_DELAY_MS = 1e3;
 var CrdtManager = class {
-	fields = /* @__PURE__ */ new Map();
-	liveByTable = /* @__PURE__ */ new Map();
-	pendingLive = /* @__PURE__ */ new Map();
-	staleTables = /* @__PURE__ */ new Set();
-	connectionGeneration = 0;
-	connectionUnsubscribes = [];
+	sessions = /* @__PURE__ */ new Map();
+	opening = /* @__PURE__ */ new Map();
+	ports = null;
 	logger;
-	sessionId = "";
-	constructor(schema, local, remote, logger, debounceMs = 500) {
+	peer = randomPeer();
+	/** The current peer's claim: settled once the database holds it for us. */
+	claim = null;
+	claimRetry = null;
+	connectionUnsubscribes = [];
+	constructor(schema, local, remote, logger, debounceMs = 300) {
 		this.schema = schema;
 		this.local = local;
 		this.remote = remote;
 		this.debounceMs = debounceMs;
 		this.logger = logger.child({ service: "CrdtManager" });
-		this.subscribeToReconnect();
+		this.connectionUnsubscribes.push(this.remote.subscribeConnection("connected", () => {
+			for (const s of this.sessions.values()) this.scheduleFlush(s, 0);
+		}));
+	}
+	/** Hand over the runtime ports. Called once by the client facade. */
+	attach(ports) {
+		this.ports = ports;
 	}
 	/**
-	* Re-establish table LIVEs after a socket drop.
-	*
-	* A LIVE subscription lives and dies with its WebSocket session, and
-	* `ensureTableSubscription` is memoized on `liveByTable` — so without this,
-	* the first reconnect leaves CRDT realtime permanently dead: the map still
-	* holds a uuid for a subscription the server has forgotten, so every later
-	* `open()` short-circuits and no LIVE is ever re-issued.
-	*
-	* Both drop events matter: the SDK publishes `reconnecting` (not
-	* `disconnected`) when it intends to recover on its own, and `disconnected`
-	* only once it has given up.
+	* A new signed-in identity (boot, sign-in, sign-out): edits from here on
+	* belong to it, under a peer it claims. Edits already made stay with the
+	* peer they were made under.
 	*/
-	subscribeToReconnect() {
-		const onDrop = () => {
-			this.connectionGeneration++;
-			for (const table of this.liveByTable.keys()) this.staleTables.add(table);
-			for (const table of this.pendingLive.keys()) this.staleTables.add(table);
-			this.liveByTable.clear();
-		};
-		this.connectionUnsubscribes.push(this.remote.subscribeConnection("reconnecting", onDrop), this.remote.subscribeConnection("disconnected", onDrop), this.remote.subscribeConnection("connected", () => {
-			const tables = Array.from(this.staleTables);
-			this.staleTables.clear();
-			for (const table of tables) {
-				if (!this.hasOpenFieldFor(table)) continue;
-				this.ensureTableSubscription(table);
-			}
-		}));
+	setSessionId(_salt) {
+		this.peer = randomPeer();
+		this.claim = null;
+		for (const s of this.sessions.values()) s.doc.setPeerId(this.peer);
 	}
-	/** Stop observing transport events. Separate from {@link closeAll}, which also
-	*  runs on a bucket switch where the manager keeps being used. */
 	dispose() {
-		for (const off of this.connectionUnsubscribes) try {
+		for (const off of this.connectionUnsubscribes.splice(0)) try {
 			off();
 		} catch {}
-		this.connectionUnsubscribes = [];
-		this.staleTables.clear();
-	}
-	hasOpenFieldFor(table) {
-		const prefix = `${table}:`;
-		return Array.from(this.fields.keys()).some((k) => k.startsWith(prefix));
-	}
-	/** Set the session id that scopes this client's cursor entries. Must be
-	*  called before `open()` for cursors to be pushed under a stable key.
-	*  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
-	*  for the data-module salt). */
-	setSessionId(sessionId) {
-		this.sessionId = sessionId;
+		if (this.claimRetry) clearTimeout(this.claimRetry);
 	}
 	/**
-	* Open a CRDT field for collaborative editing.
+	* Open a collaborative field. Every open of the same field shares one
+	* document; close each open with {@link close}.
 	*
-	* @param table - Table name
-	* @param recordId - Full record ID (e.g., "thread:abc")
-	* @param field - Field name (e.g., "title", "content")
-	* @param fallbackText - Current plain text from the record, used to seed the
-	*                       LoroDoc if no CRDT state exists yet (migration path)
+	* `draft` (from {@link createDraft}) hands over edits made before the record
+	* existed: they are merged in and sent like this tab's own.
 	*/
-	async open(table, recordId, field, fallbackText) {
-		this.assertCrdtField(table, field);
-		const cursorsEnabled = this.fieldHasCursor(table, field);
-		const key = this.makeKey(table, recordId, field);
-		let crdtField = this.fields.get(key);
-		if (crdtField) return crdtField;
-		let initialCrdtState;
-		try {
-			const [result] = await this.local.query(`SELECT VALUE ${field} FROM ONLY $id`, { id: parseRecordIdString(recordId) });
-			const snapshot = this.extractSnapshot(result, cursorsEnabled);
-			if (snapshot) initialCrdtState = snapshot;
-		} catch (e) {
-			this.logger.info({
-				error: String(e),
-				recordId,
-				field,
-				Category: "sp00ky-client::CrdtManager::open"
-			}, "No existing CRDT state found in local cache (continuing with empty doc)");
-		}
-		const { LoroDoc } = await loadLoro();
-		crdtField = new CrdtField(field, cursorsEnabled, LoroDoc, initialCrdtState, this.logger);
-		crdtField.startSync(this.local, this.remote, recordId, this.sessionId, this.debounceMs);
-		this.fields.set(key, crdtField);
-		this.logger.info({
+	async open(table, recordId, field, draft) {
+		const { kind, cursor } = this.fieldSpec(table, field);
+		const key = `${table}|${recordId}|${field}`;
+		let session = this.sessions.get(key);
+		if (session) session.refs++;
+		else {
+			const inFlight = this.opening.get(key);
+			if (inFlight) {
+				session = await inFlight;
+				session.refs++;
+			} else {
+				const pending = this.start(key, table, recordId, field, kind, cursor).finally(() => this.opening.delete(key));
+				this.opening.set(key, pending);
+				session = await pending;
+			}
+		}
+		if (draft) this.adopt(session, draft.getDoc());
+		return session.handle;
+	}
+	/**
+	* A detached document for a field of a record that does not exist yet (a
+	* "new thread" form). Nothing is sent; pass it to {@link open} once the
+	* record is created and its edits become the record's first ones.
+	*/
+	async createDraft(table, field) {
+		const { kind, cursor } = this.fieldSpec(table, field);
+		return new CrdtField(table, "", field, kind, cursor, new (await (loadLoro())).LoroDoc(), { pushPresence: () => {} });
+	}
+	adopt(s, draft) {
+		const peers = [...draft.oplogVersion().toJSON().keys()];
+		if (peers.length === 0) return;
+		this.tryImport(s.doc, draft.export({ mode: "update" }), s.key);
+		for (const peer of peers) s.local.peers[String(peer)] ??= { enqueued: 0 };
+		this.schedulePersist(s);
+		this.scheduleFlush(s, 0);
+	}
+	/** Close one open. The last close of a field resolves once its unsent
+	*  edits are in the outbox (or are left for a later session, offline). */
+	close(table, recordId, field) {
+		const s = this.sessions.get(`${table}|${recordId}|${field}`);
+		if (!s || --s.refs > 0) return Promise.resolve();
+		return this.stop(s, true);
+	}
+	/** Close every field. `flush: false` (a bucket switch) drops unsent edits
+	*  from this session's memory; they stay in the local snapshot of the
+	*  bucket they belong to. */
+	closeAll(options = {}) {
+		for (const s of [...this.sessions.values()]) this.stop(s, options.flush ?? true);
+	}
+	fieldSpec(table, field) {
+		const t = this.schema.tables.find((x) => x.name === table);
+		if (!t) throw new Error(`CrdtManager: unknown table '${table}'`);
+		const col = t.columns[field];
+		if (!col) throw new Error(`CrdtManager: unknown field '${table}.${field}'`);
+		if (!col.crdt) throw new Error(`CrdtManager: '${table}.${field}' is not a CRDT field. Add \`-- @crdt text\` or \`-- @crdt prosemirror\` above its DEFINE FIELD and re-run \`spky generate\`.`);
+		return {
+			kind: col.crdt === "prosemirror" ? "prosemirror" : "text",
+			cursor: !!col.cursor
+		};
+	}
+	async start(key, table, recordId, field, kind, cursor) {
+		if (!this.ports) throw new Error("CrdtManager: not attached to a client");
+		const doc = new (await (loadLoro())).LoroDoc();
+		doc.setPeerId(this.peer);
+		const local = await this.readLocal(recordId, field);
+		if (local.snapshot) this.tryImport(doc, local.snapshot, key);
+		const session = {
+			key,
+			table,
+			recordId,
+			field,
+			kind,
+			cursor,
+			doc,
+			handle: void 0,
+			refs: 1,
+			local,
+			seen: /* @__PURE__ */ new Set(),
+			present: /* @__PURE__ */ new Set(),
+			verifiedRev: 0,
+			verifyTimer: null,
+			disposers: [],
+			flushTimer: null,
+			firstDirtyAt: 0,
+			persistTimer: null,
+			flushing: null,
+			refetching: false,
+			presenceTimer: null,
+			presencePending: null,
+			presenceSent: false,
+			ingesting: Promise.resolve()
+		};
+		session.handle = new CrdtField(table, recordId, field, kind, cursor, doc, { pushPresence: (state) => this.pushPresence(session, state) });
+		this.sessions.set(key, session);
+		this.ensureClaimed();
+		if (!local.snapshot) await this.refetchCanonical(session);
+		session.disposers.push(doc.subscribeLocalUpdates(() => {
+			session.local.peers[this.peer] ??= { enqueued: 0 };
+			this.scheduleFlush(session);
+			this.schedulePersist(session);
+		}));
+		const ports = this.ports;
+		const log = await ports.watch(`${table}${LOG_SUFFIX}`, {
+			doc: recordId,
+			field
+		}, (rows) => {
+			session.ingesting = session.ingesting.then(() => this.ingest(session, rows));
+		});
+		session.disposers.push(log.stop);
+		if (cursor) {
+			const presence = await ports.watch(`${table}${PRESENCE_SUFFIX}`, {
+				doc: recordId,
+				field
+			}, (rows) => this.ingestPresence(session, rows));
+			session.disposers.push(presence.stop);
+		}
+		if (!session.handle.hasContent()) await Promise.race([log.settled, delay(FIRST_ANSWER_TIMEOUT_MS)]);
+		await session.ingesting;
+		this.scheduleFlush(session, 0);
+		this.logger.debug({
 			key,
-			hasInitialState: !!initialCrdtState,
-			hasFallback: !!fallbackText,
+			peer: this.peer,
 			Category: "sp00ky-client::CrdtManager::open"
-		}, "CrdtField opened");
-		this.ensureTableSubscription(table);
-		if (!initialCrdtState) this.fetchAndDispatchRow(table, recordId);
-		return crdtField;
+		}, "CRDT field opened");
+		return session;
 	}
-	close(table, recordId, field) {
-		const key = this.makeKey(table, recordId, field);
-		const crdtField = this.fields.get(key);
-		if (crdtField) {
-			crdtField.stopSync();
-			this.fields.delete(key);
+	async stop(s, flush) {
+		this.sessions.delete(s.key);
+		for (const off of s.disposers.splice(0)) try {
+			off();
+		} catch {}
+		if (s.flushTimer) clearTimeout(s.flushTimer);
+		if (s.persistTimer) clearTimeout(s.persistTimer);
+		if (s.presenceTimer) clearTimeout(s.presenceTimer);
+		if (s.verifyTimer) clearTimeout(s.verifyTimer);
+		if (s.presenceSent) this.dropPresence(s);
+		if (flush) {
+			await this.persist(s);
+			await this.flush(s);
+		}
+	}
+	async ingest(s, rows) {
+		const loro = await loadLoro();
+		const ids = new Set(rows.map((row) => String(row.id ?? "")));
+		for (const id of s.present) if (!ids.has(id)) {
+			this.scheduleVerify(s);
+			break;
+		}
+		s.present = ids;
+		const blobs = [];
+		for (const row of rows) {
+			const id = String(row.id ?? "");
+			if (!id || s.seen.has(id)) continue;
+			s.seen.add(id);
+			const blob = asBytes(row.data);
+			const verdict = check(loro, blob, row.peer == null ? void 0 : String(row.peer));
+			if (!verdict.ok) {
+				this.logger.debug({
+					row: id,
+					reason: verdict.reason,
+					Category: "sp00ky-client::CrdtManager::ingest"
+				}, "CRDT log row refused");
+				continue;
+			}
+			blobs.push(blob);
 		}
-		if (!this.hasOpenFieldFor(table)) {
-			this.killTableSubscription(table);
-			this.staleTables.delete(table);
+		if (blobs.length === 0) return;
+		let pending = false;
+		for (const blob of blobs) if (this.tryImport(s.doc, blob, s.key)?.pending) pending = true;
+		this.schedulePersist(s);
+		if (pending) this.refetchCanonical(s);
+	}
+	tryImport(doc, blob, key) {
+		try {
+			const status = doc.import(blob);
+			return { pending: !!status.pending && status.pending.size > 0 };
+		} catch (e) {
+			this.logger.warn({
+				key,
+				error: String(e),
+				Category: "sp00ky-client::CrdtManager::import"
+			}, "CRDT import failed");
+			return null;
 		}
-		this.logger.debug({
-			key,
-			Category: "sp00ky-client::CrdtManager::close"
-		}, "CrdtField closed");
+	}
+	async refetchCanonical(s) {
+		if (s.refetching) return;
+		s.refetching = true;
+		try {
+			const [row] = await this.remote.query("SELECT rev, snapshot FROM ONLY type::record('_00_crdt_doc', [type::record($doc), $field])", {
+				doc: s.recordId,
+				field: s.field
+			});
+			const snapshot = asBytes(row?.snapshot);
+			if (snapshot) {
+				this.tryImport(s.doc, snapshot, s.key);
+				s.local.rev = Math.max(s.local.rev, row?.rev ?? 0);
+				this.schedulePersist(s);
+			}
+		} catch (e) {
+			this.logger.debug({
+				key: s.key,
+				error: String(e),
+				Category: "sp00ky-client::CrdtManager::refetch"
+			}, "No canonical CRDT document fetched");
+		} finally {
+			s.refetching = false;
+		}
+	}
+	scheduleVerify(s) {
+		if (s.verifyTimer) clearTimeout(s.verifyTimer);
+		s.verifyTimer = setTimeout(() => {
+			s.verifyTimer = null;
+			this.verify(s);
+		}, VERIFY_DELAY_MS);
 	}
 	/**
-	* Close every open field + table LIVE. Fields flush a final remote push by
-	* default; pass `{ flush: false }` on a bucket switch, where that flush
-	* would push the previous user's snapshot under the next user's session.
+	* After a fold: compare this device's document with the one the server
+	* published, at the version the server published. Missing ops (rows this
+	* device never got before they were folded away) are repaired by merging
+	* the published snapshot in. The same ops giving a different state cannot
+	* be merged away; that is logged.
 	*/
-	closeAll(options = {}) {
-		for (const [_, field] of this.fields) field.stopSync(options);
-		this.fields.clear();
-		for (const table of Array.from(this.liveByTable.keys())) this.killTableSubscription(table);
-		this.staleTables.clear();
-	}
-	/** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
-	*  every open CrdtField on `table`. */
-	async ensureTableSubscription(table) {
-		if (this.liveByTable.has(table)) return;
-		const generation = this.connectionGeneration;
-		const pending = this.pendingLive.get(table);
-		if (pending) {
-			if (pending.generation === generation) return pending.promise;
-			await pending.promise.catch(() => {});
-			if (this.liveByTable.has(table)) return;
-			if (generation !== this.connectionGeneration) return;
-			const successor = this.pendingLive.get(table);
-			if (successor && successor.generation === generation) return successor.promise;
-		}
-		const start = (async () => {
+	async verify(s) {
+		let row;
+		try {
+			[row] = await this.remote.query("SELECT rev, upto, state_hash FROM ONLY type::record('_00_crdt_doc', [type::record($doc), $field])", {
+				doc: s.recordId,
+				field: s.field
+			});
+		} catch {
+			return;
+		}
+		const rev = row?.rev ?? 0;
+		const frontiers = row?.upto?.frontiers;
+		if (!row?.state_hash || !frontiers || !row.upto?.vv || rev <= s.verifiedRev || !this.sessions.has(s.key)) return;
+		const have = s.doc.oplogVersion().toJSON();
+		if (Object.entries(row.upto.vv).some(([peer, end]) => (have.get(peer) ?? 0) < end)) {
+			this.logger.info({
+				key: s.key,
+				rev,
+				Category: "sp00ky-client::CrdtManager::verify"
+			}, "CRDT document behind the published one; merging it in");
+			await this.refetchCanonical(s);
+			return;
+		}
+		s.verifiedRev = rev;
+		if (!globalThis.crypto?.subtle) return;
+		const loro = await loadLoro();
+		let fork;
+		try {
+			fork = s.doc.forkAt(frontiers);
+			const hash = await stateHash(loro, fork);
+			if (hash !== row.state_hash) this.logger.warn({
+				key: s.key,
+				rev,
+				hash,
+				published: row.state_hash,
+				Category: "sp00ky-client::CrdtManager::verify"
+			}, "CRDT document differs from the published one at the same version");
+		} catch (e) {
+			this.logger.debug({
+				key: s.key,
+				error: String(e),
+				Category: "sp00ky-client::CrdtManager::verify"
+			}, "CRDT document check failed");
+		} finally {
+			fork?.free();
+		}
+	}
+	scheduleFlush(s, delay = this.debounceMs) {
+		const now = Date.now();
+		if (!s.flushTimer) s.firstDirtyAt = now;
+		else clearTimeout(s.flushTimer);
+		const wait = Math.max(0, Math.min(delay, s.firstDirtyAt + MAX_WAIT_MS - now));
+		s.flushTimer = setTimeout(() => {
+			s.flushTimer = null;
+			this.flush(s);
+		}, wait);
+	}
+	async flush(s) {
+		if (s.flushing) return s.flushing;
+		s.flushing = this.sendOwnEdits(s).finally(() => {
+			s.flushing = null;
+		});
+		return s.flushing;
+	}
+	/** Send every own peer's ops that are not in the outbox yet, one row per
+	*  peer. Only the peer's own ops travel (`updates-in-range`): a plain
+	*  `from: version` export would carry ops imported from others too, and
+	*  the acceptance rule refuses such a row. */
+	async sendOwnEdits(s) {
+		const vv = s.doc.oplogVersion();
+		const due = [...new Set([...Object.keys(s.local.peers), this.peer])].map((peer) => ({
+			peer,
+			end: vv.get(peer) ?? 0,
+			from: s.local.peers[peer]?.enqueued ?? 0
+		})).filter((p) => p.end > p.from);
+		if (due.length === 0 || !this.ports) return;
+		if (!await this.ensureClaimed()) {
+			this.retryLater(s);
+			return;
+		}
+		for (const { peer, end, from } of due) {
+			if (peer !== this.peer && !await this.claimPeer(peer)) continue;
+			const data = s.doc.export({
+				mode: "updates-in-range",
+				spans: [{
+					id: {
+						peer,
+						counter: from
+					},
+					len: end - from
+				}]
+			});
 			try {
-				const [uuid] = await this.remote.query(`LIVE SELECT * FROM ${table}`);
-				if (generation !== this.connectionGeneration) {
-					this.logger.debug({
-						table,
-						Category: "sp00ky-client::CrdtManager::ensureTableSubscription"
-					}, "Socket dropped while registering LIVE; discarding it");
-					return;
-				}
-				(await this.remote.getClient().liveOf(uuid)).subscribe((message) => {
-					if (message.action === "KILLED") return;
-					if (message.action !== "CREATE" && message.action !== "UPDATE") return;
-					this.dispatchRow(table, message.value);
+				await this.ports.create(`${s.table}${LOG_SUFFIX}:${rowKey()}`, {
+					doc: s.recordId,
+					field: s.field,
+					peer,
+					data
 				});
-				if (generation !== this.connectionGeneration) return;
-				this.liveByTable.set(table, uuid);
-				this.logger.info({
-					table,
-					Category: "sp00ky-client::CrdtManager::ensureTableSubscription"
-				}, "LIVE SELECT started");
 			} catch (e) {
 				this.logger.warn({
-					error: e,
-					table,
-					Category: "sp00ky-client::CrdtManager::ensureTableSubscription"
-				}, "Failed to start LIVE SELECT");
+					key: s.key,
+					error: String(e),
+					Category: "sp00ky-client::CrdtManager::flush"
+				}, "Queueing CRDT edits failed");
+				this.retryLater(s);
+				return;
 			}
-		})();
-		this.pendingLive.set(table, {
-			promise: start,
-			generation
-		});
+			s.local.peers[peer] = { enqueued: end };
+		}
+		await this.persist(s);
+	}
+	retryLater(s) {
+		if (this.sessions.get(s.key) === s) this.scheduleFlush(s, CLAIM_RETRY_MS);
+	}
+	/** Claim this session's peer once; a failure (offline, signed out) is retried. */
+	ensureClaimed() {
+		if (!this.claim) {
+			const peer = this.peer;
+			this.claim = this.claimPeer(peer).then((ok) => {
+				if (!ok && this.peer === peer) this.claim = null;
+				return ok;
+			});
+		}
+		return this.claim;
+	}
+	async claimPeer(peer) {
 		try {
-			await start;
-		} finally {
-			this.pendingLive.delete(table);
-		}
-	}
-	/** Apply a parent-row payload from a non-LIVE source (e.g. the
-	*  list_ref-driven sync engine, when the cross-user LIVE on the
-	*  parent table is filtered out by the SurrealDB cross-session
-	*  permission gap). Same semantics as the internal `dispatchRow`. */
-	applyRow(table, row) {
-		this.dispatchRow(table, row);
-	}
-	/** Dispatch a parent-row LIVE event to every open CrdtField on that
-	*  record. Each open field reads its slice of the row directly — the
-	*  CRDT snapshot is a column on the parent now, so there is no
-	*  follow-up subquery. */
-	dispatchRow(table, row) {
-		const id = row.id != null ? String(row.id) : "";
-		if (!id) return;
-		const rowKeyPrefix = `${table}:${id}:`;
-		for (const [key, crdtField] of this.fields) {
-			if (!key.startsWith(rowKeyPrefix)) continue;
-			const fieldName = key.slice(rowKeyPrefix.length);
-			const cursorsEnabled = this.fieldHasCursor(table, fieldName);
-			const slice = row[fieldName];
-			const snapshot = this.extractSnapshot(slice, cursorsEnabled);
-			if (snapshot) crdtField.importRemote(snapshot);
-			if (cursorsEnabled && slice && typeof slice === "object") {
-				const cursors = slice.cursors;
-				if (cursors && typeof cursors === "object") for (const [sid, blob] of Object.entries(cursors)) {
-					if (sid === this.sessionId) continue;
-					if (typeof blob === "string" && blob.length > 0) crdtField.importRemoteCursor(blob);
-				}
+			const [created] = await this.remote.query("CREATE type::record('_00_crdt_peer', $peer) RETURN id", { peer });
+			return Array.isArray(created) && created.length > 0;
+		} catch (e) {
+			if (!/already exists/i.test(String(e))) return false;
+			try {
+				const [owner] = await this.remote.query("SELECT VALUE author FROM ONLY type::record('_00_crdt_peer', $peer)", { peer });
+				if (owner != null) return true;
+			} catch {
+				return false;
 			}
+			this.logger.error({
+				peer,
+				Category: "sp00ky-client::CrdtManager::claim"
+			}, "CRDT peer id taken by another user");
+			if (peer === this.peer) this.setSessionId("");
+			return false;
 		}
 	}
-	/** One-shot remote fetch for a row whose CRDT field hasn't synced
-	*  locally yet (fresh device, memory-backed local DB after reload, …).
-	*  Used by `open()` when the local read came up empty. Subsequent
-	*  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
-	async fetchAndDispatchRow(table, id) {
+	localId(recordId, field) {
+		return new RecordId$1(LOCAL_TABLE, `${recordId}|${field}`);
+	}
+	async readLocal(recordId, field) {
 		try {
-			const recordId = parseRecordIdString(id);
-			const [row] = await this.remote.query(`SELECT * FROM ONLY $id`, { id: recordId });
-			if (!row || typeof row !== "object") return;
-			this.dispatchRow(table, row);
+			const row = await this.local.getById(LOCAL_TABLE, this.localId(recordId, field));
+			if (row) return {
+				snapshot: asBytes(row.snapshot),
+				rev: Number(row.rev ?? 0),
+				peers: row.peers ?? {}
+			};
 		} catch (e) {
-			this.logger.warn({
-				error: e,
-				table,
-				id,
-				Category: "sp00ky-client::CrdtManager::fetchAndDispatchRow"
-			}, "Failed to fetch parent row for CRDT hydration");
-		}
-	}
-	/** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
-	*  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
-	fieldHasCursor(table, field) {
-		return !!this.schema.tables.find((t) => t.name === table)?.columns[field]?.cursor;
-	}
-	/** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
-	*  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
-	*  `{ state, cursors }` where `state` carries the snapshot bytes. */
-	extractSnapshot(value, cursorsEnabled) {
-		const asBytes = (v) => {
-			if (v instanceof Uint8Array) return v.length > 0 ? v : void 0;
-			if (v instanceof ArrayBuffer) return new Uint8Array(v);
-			if (ArrayBuffer.isView(v)) {
-				const view = v;
-				return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
-			}
-			if (Array.isArray(v) && v.length > 0 && v.every((n) => typeof n === "number")) return Uint8Array.from(v);
-		};
-		if (cursorsEnabled) {
-			if (value && typeof value === "object" && !(value instanceof Uint8Array)) return asBytes(value.state);
-			return;
+			this.logger.debug({
+				error: String(e),
+				Category: "sp00ky-client::CrdtManager::readLocal"
+			}, "No local CRDT state");
 		}
-		return asBytes(value);
+		return {
+			rev: 0,
+			peers: {}
+		};
 	}
-	killTableSubscription(table) {
-		const uuid = this.liveByTable.get(table);
-		if (uuid) {
-			this.remote.query("KILL $uuid", { uuid }).catch((err) => {
-				this.logger.debug({
-					err,
-					table,
-					Category: "sp00ky-client::CrdtManager::killTableSubscription"
-				}, "KILL of table LIVE failed (already closed?)");
+	schedulePersist(s) {
+		if (s.persistTimer) return;
+		s.persistTimer = setTimeout(() => {
+			s.persistTimer = null;
+			this.persist(s);
+		}, PERSIST_DEBOUNCE_MS);
+	}
+	/** Save the merged document. Another tab may have saved too: merge with
+	*  its snapshot rather than overwrite it, and keep the further of the two
+	*  outbox marks per peer. */
+	async persist(s) {
+		try {
+			const stored = await this.readLocal(s.recordId, s.field);
+			if (stored.snapshot) this.tryImport(s.doc, stored.snapshot, s.key);
+			for (const [peer, mark] of Object.entries(stored.peers)) {
+				const mine = s.local.peers[peer]?.enqueued ?? 0;
+				if (mark.enqueued > mine) s.local.peers[peer] = { enqueued: mark.enqueued };
+			}
+			s.local.rev = Math.max(s.local.rev, stored.rev);
+			s.local.snapshot = s.doc.export({ mode: "snapshot" });
+			await this.local.upsert(LOCAL_TABLE, this.localId(s.recordId, s.field), {
+				doc: s.recordId,
+				field: s.field,
+				snapshot: s.local.snapshot,
+				rev: s.local.rev,
+				peers: s.local.peers
+			}, "replace");
+		} catch (e) {
+			this.logger.debug({
+				key: s.key,
+				error: String(e),
+				Category: "sp00ky-client::CrdtManager::persist"
+			}, "Saving local CRDT state failed");
+		}
+	}
+	pushPresence(s, state) {
+		s.presencePending = state;
+		if (s.presenceTimer) return;
+		s.presenceTimer = setTimeout(() => {
+			s.presenceTimer = null;
+			const data = s.presencePending;
+			s.presencePending = null;
+			if (data) this.sendPresence(s, data);
+		}, PRESENCE_THROTTLE_MS);
+	}
+	/** Presence is the latest state only: no outbox, no offline queue. */
+	async sendPresence(s, state) {
+		if (!await this.ensureClaimed()) return;
+		try {
+			await this.remote.query(`UPSERT type::record($table, $key) SET doc = type::record($doc), field = $field, session = $sid, state = $state RETURN NONE`, {
+				table: `${s.table}${PRESENCE_SUFFIX}`,
+				key: presenceKey(this.peer, s.field, s.recordId),
+				doc: s.recordId,
+				field: s.field,
+				sid: this.peer,
+				state
 			});
-			this.liveByTable.delete(table);
+			s.presenceSent = true;
+		} catch (e) {
+			this.logger.debug({
+				key: s.key,
+				error: String(e),
+				Category: "sp00ky-client::CrdtManager::presence"
+			}, "Presence update failed");
 		}
 	}
-	makeKey(table, recordId, field) {
-		return `${table}:${recordId}:${field}`;
+	/** Remove this session's cursor when the field closes; the server's TTL
+	*  sweep covers a tab that never gets here. */
+	async dropPresence(s) {
+		try {
+			await this.remote.query(`DELETE type::record($table, $key) RETURN NONE`, {
+				table: `${s.table}${PRESENCE_SUFFIX}`,
+				key: presenceKey(this.peer, s.field, s.recordId)
+			});
+		} catch (e) {
+			this.logger.debug({
+				key: s.key,
+				error: String(e),
+				Category: "sp00ky-client::CrdtManager::presence"
+			}, "Presence removal failed");
+		}
 	}
-	/**
-	* Throws if `<table>.<field>` is not annotated `@crdt` in the schema. Catches
-	* typos, removed annotations, and stale schema codegen at the call site instead
-	* of silently producing a non-CRDT writer.
-	*/
-	assertCrdtField(table, field) {
-		if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) throw new Error(`openCrdtField: refusing unsafe field identifier '${field}' — must match [a-zA-Z_][a-zA-Z0-9_]*`);
-		const tableSchema = this.schema.tables.find((t) => t.name === table);
-		if (!tableSchema) throw new Error(`openCrdtField: unknown table '${table}'. Available: ${this.schema.tables.map((t) => t.name).join(", ")}`);
-		const column = tableSchema.columns[field];
-		if (!column) throw new Error(`openCrdtField: '${table}.${field}' is not in the schema. Available fields: ${Object.keys(tableSchema.columns).join(", ")}`);
-		if (!column.crdt) throw new Error(`openCrdtField: '${table}.${field}' is not annotated '@crdt' in the schema. Add '-- @crdt text' above the field's DEFINE FIELD and regenerate the client schema.`);
+	ingestPresence(s, rows) {
+		for (const row of rows) {
+			if (String(row.session ?? "") === this.peer) continue;
+			const state = asBytes(row.state);
+			if (state) s.handle.deliverPresence(state);
+		}
 	}
 };
+/** `p<session>_<field>_<record key>`, letters, digits and `_` only. */
+function presenceKey(session, field, recordId) {
+	return `p${session}_${field}_${recordId.slice(recordId.indexOf(":") + 1).replace(/[^A-Za-z0-9_]/g, "_")}`;
+}
+function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function rowKey() {
+	const bytes = new Uint8Array(12);
+	crypto.getRandomValues(bytes);
+	return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
 
 //#endregion
 //#region src/services/persistence/localstorage.ts
@@ -14952,7 +15235,7 @@ function createServices(config) {
 	streamProcessor.configureCircuitPersistence(config.persistCircuit ?? config.localEngine === "sqlite", config.circuitCheckpointMs);
 	streamProcessor.configureProjection(config.circuitProjection ?? true);
 	const migrator = new LocalMigrator(local, logger);
-	const crdt = new CrdtManager(config.schema, local, remote, logger, config.crdtDebounceMs ?? 500);
+	const crdt = new CrdtManager(config.schema, local, remote, logger, config.crdtDebounceMs ?? 300);
 	const auth = new AuthService(config.schema, remote, persistence, logger);
 	const tabId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `tab_${Math.random().toString(36).slice(2)}`;
 	return {
@@ -14978,7 +15261,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.323",
+			coreVersion: "0.0.1-canary.325",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -15649,6 +15932,28 @@ var Sp00kyClient = class {
 			subscribe: (hash, cb, options) => this.runtime.subscribe(hash, cb, options)
 		};
 		const remoteRegisterPort = { enqueueDownEvent: () => void this.runtime.dispatch({ type: "EnsureRegistered" }) };
+		s.crdt.attach({
+			watch: async (table, where, onRows) => {
+				const { hash } = await this.query(table, {}).where(where).build().run();
+				const stopRows = this.runtime.subscribe(hash, onRows, { immediate: true });
+				let known = false;
+				let idle = false;
+				let done;
+				const settled = new Promise((resolve) => done = resolve);
+				const check = () => known && idle && done();
+				const stopAuthority = this.runtime.subscribeAuthority(hash, (k) => (known = k, check()), { immediate: true });
+				const stopStatus = this.runtime.subscribeStatus(hash, (st) => (idle = st === "idle", check()), { immediate: true });
+				return {
+					stop: () => {
+						stopRows();
+						stopAuthority();
+						stopStatus();
+					},
+					settled
+				};
+			},
+			create: (id, data) => this.create(id, data)
+		});
 		this.featureFlags = new FeatureFlagModule({
 			dataModule: liveQueryPort,
 			sync: remoteRegisterPort,
@@ -16051,11 +16356,20 @@ var Sp00kyClient = class {
 	appRelease(app, options) {
 		return this.appReleases.release(app, options);
 	}
-	async openCrdtField(table, recordId, field, fallbackText) {
-		return this.services.crdt.open(table, recordId, field, fallbackText);
+	/** Open a `@crdt` field for editing. `draft` (from {@link createCrdtDraft})
+	*  hands over edits made before the record existed. */
+	async openCrdtField(table, recordId, field, draft) {
+		return this.services.crdt.open(table, recordId, field, draft);
+	}
+	/** A detached `@crdt` document for a record not created yet; see
+	*  {@link openCrdtField}. */
+	async createCrdtDraft(table, field) {
+		return this.services.crdt.createDraft(table, field);
 	}
+	/** Close a `@crdt` field. The last close resolves once its unsent edits
+	*  are queued in the outbox. */
 	closeCrdtField(table, recordId, field) {
-		this.services.crdt.close(table, recordId, field);
+		return this.services.crdt.close(table, recordId, field);
 	}
 	bucket(name) {
 		return new BucketHandle(name, this.services.remote, this.services.blobs, {