@spooky-sync/core 0.0.1-canary.355 → 0.0.1-canary.357

package/dist/index.js

@@ -1333,6 +1333,1347 @@ var WebPushModule = class {
 	}
 };
 
+//#endregion
+//#region src/modules/channel/index.ts
+const compareHlc = (a, b) => a[0] - b[0] || a[1] - b[1] || (a[2] < b[2] ? -1 : a[2] > b[2] ? 1 : 0);
+const peerKey = (p) => `${p.user}#${p.peer}`;
+const isRecordIdLike = (v) => v instanceof RecordId$1 || v !== null && typeof v === "object" && v.constructor?.name === "RecordId";
+/** `table:id` for a record id in any spelling, or null. */
+function idKey(v) {
+	if (typeof v === "string") return v.includes(":") ? v : null;
+	if (isRecordIdLike(v)) return encodeRecordId(v);
+	if (v !== null && typeof v === "object" && "table" in v && "id" in v) {
+		const t = v.table;
+		const name = typeof t === "string" ? t : t?.name;
+		if (typeof name === "string") return `${name}:${String(v.id)}`;
+	}
+	return null;
+}
+const toBase64 = (bytes) => {
+	let s = "";
+	for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+	return btoa(s);
+};
+const fromBase64 = (b64) => {
+	const s = atob(b64);
+	const out = new Uint8Array(s.length);
+	for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+	return out;
+};
+/** JSON-safe form of a field value: record ids, dates and bytes are tagged. */
+function encodeValue(v) {
+	if (v === void 0) return null;
+	if (isRecordIdLike(v)) return { $rid: encodeRecordId(v) };
+	if (v instanceof Date) return { $date: v.toISOString() };
+	if (v instanceof Uint8Array) return { $bytes: toBase64(v) };
+	if (v instanceof ArrayBuffer) return { $bytes: toBase64(new Uint8Array(v)) };
+	if (Array.isArray(v)) return v.map(encodeValue);
+	if (v !== null && typeof v === "object") {
+		const out = {};
+		for (const [k, x] of Object.entries(v)) out[k] = encodeValue(x);
+		return out;
+	}
+	return v;
+}
+function decodeValue(v) {
+	if (Array.isArray(v)) return v.map(decodeValue);
+	if (v === null || typeof v !== "object") return v;
+	const o = v;
+	if (Object.keys(o).length === 1) {
+		if (typeof o.$rid === "string") return parseRecordIdString(o.$rid);
+		if (typeof o.$date === "string") return new Date(o.$date);
+		if (typeof o.$bytes === "string") return fromBase64(o.$bytes);
+	}
+	const out = {};
+	for (const [k, x] of Object.entries(o)) out[k] = decodeValue(x);
+	return out;
+}
+const sameValue = (a, b) => a === b || JSON.stringify(encodeValue(a)) === JSON.stringify(encodeValue(b));
+/** A well-formed `op` message, or null. */
+function parseMessage(raw) {
+	if (raw === null || typeof raw !== "object") return null;
+	const m = raw;
+	const hlc = m.hlc;
+	if (m.kind !== void 0 && m.kind !== "update" && m.kind !== "create" && m.kind !== "delete") return null;
+	if (m.t !== "op" || typeof m.table !== "string" || typeof m.id !== "string" || m.patch === null || typeof m.patch !== "object" || Array.isArray(m.patch) || !Array.isArray(hlc) || hlc.length !== 3 || typeof hlc[0] !== "number" || typeof hlc[1] !== "number" || typeof hlc[2] !== "string") return null;
+	return m;
+}
+/** Whether a decoded value fits a column, loosely (the shapes the client itself writes). */
+function fitsColumn(col, v) {
+	if (v === null || v === void 0) return col.optional;
+	if (col.array) return Array.isArray(v) && v.every((x) => fitsScalar(col, x));
+	return fitsScalar(col, v);
+}
+function fitsScalar(col, v) {
+	if (col.recordId) return typeof v === "string" || isRecordIdLike(v);
+	if (col.dateTime) return v instanceof Date || typeof v === "string";
+	switch (col.type) {
+		case "string": return typeof v === "string";
+		case "number": return typeof v === "number" && Number.isFinite(v);
+		case "boolean": return typeof v === "boolean";
+		case "Uint8Array": return v instanceof Uint8Array;
+		case "null": return v === null;
+		default: return true;
+	}
+}
+/** Why a peer patch is refused against the table's columns, or null when it fits. */
+function checkPatch(columns, patch, allowEmpty = false) {
+	const fields = Object.keys(patch);
+	if (fields.length === 0 && !allowEmpty) return "empty patch";
+	for (const field of fields) {
+		if (field === "id") return "patches the id";
+		const col = columns[field];
+		if (!col) return `unknown field '${field}'`;
+		if (col.crdt) return `'${field}' is a @crdt field`;
+		if (!fitsColumn(col, patch[field])) return `'${field}' does not fit its column type`;
+	}
+	return null;
+}
+/** A patch split into the fields the database gets and the ones only peers get. */
+function splitPatch(columns, data) {
+	let ephemeral = null;
+	const persistent = {};
+	for (const [k, v] of Object.entries(data)) if (columns[k]?.ephemeral) (ephemeral ??= {})[k] = v;
+	else persistent[k] = v;
+	return {
+		persistent,
+		ephemeral
+	};
+}
+const OVERLAY_DEPTH = 4;
+/**
+* Rows with the overlay folded in, nested related rows included. Untouched
+* rows (and the array itself, when nothing changed) keep their identity.
+*/
+function applyOverlay(rows, overlay) {
+	if (overlay.size === 0) return rows;
+	return foldArray(rows, overlay, 0);
+}
+function foldArray(arr, overlay, depth) {
+	let changed = false;
+	const next = arr.map((x) => {
+		const y = foldValue(x, overlay, depth);
+		if (y !== x) changed = true;
+		return y;
+	});
+	return changed ? next : arr;
+}
+function foldValue(v, overlay, depth) {
+	if (depth > OVERLAY_DEPTH || v === null || typeof v !== "object") return v;
+	if (Array.isArray(v)) return foldArray(v, overlay, depth + 1);
+	if (isRecordIdLike(v) || v instanceof Date || v instanceof Uint8Array) return v;
+	const row = v;
+	let next = null;
+	for (const [k, x] of Object.entries(row)) {
+		if (k === "id") continue;
+		const y = foldValue(x, overlay, depth + 1);
+		if (y !== x) (next ??= { ...row })[k] = y;
+	}
+	const key = "id" in row ? idKey(row.id) : null;
+	const fields = key ? overlay.get(key) : void 0;
+	if (fields) {
+		for (const [field, entry] of fields) if (!sameValue(row[field], entry.value)) (next ??= { ...row })[field] = entry.value;
+	}
+	return next ?? row;
+}
+/** Every record id in rows, nested related rows included. */
+function collectIds(rows, into = /* @__PURE__ */ new Set(), depth = 0) {
+	if (depth > OVERLAY_DEPTH) return into;
+	for (const v of rows) {
+		if (v === null || typeof v !== "object") continue;
+		if (Array.isArray(v)) {
+			collectIds(v, into, depth + 1);
+			continue;
+		}
+		if (isRecordIdLike(v) || v instanceof Date || v instanceof Uint8Array) continue;
+		const row = v;
+		const key = "id" in row ? idKey(row.id) : null;
+		if (key) into.add(key);
+		for (const [k, x] of Object.entries(row)) if (k !== "id" && x !== null && typeof x === "object") collectIds([x], into, depth + 1);
+	}
+	return into;
+}
+/** Normalized peer ids, without `self`. */
+function peerUsers(peers, self) {
+	const out = /* @__PURE__ */ new Set();
+	for (const p of peers) {
+		const key = idKey(p);
+		if (key && key !== self) out.add(key);
+	}
+	return out;
+}
+const OPS = {
+	"=": (a, b) => sameKey(a, b),
+	"==": (a, b) => sameKey(a, b),
+	"!=": (a, b) => !sameKey(a, b),
+	">": (a, b) => order(a, b) > 0,
+	">=": (a, b) => order(a, b) >= 0,
+	"<": (a, b) => order(a, b) < 0,
+	"<=": (a, b) => order(a, b) <= 0,
+	IN: (a, b) => Array.isArray(b) && b.some((x) => sameKey(a, x)),
+	INSIDE: (a, b) => Array.isArray(b) && b.some((x) => sameKey(a, x)),
+	"∈": (a, b) => Array.isArray(b) && b.some((x) => sameKey(a, x)),
+	"NOT IN": (a, b) => !(Array.isArray(b) && b.some((x) => sameKey(a, x))),
+	NOTINSIDE: (a, b) => !(Array.isArray(b) && b.some((x) => sameKey(a, x))),
+	"∉": (a, b) => !(Array.isArray(b) && b.some((x) => sameKey(a, x))),
+	CONTAINS: (a, b) => Array.isArray(a) && a.some((x) => sameKey(x, b)),
+	"∋": (a, b) => Array.isArray(a) && a.some((x) => sameKey(x, b)),
+	CONTAINSNOT: (a, b) => !(Array.isArray(a) && a.some((x) => sameKey(x, b))),
+	"∌": (a, b) => !(Array.isArray(a) && a.some((x) => sameKey(x, b)))
+};
+/** A comparable form: record ids by `table:id` (in any spelling), dates by ms. */
+function keyOf(v) {
+	if (v === void 0) return null;
+	if (isRecordIdLike(v)) return idKey(v);
+	if (v instanceof Date) return v.getTime();
+	return v;
+}
+function sameKey(a, b) {
+	const x = isRecordIdLike(a) || isRecordIdLike(b) ? keyOfId(a) : keyOf(a);
+	const y = isRecordIdLike(a) || isRecordIdLike(b) ? keyOfId(b) : keyOf(b);
+	if (x === y) return true;
+	return x !== null && y !== null && typeof x === "object" && typeof y === "object" && sameValue(x, y);
+}
+/** A record id compared against a string spelling of one. */
+function keyOfId(v) {
+	return typeof v === "string" ? v : keyOf(v);
+}
+function order(a, b) {
+	const x = keyOf(a);
+	const y = keyOf(b);
+	if (x === null || y === null || typeof x !== typeof y) return NaN;
+	return x < y ? -1 : x > y ? 1 : 0;
+}
+function pathValue(row, path) {
+	let v = row;
+	for (const part of path.split(".")) {
+		if (v === null || typeof v !== "object") return void 0;
+		v = v[part];
+	}
+	return v;
+}
+function matchesComparison(c, row) {
+	const field = pathValue(row, c.field);
+	const op = OPS[c.op];
+	return c.swap ? op(c.value, field) : op(field, c.value);
+}
+/** Whether `row` passes a query's `where` (a conjunction of comparisons and `_or` groups). */
+function matchesWhere(where, row) {
+	return where.every((node) => "or" in node ? node.or.some((c) => matchesComparison(c, row)) : matchesComparison(node, row));
+}
+/**
+* The parts of a channel query that do nothing there (a channel only reads
+* the `where`). Not an error, worth a warning unless `.ignoreUnusedArgs()`.
+*/
+function unusedArgs(plan, isOne = false) {
+	const out = [];
+	if (isOne) out.push(".one()");
+	if (plan.orderBy && plan.orderBy.length > 0) out.push("orderBy");
+	if (plan.limit !== void 0 && !(isOne && plan.limit === 1)) out.push("limit");
+	if (plan.offset !== void 0) out.push("offset");
+	if (plan.select && plan.select.length > 0) out.push("select");
+	return out;
+}
+/**
+* A query plan as a channel scope, or an error saying why it cannot be one:
+* the table must be `@channel`, and the filter must be decidable from the
+* row alone (its own fields, literal values, supported operators). Order,
+* limit and projection do not matter to a channel and are ignored.
+*/
+function compileScope(schema, plan) {
+	const table = schema.tables.find((t) => t.name === plan.table);
+	if (!table?.channel) throw new Error(`Cannot open a channel on '${plan.table}': the table is not marked '-- @channel'. Add '-- @channel' above 'DEFINE TABLE ${plan.table}' and run 'spky generate'.`);
+	if (plan.relations && plan.relations.length > 0) throw new Error(`A channel query on '${plan.table}' cannot use .related(): its filter must be decidable from the row alone.`);
+	const where = plan.where ?? [];
+	for (const node of where) for (const c of "or" in node ? node.or : [node]) {
+		if (!(c.op in OPS)) throw new Error(`A channel query on '${plan.table}' cannot use the operator '${c.op}'.`);
+		if (c.value === void 0 && c.paramRef) throw new Error(`A channel query on '${plan.table}' cannot compare '${c.field}' with a parameter ($${c.paramRef}); use a value.`);
+		const root = c.field.split(".")[0];
+		if (c.field.includes(".") && table.columns[root]?.recordId) throw new Error(`A channel query on '${plan.table}' cannot filter on '${c.field}': it follows a record link, which the row alone does not hold.`);
+	}
+	return {
+		table: plan.table,
+		where
+	};
+}
+const SWEEP_MS = 1e3;
+const randomPeerId = () => {
+	const bytes = new Uint8Array(8);
+	globalThis.crypto.getRandomValues(bytes);
+	return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+};
+var ChannelManager = class {
+	tables;
+	schema;
+	overlay = /* @__PURE__ */ new Map();
+	taps = /* @__PURE__ */ new Set();
+	channels = /* @__PURE__ */ new Set();
+	handles = /* @__PURE__ */ new WeakMap();
+	connected = /* @__PURE__ */ new Map();
+	userStatus = /* @__PURE__ */ new Map();
+	/** Unused-argument warnings already given, so a reactive query does not repeat them. */
+	warnedUnused = /* @__PURE__ */ new Set();
+	peerId = randomPeerId();
+	user = null;
+	clock;
+	transport = null;
+	sweepTimer = null;
+	closed = false;
+	now;
+	confirmMs;
+	constructor(schema, deps = {}) {
+		this.deps = deps;
+		this.schema = schema;
+		this.tables = new Map(schema.tables.map((t) => [t.name, {
+			columns: t.columns,
+			channel: t.channel === true
+		}]));
+		this.now = deps.now ?? Date.now;
+		this.confirmMs = Math.max(0, deps.config?.confirmTimeoutMs ?? 5e3);
+		this.clock = [
+			0,
+			0,
+			this.peerId
+		];
+	}
+	/** True when any table is a channel table; otherwise the client skips all of this. */
+	get enabled() {
+		for (const t of this.tables.values()) if (t.channel) return true;
+		return false;
+	}
+	/** The signed-in user changed: peers, their values and the transport start over. */
+	setUser(user) {
+		if (user === this.user) return;
+		this.user = user;
+		this.transport?.close();
+		this.transport = null;
+		this.connected.clear();
+		this.userStatus.clear();
+		const touched = new Set(this.overlay.keys());
+		this.overlay.clear();
+		for (const ch of this.channels) ch.users = peerUsers(ch.listed, user);
+		this.syncWanted();
+		this.emitFor(touched);
+		this.notifyAll();
+	}
+	/**
+	* Compile a query plan into a channel scope (throws when it cannot be
+	* one). Parts the channel ignores draw one warning per distinct query
+	* shape, unless the query says so itself (`ignoreUnused`).
+	*/
+	scope(plan, opts = {}) {
+		const scope = compileScope(this.schema, plan);
+		const unused = opts.ignoreUnused ? [] : unusedArgs(plan, opts.isOne);
+		if (unused.length > 0) {
+			const message = `channel query on '${plan.table}' has ${unused.join(", ")}, which a channel ignores (it only uses the where filter). Remove them, or add .ignoreUnusedArgs() to the query to say it is on purpose.`;
+			if (!this.warnedUnused.has(message)) {
+				this.warnedUnused.add(message);
+				this.deps.logger?.warn({
+					table: plan.table,
+					unused,
+					Category: "sp00ky-client::channel"
+				}, message);
+			}
+		}
+		return scope;
+	}
+	/** Open a channel carrying the rows `scopes` match to `peers`. */
+	open(scopes, peers) {
+		if (scopes.length === 0) throw new Error("A channel needs at least one query.");
+		const listed = [...peers];
+		const ch = {
+			scopes,
+			listed,
+			users: peerUsers(listed, this.user),
+			listeners: /* @__PURE__ */ new Set(),
+			state: {
+				status: "idle",
+				peers: []
+			},
+			closed: false
+		};
+		this.channels.add(ch);
+		this.syncWanted();
+		ch.state = this.stateOf(ch);
+		const handle = {
+			tables: () => [...new Set(ch.scopes.map((sc) => sc.table))],
+			state: () => ch.state,
+			subscribe: (cb) => {
+				cb(ch.state);
+				ch.listeners.add(cb);
+				return () => ch.listeners.delete(cb);
+			},
+			setPeers: (next) => {
+				if (ch.closed) return;
+				ch.listed = [...next];
+				ch.users = peerUsers(ch.listed, this.user);
+				this.syncWanted();
+				this.notify(ch);
+			},
+			setScopes: (next) => {
+				if (ch.closed) return;
+				if (next.length === 0) throw new Error("A channel needs at least one query.");
+				ch.scopes = next;
+			},
+			close: () => {
+				if (ch.closed) return;
+				ch.closed = true;
+				this.channels.delete(ch);
+				ch.listeners.clear();
+				this.syncWanted();
+			}
+		};
+		this.handles.set(handle, ch);
+		return handle;
+	}
+	/** Throws unless `handle` is an open channel of this manager with a query on `table`. */
+	assertCarries(handle, table) {
+		const ch = this.handles.get(handle);
+		if (!ch || ch.closed) throw new Error("This channel is closed.");
+		if (!ch.scopes.some((sc) => sc.table === table)) throw new Error(`This channel has no query on '${table}' (it reads ${[...new Set(ch.scopes.map((sc) => sc.table))].join(", ")}).`);
+	}
+	/**
+	* Follow a subscription: `feed` it the raw rows, and `cb` gets them with
+	* the overlay folded in, again whenever the overlay changes for its rows.
+	*/
+	tap(cb) {
+		const tap = {
+			cb,
+			raw: null,
+			ids: null
+		};
+		this.taps.add(tap);
+		return {
+			feed: (rows) => {
+				tap.raw = rows;
+				tap.ids = null;
+				this.emit(tap);
+			},
+			stop: () => {
+				this.taps.delete(tap);
+			}
+		};
+	}
+	/** Split an own write on `table` into database fields and peer-only fields. */
+	split(table, data) {
+		const t = this.tables.get(table);
+		if (!t?.channel) return {
+			persistent: data,
+			ephemeral: null
+		};
+		return splitPatch(t.columns, data);
+	}
+	/**
+	* An own update: ephemeral fields go into the overlay (they have no other
+	* home), persistent fields drop any peer value they supersede, and the
+	* whole patch goes to the peers (of `scope`, or of the channel carrying the
+	* table, see `targets`).
+	*/
+	local(table, id, persistent, ephemeral, scope) {
+		if (!this.tables.get(table)?.channel || this.closed) return;
+		const rid = normalizeId(table, id);
+		const hlc = this.tick();
+		const fields = this.overlay.get(rid);
+		let touched = false;
+		if (fields) for (const f of Object.keys(persistent)) touched = fields.delete(f) || touched;
+		if (ephemeral) {
+			const map = fields ?? /* @__PURE__ */ new Map();
+			for (const [f, value] of Object.entries(ephemeral)) map.set(f, {
+				value,
+				hlc,
+				from: "self",
+				ephemeral: true,
+				expiresAt: null
+			});
+			this.overlay.set(rid, map);
+			touched = true;
+		}
+		if (fields && fields.size === 0) this.overlay.delete(rid);
+		if (touched) this.emitFor(new Set([rid]));
+		const patch = {
+			...persistent,
+			...ephemeral ?? {}
+		};
+		if (Object.keys(patch).length === 0) return;
+		this.rowFor(rid).then((row) => {
+			const after = {
+				...row ?? { id: rid },
+				...patch
+			};
+			this.send(this.targets(table, row ? [row, after] : [after], scope), table, rid, patch, hlc, "update");
+		});
+	}
+	/**
+	* An own create: its ephemeral fields go into the overlay (the store never
+	* holds them), and the whole row goes to the peers.
+	*/
+	localCreate(table, id, row, scope) {
+		const t = this.tables.get(table);
+		if (!t?.channel || this.closed) return;
+		const rid = normalizeId(table, id);
+		const full = pickColumns(t.columns, row);
+		const hlc = this.tick();
+		const ephemeral = Object.keys(full).filter((f) => t.columns[f]?.ephemeral);
+		if (ephemeral.length > 0) {
+			const map = this.overlay.get(rid) ?? /* @__PURE__ */ new Map();
+			for (const f of ephemeral) map.set(f, {
+				value: full[f],
+				hlc,
+				from: "self",
+				ephemeral: true,
+				expiresAt: null
+			});
+			this.overlay.set(rid, map);
+			this.emitFor(new Set([rid]));
+		}
+		this.send(this.targets(table, [{
+			...full,
+			id: rid
+		}], scope), table, rid, full, hlc, "create");
+	}
+	/**
+	* An own delete: the peers hide the row at once. Resolves once it is sent;
+	* await it before the local delete, which the filter check reads past.
+	*/
+	async localDelete(table, id, scope) {
+		if (!this.tables.get(table)?.channel || this.closed) return;
+		const rid = normalizeId(table, id);
+		const hlc = this.tick();
+		const row = await this.rowFor(rid);
+		if (row) this.send(this.targets(table, [row], scope), table, rid, {}, hlc, "delete");
+		if (this.overlay.delete(rid)) this.emitFor(new Set([rid]));
+	}
+	/** A transport delivered a message from `from`. */
+	receive(from, raw) {
+		if (this.closed) return;
+		const msg = parseMessage(raw);
+		if (!msg) return this.drop(from, "malformed message");
+		this.observe(msg.hlc);
+		const t = this.tables.get(msg.table);
+		if (!t?.channel) return this.drop(from, `'${msg.table}' is not a @channel table`);
+		const rid = normalizeId(msg.table, msg.id);
+		if (rid.slice(0, rid.indexOf(":")) !== msg.table) return this.drop(from, "id is not a row of the table");
+		if (!this.listedOn(msg.table, from.user)) return this.drop(from, `no channel on '${msg.table}' lists ${from.user}`);
+		const kind = msg.kind ?? "update";
+		if (kind === "create") return this.receiveCreate(from, msg, rid, t.columns);
+		if (kind === "delete") return void this.receiveDelete(from, msg.table, rid);
+		const patch = {};
+		for (const [k, v] of Object.entries(msg.patch)) patch[k] = decodeValue(v);
+		const problem = checkPatch(t.columns, patch);
+		if (problem) return this.drop(from, problem);
+		this.receiveUpdate(from, msg, rid, patch, t.columns);
+	}
+	/** A peer updated a row we hold, inside a channel's filter (before or after the patch). */
+	async receiveUpdate(from, msg, rid, patch, columns) {
+		const row = await this.rowFor(rid);
+		if (this.closed) return;
+		if (!row) return this.drop(from, `${rid} is not held here, so no filter can be checked`);
+		if (!this.matchesFor(msg.table, [row, {
+			...row,
+			...patch
+		}], from.user)) return this.drop(from, `${rid} is outside every channel listing ${from.user}`);
+		if (!this.accepts({
+			kind: "update",
+			from: from.user,
+			table: msg.table,
+			id: rid,
+			row,
+			patch
+		})) return this.drop(from, "refused by the accept rule");
+		const map = this.overlay.get(rid) ?? /* @__PURE__ */ new Map();
+		const key = peerKey(from);
+		let touched = false;
+		for (const [field, value] of Object.entries(patch)) {
+			const prev = map.get(field);
+			if (prev && compareHlc(prev.hlc, msg.hlc) >= 0) continue;
+			const ephemeral = columns[field]?.ephemeral === true;
+			map.set(field, {
+				value,
+				hlc: msg.hlc,
+				from: key,
+				ephemeral,
+				expiresAt: ephemeral ? null : this.now() + this.confirmMs
+			});
+			touched = true;
+		}
+		if (map.size > 0) this.overlay.set(rid, map);
+		if (!touched) return;
+		this.ensureSweep();
+		this.emitFor(new Set([rid]));
+	}
+	/** A peer created a row: into the store like an own optimistic create, unconfirmed. */
+	receiveCreate(from, msg, rid, columns) {
+		const rows = this.deps.rows;
+		if (!rows) return this.drop(from, "creates are not wired");
+		const row = {};
+		for (const [k, v] of Object.entries(msg.patch)) if (k !== "id") row[k] = decodeValue(v);
+		const problem = checkPatch(columns, row, true);
+		if (problem) return this.drop(from, problem);
+		if (!this.matchesFor(msg.table, [{
+			...row,
+			id: parseRecordIdString(rid)
+		}], from.user)) return this.drop(from, `the new ${rid} is outside every channel listing ${from.user}`);
+		if (!this.accepts({
+			kind: "create",
+			from: from.user,
+			table: msg.table,
+			id: rid,
+			row: void 0,
+			patch: row
+		})) return this.drop(from, "refused by the accept rule");
+		const persistent = {};
+		const ephemeral = {};
+		for (const [k, v] of Object.entries(row)) (columns[k]?.ephemeral ? ephemeral : persistent)[k] = v;
+		rows.create(msg.table, rid, persistent, this.confirmMs).then((applied) => {
+			if (!applied || this.closed || Object.keys(ephemeral).length === 0) return;
+			const map = this.overlay.get(rid) ?? /* @__PURE__ */ new Map();
+			for (const [f, value] of Object.entries(ephemeral)) map.set(f, {
+				value,
+				hlc: msg.hlc,
+				from: peerKey(from),
+				ephemeral: true,
+				expiresAt: null
+			});
+			this.overlay.set(rid, map);
+			this.emitFor(new Set([rid]));
+		}, (error) => this.deps.logger?.debug({
+			error,
+			Category: "sp00ky-client::channel"
+		}, "peer create failed"));
+	}
+	/** A peer deleted a row inside a channel's filter: hide it until the server confirms (or undo its own create). */
+	async receiveDelete(from, table, rid) {
+		const rows = this.deps.rows;
+		if (!rows) return this.drop(from, "deletes are not wired");
+		const row = await this.rowFor(rid);
+		if (this.closed) return;
+		if (!row) return this.drop(from, `${rid} is not held here`);
+		if (!this.matchesFor(table, [row], from.user)) return this.drop(from, `${rid} is outside every channel listing ${from.user}`);
+		if (!this.accepts({
+			kind: "delete",
+			from: from.user,
+			table,
+			id: rid,
+			row,
+			patch: {}
+		})) return this.drop(from, "refused by the accept rule");
+		if (this.overlay.delete(rid)) this.emitFor(new Set([rid]));
+		rows.delete(table, rid, this.confirmMs).catch((error) => this.deps.logger?.debug({
+			error,
+			Category: "sp00ky-client::channel"
+		}, "peer delete failed"));
+	}
+	accepts(op) {
+		const rule = this.deps.config?.accept?.[op.table];
+		if (!rule) return true;
+		try {
+			return rule(op) === true;
+		} catch (error) {
+			this.deps.logger?.warn({
+				error,
+				Category: "sp00ky-client::channel"
+			}, "channel accept rule threw");
+			return false;
+		}
+	}
+	/** A peer tab came up (send it our ephemeral state) or went away (drop its). */
+	peerChanged(peer, up) {
+		const key = peerKey(peer);
+		if (up) {
+			this.connected.set(key, peer);
+			this.userStatus.set(peer.user, "connected");
+			this.sendSnapshot(peer);
+		} else {
+			this.connected.delete(key);
+			const touched = /* @__PURE__ */ new Set();
+			for (const [rid, fields] of this.overlay) {
+				for (const [f, e] of fields) if (e.from === key && e.ephemeral) {
+					fields.delete(f);
+					touched.add(rid);
+				}
+				if (fields.size === 0) this.overlay.delete(rid);
+			}
+			this.emitFor(touched);
+		}
+		this.notifyAll();
+	}
+	statusChanged(user, status) {
+		if (status !== "connected" && [...this.connected.values()].some((p) => p.user === user)) return;
+		this.userStatus.set(user, status);
+		this.notifyAll();
+	}
+	close() {
+		this.closed = true;
+		this.transport?.close();
+		this.transport = null;
+		if (this.sweepTimer) clearInterval(this.sweepTimer);
+		this.sweepTimer = null;
+		this.taps.clear();
+		for (const ch of this.channels) ch.closed = true;
+		this.channels.clear();
+		this.overlay.clear();
+	}
+	syncWanted() {
+		if (this.closed) return;
+		const wanted = /* @__PURE__ */ new Set();
+		for (const ch of this.channels) for (const u of ch.users) wanted.add(u);
+		if (!this.transport) {
+			if (wanted.size === 0 || !this.user || !this.deps.transport) return;
+			this.transport = this.deps.transport({
+				self: () => this.user ? {
+					user: this.user,
+					peer: this.peerId
+				} : null,
+				onMessage: (from, message) => this.receive(from, message),
+				onPeer: (peer, up) => this.peerChanged(peer, up),
+				onStatus: (user, status) => this.statusChanged(user, status)
+			});
+		}
+		this.transport.want(wanted);
+	}
+	/** Some open channel lists `user` and has a query on `table` (the cheap check before any read). */
+	listedOn(table, user) {
+		for (const ch of this.channels) if (ch.users.has(user) && ch.scopes.some((sc) => sc.table === table)) return true;
+		return false;
+	}
+	/** Some open channel listing `user` has a query on `table` one of `rows` matches. */
+	matchesFor(table, rows, user) {
+		for (const ch of this.channels) if (ch.users.has(user) && carries(ch, table, rows)) return true;
+		return false;
+	}
+	/**
+	* Who an own write goes to: the peers of every open channel (or only
+	* `scope`) whose filter one of `rows` matches. That is what keeps a
+	* message of one conversation away from the participants of another.
+	*/
+	targets(table, rows, scope) {
+		const users = /* @__PURE__ */ new Set();
+		const pick = scope ? this.handles.get(scope) : void 0;
+		for (const ch of pick ? [pick] : this.channels) {
+			if (ch.closed || !carries(ch, table, rows)) continue;
+			for (const u of ch.users) users.add(u);
+		}
+		return users;
+	}
+	/** The row as shown (overlay included): from a subscription, else the store. */
+	async rowFor(rid) {
+		const shown = this.rowOf(rid);
+		if (shown) return shown;
+		const stored = await this.deps.rows?.read(rid).catch(() => null);
+		return stored ? applyOverlay([stored], this.overlay)[0] : null;
+	}
+	send(users, table, rid, patch, hlc, kind) {
+		const transport = this.transport;
+		if (!transport || users.size === 0) return;
+		const encoded = {};
+		for (const [k, v] of Object.entries(patch)) encoded[k] = encodeValue(v);
+		const message = kind === "update" ? {
+			t: "op",
+			table,
+			id: rid,
+			patch: encoded,
+			hlc
+		} : {
+			t: "op",
+			kind,
+			table,
+			id: rid,
+			patch: encoded,
+			hlc
+		};
+		for (const peer of this.connected.values()) if (users.has(peer.user)) transport.send(peer, message);
+	}
+	/** Own ephemeral values of rows inside a channel a newly connected peer is listed on. */
+	sendSnapshot(peer) {
+		for (const [rid, fields] of this.overlay) {
+			const own = [...fields].filter(([, e]) => e.from === "self");
+			if (own.length === 0) continue;
+			const table = rid.slice(0, rid.indexOf(":"));
+			if (!this.listedOn(table, peer.user)) continue;
+			const patch = {};
+			let hlc = own[0][1].hlc;
+			for (const [f, e] of own) {
+				patch[f] = encodeValue(e.value);
+				if (compareHlc(e.hlc, hlc) > 0) hlc = e.hlc;
+			}
+			this.rowFor(rid).then((row) => {
+				if (!row || !this.matchesFor(table, [row], peer.user)) return;
+				this.transport?.send(peer, {
+					t: "op",
+					table,
+					id: rid,
+					patch,
+					hlc
+				});
+			});
+		}
+	}
+	rowOf(rid) {
+		for (const tap of this.taps) {
+			if (!tap.raw || !idsOf(tap).has(rid)) continue;
+			const row = findRow(tap.raw, rid, 0);
+			if (row) return applyOverlay([row], this.overlay)[0];
+		}
+	}
+	emit(tap) {
+		if (!tap.raw) return;
+		const rows = applyOverlay(tap.raw, this.overlay);
+		this.confirm(tap.raw);
+		tap.cb(rows);
+	}
+	emitFor(rids) {
+		if (rids.size === 0) return;
+		for (const tap of this.taps) {
+			if (!tap.raw) continue;
+			const ids = idsOf(tap);
+			for (const rid of rids) if (ids.has(rid)) {
+				this.emit(tap);
+				break;
+			}
+		}
+	}
+	/** Persistent peer values the synced rows already hold are done showing. */
+	confirm(raw) {
+		if (this.overlay.size === 0) return;
+		for (const rid of collectIds(raw)) {
+			const fields = this.overlay.get(rid);
+			if (!fields) continue;
+			const row = findRow(raw, rid, 0);
+			if (!row) continue;
+			for (const [f, e] of fields) if (!e.ephemeral && e.from !== "self" && f in row && sameValue(row[f], e.value)) fields.delete(f);
+			if (fields.size === 0) this.overlay.delete(rid);
+		}
+	}
+	ensureSweep() {
+		if (this.sweepTimer || this.closed) return;
+		this.sweepTimer = setInterval(() => this.sweep(), SWEEP_MS);
+	}
+	sweep() {
+		const now = this.now();
+		const touched = /* @__PURE__ */ new Set();
+		let pending = false;
+		for (const [rid, fields] of this.overlay) {
+			for (const [f, e] of fields) {
+				if (e.expiresAt === null) continue;
+				if (e.expiresAt <= now) {
+					fields.delete(f);
+					touched.add(rid);
+				} else pending = true;
+			}
+			if (fields.size === 0) this.overlay.delete(rid);
+		}
+		if (!pending && this.sweepTimer) {
+			clearInterval(this.sweepTimer);
+			this.sweepTimer = null;
+		}
+		this.emitFor(touched);
+	}
+	tick() {
+		const now = this.now();
+		const [ms, c] = this.clock;
+		this.clock = now > ms ? [
+			now,
+			0,
+			this.peerId
+		] : [
+			ms,
+			c + 1,
+			this.peerId
+		];
+		return this.clock;
+	}
+	observe(h) {
+		if (h[0] > this.clock[0] || h[0] === this.clock[0] && h[1] > this.clock[1]) this.clock = [
+			h[0],
+			h[1],
+			this.peerId
+		];
+	}
+	stateOf(ch) {
+		const users = [...ch.users];
+		if (users.length === 0) return {
+			status: "idle",
+			peers: []
+		};
+		if (this.transport && !this.transport.supported) return {
+			status: "unsupported",
+			peers: []
+		};
+		const up = users.filter((u) => [...this.connected.values()].some((p) => p.user === u));
+		if (up.length > 0) return {
+			status: "connected",
+			peers: up
+		};
+		if (users.every((u) => this.userStatus.get(u) === "failed")) return {
+			status: "failed",
+			peers: []
+		};
+		return {
+			status: "connecting",
+			peers: []
+		};
+	}
+	notify(ch) {
+		const next = this.stateOf(ch);
+		if (next.status === ch.state.status && next.peers.join(",") === ch.state.peers.join(",")) return;
+		ch.state = next;
+		for (const cb of ch.listeners) cb(next);
+	}
+	notifyAll() {
+		for (const ch of this.channels) this.notify(ch);
+	}
+	drop(from, reason) {
+		this.deps.logger?.debug({
+			from: from.user,
+			reason,
+			Category: "sp00ky-client::channel"
+		}, "channel message dropped");
+	}
+};
+/** Whether a channel has a query on `table` that one of `rows` matches. */
+function carries(ch, table, rows) {
+	return ch.scopes.some((sc) => sc.table === table && rows.some((r) => matchesWhere(sc.where, r)));
+}
+/** The fields of `row` the table has as plain columns (no id, no `@crdt`). */
+function pickColumns(columns, row) {
+	const out = {};
+	for (const [k, v] of Object.entries(row)) {
+		if (k === "id" || !columns[k] || columns[k].crdt || v === void 0) continue;
+		out[k] = v;
+	}
+	return out;
+}
+function idsOf(tap) {
+	return tap.ids ??= tap.raw ? collectIds(tap.raw) : /* @__PURE__ */ new Set();
+}
+/** `table:id` for an id given with or without its table. */
+function normalizeId(table, id) {
+	return id.includes(":") ? id : `${table}:${id}`;
+}
+function findRow(rows, rid, depth) {
+	if (depth > OVERLAY_DEPTH) return null;
+	for (const v of rows) {
+		if (v === null || typeof v !== "object") continue;
+		if (Array.isArray(v)) {
+			const hit = findRow(v, rid, depth + 1);
+			if (hit) return hit;
+			continue;
+		}
+		if (isRecordIdLike(v) || v instanceof Date || v instanceof Uint8Array) continue;
+		const row = v;
+		if ("id" in row && idKey(row.id) === rid) return row;
+		for (const [k, x] of Object.entries(row)) {
+			if (k === "id" || x === null || typeof x !== "object") continue;
+			const hit = findRow([x], rid, depth + 1);
+			if (hit) return hit;
+		}
+	}
+	return null;
+}
+
+//#endregion
+//#region src/modules/channel/webrtc.ts
+const DEFAULT_ICE = [{ urls: "stun:stun.cloudflare.com:3478" }];
+const ICE_FLUSH_MS = 20;
+const RETRY_BASE_MS$1 = 2e3;
+const RETRY_MAX_MS$1 = 3e4;
+const randomSid = () => Math.random().toString(36).slice(2, 10);
+function webrtcTransport(hooks, opts) {
+	const PC = opts.RTCPeerConnection ?? globalThis.RTCPeerConnection;
+	const log = opts.logger;
+	const connectTimeoutMs = opts.connectTimeoutMs ?? 15e3;
+	const links = /* @__PURE__ */ new Map();
+	const retries = /* @__PURE__ */ new Map();
+	let wanted = /* @__PURE__ */ new Set();
+	let stopListen = null;
+	let listeningAs = null;
+	let closed = false;
+	const selfKey = () => {
+		const self = hooks.self();
+		return self ? peerKey(self) : null;
+	};
+	const send = (link, signal) => {
+		const self = hooks.self();
+		if (!self) return;
+		const out = {
+			...signal,
+			fromPeer: self.peer
+		};
+		const run = () => opts.signal.send(out).catch((error) => {
+			log?.debug({
+				error,
+				kind: signal.kind,
+				Category: "sp00ky-client::channel"
+			}, "channel signal failed");
+		});
+		if (link) link.queue = link.queue.then(run);
+		else run();
+	};
+	const dropLink = (link, failed) => {
+		if (link.closed) return;
+		link.closed = true;
+		if (link.iceTimer) clearTimeout(link.iceTimer);
+		if (link.connectTimer) clearTimeout(link.connectTimer);
+		try {
+			link.dc?.close();
+			link.pc.close();
+		} catch {}
+		if (links.get(link.key) === link) links.delete(link.key);
+		if (link.open) {
+			link.open = false;
+			hooks.onPeer(link.ref, false);
+		}
+		if (failed && wanted.has(link.ref.user) && !closed) {
+			if (![...links.values()].some((l) => l.ref.user === link.ref.user && l.open)) hooks.onStatus(link.ref.user, "failed");
+			scheduleRetry(link.ref);
+		}
+	};
+	const scheduleRetry = (ref) => {
+		const key = peerKey(ref);
+		const r = retries.get(key) ?? {
+			attempts: 0,
+			timer: null
+		};
+		if (r.timer) return;
+		const delay = Math.min(RETRY_MAX_MS$1, RETRY_BASE_MS$1 * 2 ** r.attempts);
+		r.attempts++;
+		r.timer = setTimeout(() => {
+			r.timer = null;
+			if (closed || !wanted.has(ref.user) || links.has(key)) return;
+			const mine = selfKey();
+			if (!mine) return;
+			if (mine < key) startOffer(ref);
+			else send(null, {
+				to: ref.user,
+				toPeer: ref.peer,
+				kind: "hello",
+				payload: null
+			});
+		}, delay);
+		retries.set(key, r);
+	};
+	const attachChannel = (link, dc) => {
+		link.dc = dc;
+		dc.onopen = () => {
+			if (link.closed) return;
+			link.open = true;
+			if (link.connectTimer) clearTimeout(link.connectTimer);
+			link.connectTimer = null;
+			retries.delete(link.key);
+			hooks.onPeer(link.ref, true);
+			hooks.onStatus(link.ref.user, "connected");
+		};
+		dc.onclose = () => dropLink(link, true);
+		dc.onmessage = (event) => {
+			if (typeof event.data !== "string") return;
+			let message;
+			try {
+				message = JSON.parse(event.data);
+			} catch {
+				return;
+			}
+			hooks.onMessage(link.ref, message);
+		};
+	};
+	const newLink = (ref, offerer, sid) => {
+		if (!PC) return null;
+		const key = peerKey(ref);
+		const prev = links.get(key);
+		if (prev) dropLink(prev, false);
+		const pc = new PC({ iceServers: opts.iceServers ?? DEFAULT_ICE });
+		const link = {
+			ref,
+			key,
+			offerer,
+			sid,
+			pc,
+			dc: null,
+			open: false,
+			remoteSet: false,
+			pendingIce: [],
+			outIce: [],
+			iceTimer: null,
+			connectTimer: null,
+			queue: Promise.resolve(),
+			closed: false
+		};
+		links.set(key, link);
+		pc.onicecandidate = (event) => {
+			if (!event.candidate || link.closed) return;
+			link.outIce.push(event.candidate.toJSON());
+			link.iceTimer ??= setTimeout(() => {
+				link.iceTimer = null;
+				const candidates = link.outIce.splice(0);
+				if (candidates.length === 0 || link.closed) return;
+				send(link, {
+					to: ref.user,
+					toPeer: ref.peer,
+					kind: "ice",
+					payload: JSON.stringify({
+						sid,
+						candidates
+					})
+				});
+			}, ICE_FLUSH_MS);
+		};
+		pc.onconnectionstatechange = () => {
+			if (pc.connectionState === "failed" || pc.connectionState === "closed") dropLink(link, true);
+		};
+		if (!offerer) pc.ondatachannel = (event) => attachChannel(link, event.channel);
+		link.connectTimer = setTimeout(() => {
+			if (!link.open) dropLink(link, true);
+		}, connectTimeoutMs);
+		hooks.onStatus(ref.user, "connecting");
+		return link;
+	};
+	const startOffer = (ref) => {
+		const link = newLink(ref, true, randomSid());
+		if (!link) return;
+		attachChannel(link, link.pc.createDataChannel("sp00ky", { ordered: true }));
+		(async () => {
+			try {
+				const offer = await link.pc.createOffer();
+				await link.pc.setLocalDescription(offer);
+				send(link, {
+					to: ref.user,
+					toPeer: ref.peer,
+					kind: "offer",
+					payload: JSON.stringify({
+						sid: link.sid,
+						sdp: link.pc.localDescription?.sdp ?? offer.sdp
+					})
+				});
+			} catch (error) {
+				log?.debug({
+					error,
+					Category: "sp00ky-client::channel"
+				}, "channel offer failed");
+				dropLink(link, true);
+			}
+		})();
+	};
+	const addIce = async (link, candidates) => {
+		for (const c of candidates) try {
+			await link.pc.addIceCandidate(c);
+		} catch {}
+	};
+	const onSignal = (s) => {
+		if (closed) return;
+		const self = hooks.self();
+		if (!self) return;
+		const from = idKey(s.from);
+		if (!from || !wanted.has(from)) return;
+		if (s.toPeer !== null && s.toPeer !== self.peer) return;
+		const ref = {
+			user: from,
+			peer: s.fromPeer
+		};
+		const key = peerKey(ref);
+		const mine = peerKey(self);
+		if (key === mine) return;
+		const payload = parsePayload(s.payload);
+		const link = links.get(key);
+		switch (s.kind) {
+			case "hello":
+				if (link && !link.closed) return;
+				if (mine < key) startOffer(ref);
+				else if (s.toPeer === null) send(null, {
+					to: from,
+					toPeer: ref.peer,
+					kind: "hello",
+					payload: null
+				});
+				return;
+			case "offer": {
+				if (mine < key || typeof payload?.sdp !== "string" || typeof payload.sid !== "string") return;
+				const answerer = newLink(ref, false, payload.sid);
+				if (!answerer) return;
+				(async () => {
+					try {
+						await answerer.pc.setRemoteDescription({
+							type: "offer",
+							sdp: payload.sdp
+						});
+						answerer.remoteSet = true;
+						await addIce(answerer, answerer.pendingIce.splice(0));
+						const answer = await answerer.pc.createAnswer();
+						await answerer.pc.setLocalDescription(answer);
+						send(answerer, {
+							to: from,
+							toPeer: ref.peer,
+							kind: "answer",
+							payload: JSON.stringify({
+								sid: answerer.sid,
+								sdp: answerer.pc.localDescription?.sdp ?? answer.sdp
+							})
+						});
+					} catch (error) {
+						log?.debug({
+							error,
+							Category: "sp00ky-client::channel"
+						}, "channel answer failed");
+						dropLink(answerer, true);
+					}
+				})();
+				return;
+			}
+			case "answer":
+				if (!link || !link.offerer || link.remoteSet || payload?.sid !== link.sid || typeof payload.sdp !== "string") return;
+				link.remoteSet = true;
+				link.pc.setRemoteDescription({
+					type: "answer",
+					sdp: payload.sdp
+				}).then(() => addIce(link, link.pendingIce.splice(0))).catch(() => dropLink(link, true));
+				return;
+			case "ice": {
+				if (!link || payload?.sid !== link.sid || !Array.isArray(payload.candidates)) return;
+				const candidates = payload.candidates;
+				if (link.remoteSet) addIce(link, candidates);
+				else link.pendingIce.push(...candidates);
+				return;
+			}
+		}
+	};
+	const ensureListening = () => {
+		const self = hooks.self();
+		const as = self ? peerKey(self) : null;
+		if (as === listeningAs) return;
+		stopListen?.();
+		stopListen = null;
+		listeningAs = as;
+		if (self) stopListen = opts.signal.listen(self, onSignal);
+	};
+	return {
+		supported: PC !== void 0,
+		want(users) {
+			if (closed || !PC) {
+				wanted = new Set(users);
+				return;
+			}
+			const before = wanted;
+			wanted = new Set(users);
+			if (wanted.size > 0) ensureListening();
+			for (const link of [...links.values()]) if (!wanted.has(link.ref.user)) dropLink(link, false);
+			for (const [key, r] of retries) if (!wanted.has(key.slice(0, key.lastIndexOf("#"))) && r.timer) clearTimeout(r.timer);
+			for (const user of wanted) {
+				if (before.has(user)) continue;
+				send(null, {
+					to: user,
+					toPeer: null,
+					kind: "hello",
+					payload: null
+				});
+				hooks.onStatus(user, "connecting");
+			}
+		},
+		send(to, message) {
+			const link = links.get(peerKey(to));
+			if (!link?.open || !link.dc || link.dc.readyState !== "open") return;
+			try {
+				link.dc.send(JSON.stringify(message));
+			} catch (error) {
+				log?.debug({
+					error,
+					Category: "sp00ky-client::channel"
+				}, "channel send failed");
+			}
+		},
+		close() {
+			closed = true;
+			for (const r of retries.values()) if (r.timer) clearTimeout(r.timer);
+			retries.clear();
+			for (const link of [...links.values()]) dropLink(link, false);
+			stopListen?.();
+			stopListen = null;
+		}
+	};
+}
+function parsePayload(payload) {
+	if (!payload) return null;
+	try {
+		const v = JSON.parse(payload);
+		return v !== null && typeof v === "object" ? v : null;
+	} catch {
+		return null;
+	}
+}
+const SIGNAL_TABLE = "_00_channel_signal";
+const LISTEN_RETRY_MS = 3e3;
+/**
+* Signals as rows of `_00_channel_signal` (generated for schemas with a
+* `@channel` table): a CREATE to send, one raw `LIVE SELECT` on rows
+* addressed to this user to receive. Not the outbox and not a synced query:
+* each signal costs one round trip, which is what keeps connection setup
+* short. The LIVE is re-armed whenever the socket reconnects.
+*/
+function surrealSignal(remote, connection, logger) {
+	return {
+		async send(s) {
+			const content = {
+				recipient: parseRecordIdString(s.to),
+				sender_peer: s.fromPeer,
+				kind: s.kind
+			};
+			if (s.toPeer !== null) content.recipient_peer = s.toPeer;
+			if (s.payload !== null) content.payload = s.payload;
+			await remote.query(`CREATE ${SIGNAL_TABLE} CONTENT $c RETURN NONE`, { c: content });
+		},
+		listen(self, cb) {
+			let stopped = false;
+			let uuid = null;
+			let retry = null;
+			let state = null;
+			const arm = async () => {
+				if (stopped) return;
+				if (retry) clearTimeout(retry);
+				retry = null;
+				const old = uuid;
+				uuid = null;
+				if (old) remote.query("KILL $u", { u: old }).catch(() => {});
+				try {
+					const [id] = await remote.query(`LIVE SELECT * FROM ${SIGNAL_TABLE} WHERE recipient = $me`, { me: parseRecordIdString(self.user) });
+					if (stopped) {
+						remote.query("KILL $u", { u: id }).catch(() => {});
+						return;
+					}
+					uuid = id;
+					(await remote.getClient().liveOf(id)).subscribe((message) => {
+						if (stopped || message.action !== "CREATE") return;
+						const v = message.value;
+						const from = idKey(v.sender);
+						if (!from || typeof v.sender_peer !== "string" || typeof v.kind !== "string") return;
+						cb({
+							from,
+							fromPeer: v.sender_peer,
+							toPeer: typeof v.recipient_peer === "string" ? v.recipient_peer : null,
+							kind: v.kind,
+							payload: typeof v.payload === "string" ? v.payload : null
+						});
+					});
+				} catch (error) {
+					logger?.debug({
+						error,
+						Category: "sp00ky-client::channel"
+					}, "channel signal listen failed; retrying");
+					if (!stopped) retry = setTimeout(() => void arm(), LISTEN_RETRY_MS);
+				}
+			};
+			const unsubscribe = connection.subscribe((next) => {
+				const was = state;
+				state = next;
+				if (next === "connected" && was !== null && was !== "connected") arm();
+			});
+			arm();
+			return () => {
+				stopped = true;
+				unsubscribe();
+				if (retry) clearTimeout(retry);
+				if (uuid) remote.query("KILL $u", { u: uuid }).catch(() => {});
+			};
+		}
+	};
+}
+
 //#endregion
 //#region src/mutation/rows.ts
 const PENDING_TABLE = "_00_pending_mutations";
@@ -1509,6 +2850,29 @@ function planDeleteTx(input) {
 	};
 }
 /**
+* A channel peer's create: the row alone, no outbox entry (the peer's own
+* client pushes it). Result index 0 is the row.
+*/
+function planPeerCreateTx(input) {
+	const keys = Object.keys(input.data).map((key) => ({
+		key,
+		variable: `data_${key}`
+	}));
+	const vars = { id: input.recordId };
+	for (const { key, variable } of keys) vars[variable] = input.data[key];
+	return {
+		query: surql.seal(surql.tx([surql.createSet("id", keys)]), { resultIndex: 0 }),
+		vars
+	};
+}
+/** Undo a peer's create the server never confirmed: the row alone, no outbox entry. */
+function planPeerUndoTx(recordId) {
+	return {
+		query: surql.seal(surql.tx([surql.delete("id")])),
+		vars: { id: recordId }
+	};
+}
+/**
 * Debounced update: bump `_00_rv` and MERGE now; the outbox row comes later.
 * With a `mirror`, the merged patch so far is written to `_00_pending_writes`
 * in the same transaction, so the row never changes without a durable copy of
@@ -2286,8 +3650,8 @@ function trimHistory(history, cap) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.355";
-const WASM_VERSION = "0.0.1-canary.355";
+const CORE_VERSION = "0.0.1-canary.357";
+const WASM_VERSION = "0.0.1-canary.357";
 const SURREAL_VERSION = "3.1.0";
 var DevToolsService = class DevToolsService {
 	version = CORE_VERSION;
@@ -3521,6 +4885,25 @@ const outboxReplace = (items) => (s) => {
 	for (const table of tables) next = markTableDirty(table)(next);
 	return next;
 };
+/** A channel peer's create or delete is now showing; its table re-renders. */
+const setPeerWrite = (id, write) => (s) => {
+	const peerWrites = new Map(s.peerWrites);
+	peerWrites.set(id, write);
+	return markTableDirty(write.table)({
+		...s,
+		peerWrites
+	});
+};
+const clearPeerWrite = (id) => (s) => {
+	const write = s.peerWrites.get(id);
+	if (!write) return s;
+	const peerWrites = new Map(s.peerWrites);
+	peerWrites.delete(id);
+	return markTableDirty(write.table)({
+		...s,
+		peerWrites
+	});
+};
 const outboxPush = (item) => (s) => markTableDirty(item.table)({
 	...s,
 	outbox: [...s.outbox, item]
@@ -3654,6 +5037,7 @@ const clearBucketState = () => (s) => ({
 	views: /* @__PURE__ */ new Map(),
 	outbox: [],
 	pendingWrites: /* @__PURE__ */ new Map(),
+	peerWrites: /* @__PURE__ */ new Map(),
 	dirty: /* @__PURE__ */ new Set(),
 	membershipDirty: /* @__PURE__ */ new Set(),
 	membershipReread: /* @__PURE__ */ new Map(),
@@ -3722,6 +5106,8 @@ function overlay(s) {
 	const deletes = /* @__PURE__ */ new Set();
 	for (const item of s.outbox) if (item.type === "delete") deletes.add(item.recordId);
 	else writes.add(item.recordId);
+	for (const [id, write] of s.peerWrites) if (write.kind === "delete") deletes.add(id);
+	else writes.add(id);
 	return {
 		writes,
 		deletes
@@ -4212,6 +5598,7 @@ function emptyState(init) {
 		views: /* @__PURE__ */ new Map(),
 		outbox: [],
 		pendingWrites: /* @__PURE__ */ new Map(),
+		peerWrites: /* @__PURE__ */ new Map(),
 		failedCount: 0,
 		dirty: /* @__PURE__ */ new Set(),
 		membershipDirty: /* @__PURE__ */ new Set(),
@@ -5868,6 +7255,152 @@ function* adoptPendingWrites() {
 	if (adopted > 0) yield fx.dispatch({ type: "Drain" });
 	if (recheckAt !== Infinity) yield fx.timer.set("adopt-writes", recheckAt - now, { type: "AdoptPendingWrites" });
 }
+/** The row as the local store holds it, or null: what a channel checks its filter against. */
+function* readRow(recordId) {
+	return yield* readBefore(parseRecordIdString(recordId));
+}
+/**
+* A channel peer created a row: put it in the store and the circuit like an
+* own optimistic create, minus the outbox entry (the peer pushes it), and
+* show it through the overlay. `_00_rv` stays unset on purpose: the server's
+* body (with its computed fields) still downloads and replaces this one.
+* Refuses an id this client already holds a confirmed row or an own pending
+* write for, so a peer can never overwrite real data. Returns whether it applied.
+*/
+function* peerCreate(env, input) {
+	const table = extractTablePart(input.recordId);
+	const columns = columnsFor(env, table);
+	if (!columns) return false;
+	const [confirmed, ownPending, peerPending] = yield fx.state.read((s) => [
+		s.versions.has(input.recordId),
+		s.outbox.some((i) => i.recordId === input.recordId),
+		s.peerWrites.has(input.recordId)
+	]);
+	if (confirmed || ownPending || peerPending) return false;
+	const rid = parseRecordIdString(input.recordId);
+	const existing = yield* readBefore(rid);
+	let record = existing;
+	if (!existing) {
+		const tx = planPeerCreateTx({
+			recordId: rid,
+			data: parseParams(columns, input.data ?? {})
+		});
+		try {
+			const res = yield fx.local.execute(tx.query, tx.vars);
+			record = res && typeof res === "object" && !Array.isArray(res) ? res : null;
+		} catch (error) {
+			yield fx.emit({
+				type: "log",
+				level: "debug",
+				message: "peer create refused by the local store",
+				data: {
+					recordId: input.recordId,
+					error
+				}
+			});
+			return false;
+		}
+	}
+	if (!record) return false;
+	try {
+		yield fx.ssp.ingest([{
+			table,
+			op: "CREATE",
+			id: input.recordId,
+			record: {
+				...record,
+				_00_rv: 0
+			}
+		}]);
+	} catch (error) {
+		yield fx.emit({
+			type: "log",
+			level: "error",
+			message: "circuit ingest failed after a peer create",
+			data: {
+				recordId: input.recordId,
+				error
+			}
+		});
+	}
+	const now = yield fx.now();
+	yield fx.state.update(setPeerWrite(input.recordId, {
+		kind: "create",
+		table,
+		expiresAt: now + input.ttlMs
+	}));
+	yield fx.timer.set(`peer:${input.recordId}`, input.ttlMs, {
+		type: "PeerWriteExpired",
+		id: input.recordId
+	});
+	return true;
+}
+/**
+* A channel peer deleted a row: hide it through the overlay, keep it in the
+* store. Undoing is then just forgetting the entry; a confirmed delete has
+* taken the row out of the server's membership by the time it expires.
+*/
+function* peerDelete(env, input) {
+	const table = extractTablePart(input.recordId);
+	if (!columnsFor(env, table)) return false;
+	const [known, confirmed] = yield fx.state.read((s) => [s.peerWrites.get(input.recordId), s.versions.has(input.recordId)]);
+	if (known?.kind === "create" && !confirmed) {
+		yield fx.timer.clear(`peer:${input.recordId}`);
+		yield* undoPeerCreate(table, input.recordId);
+		return true;
+	}
+	if (!((yield* readBefore(parseRecordIdString(input.recordId))) !== null)) return false;
+	const now = yield fx.now();
+	yield fx.state.update(setPeerWrite(input.recordId, {
+		kind: "delete",
+		table,
+		expiresAt: now + input.ttlMs
+	}));
+	yield fx.timer.set(`peer:${input.recordId}`, input.ttlMs, {
+		type: "PeerWriteExpired",
+		id: input.recordId
+	});
+	return true;
+}
+/** Timer target: a peer's write stops showing as unconfirmed. */
+function* peerWriteExpired(id) {
+	const [write, confirmed, ownPending] = yield fx.state.read((s) => [
+		s.peerWrites.get(id),
+		s.versions.has(id),
+		s.outbox.some((i) => i.recordId === id)
+	]);
+	if (!write) return;
+	if (write.kind === "create" && !confirmed && !ownPending) {
+		yield* undoPeerCreate(write.table, id);
+		return;
+	}
+	yield fx.state.update(clearPeerWrite(id));
+}
+function* undoPeerCreate(table, id) {
+	const rid = parseRecordIdString(id);
+	const before = yield* readBefore(rid);
+	try {
+		const tx = planPeerUndoTx(rid);
+		yield fx.local.execute(tx.query, tx.vars);
+		if (before) yield fx.ssp.ingest([{
+			table,
+			op: "DELETE",
+			id,
+			record: before
+		}]);
+	} catch (error) {
+		yield fx.emit({
+			type: "log",
+			level: "warn",
+			message: "could not undo an unconfirmed peer create",
+			data: {
+				recordId: id,
+				error
+			}
+		});
+	}
+	yield fx.state.update(clearPeerWrite(id));
+}
 
 //#endregion
 //#region src/mutation/tray.saga.ts
@@ -6965,7 +8498,10 @@ function* materialize(hash) {
 	let rows;
 	try {
 		rows = rowsFromResult(effect, yield effect);
-		if (ids === null) rows = rows.filter((row) => paints(rowKey$1(row)));
+		if (ids === null) rows = rows.filter((row) => {
+			const key = rowKey$1(row);
+			return paints(key) && !(key !== null && ov.deletes.has(key));
+		});
 	} catch (error) {
 		yield fx.state.update(compose(recordError(hash), clearDirty(hash)));
 		yield fx.emit({
@@ -7670,6 +9206,10 @@ function route(env, event) {
 			saga: flushWrite(env, event.key),
 			lane: serial("outbox-write")
 		};
+		case "PeerWriteExpired": return {
+			saga: peerWriteExpired(event.id),
+			lane: serial(`peer:${event.id}`)
+		};
 		case "FlushPendingWrites": return { saga: flushPendingWrites() };
 		case "AdoptPendingWrites": return {
 			saga: adoptPendingWrites(),
@@ -16069,7 +17609,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.355",
+			coreVersion: "0.0.1-canary.357",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -16685,6 +18225,8 @@ var Sp00kyClient = class {
 	streamProcessor;
 	/** Web Push for this browser: subscribe, devices, self-pushes, service worker bridge. */
 	webPush;
+	/** Peer to peer channels of `-- @channel` tables. */
+	channels;
 	services;
 	env;
 	runtime;
@@ -16787,6 +18329,29 @@ var Sp00kyClient = class {
 			config: config.webPush
 		});
 		this.disposers.push(this.webPush.attach());
+		const channelsConfig = config.channels;
+		this.channels = new ChannelManager(config.schema, {
+			config: channelsConfig,
+			logger: s.logger,
+			rows: {
+				create: (_table, id, row, ttlMs) => this.runtime.run(peerCreate(this.env, {
+					recordId: id,
+					data: row,
+					ttlMs
+				})),
+				delete: (_table, id, ttlMs) => this.runtime.run(peerDelete(this.env, {
+					recordId: id,
+					ttlMs
+				})),
+				read: (id) => this.runtime.run(readRow(id))
+			},
+			transport: channelsConfig?.transport ?? ((hooks) => webrtcTransport(hooks, {
+				signal: surrealSignal(s.remote, s.connectionSupervisor, s.logger),
+				iceServers: channelsConfig?.iceServers,
+				logger: s.logger
+			}))
+		});
+		if (this.channels.enabled) this.disposers.push(s.auth.subscribe((userId) => this.channels.setUser(userId)));
 		this.devTools = new DevToolsService(s.local, s.remote, s.logger, config.schema, s.auth, {
 			getActiveQueries: () => [...this.runtime.state.queries.values()].map(toQueryState),
 			getQueryById: (id) => {
@@ -16940,6 +18505,7 @@ var Sp00kyClient = class {
 		const s = this.services;
 		s.connectionSupervisor.dispose();
 		for (const dispose of this.disposers.splice(0)) dispose();
+		this.channels.close();
 		this.runtime.dispose();
 		await this.featureFlags.closeAll();
 		await this.appReleases.closeAll();
@@ -17003,7 +18569,50 @@ var Sp00kyClient = class {
 		await this.runtime.run(preload(this.env, this.registerInput(q.tableName, q, "10m")), { signal: options?.signal });
 	}
 	async subscribe(queryHash, callback, options) {
-		return this.runtime.subscribe(queryHash, callback, options);
+		if (!this.channels.enabled) return this.runtime.subscribe(queryHash, callback, options);
+		const tap = this.channels.tap(callback);
+		const stop = this.runtime.subscribe(queryHash, tap.feed, options);
+		return () => {
+			stop();
+			tap.stop();
+		};
+	}
+	/**
+	* Open a peer to peer channel to `peers` (your own id is skipped; a
+	* connection forms only when both sides list each other) for the rows
+	* `queries` match, each a query on a `-- @channel` table. Only its `where`
+	* counts, evaluated against each row; the query is never registered. Writes
+	* to matching rows (plain or the channel's own) reach the peers. Close it
+	* when done.
+	*/
+	channel(queries, peers) {
+		const handle = this.channels.open(this.channelScopes(queries), peers);
+		const scoped = (table) => {
+			this.channels.assertCarries(handle, table);
+			return handle;
+		};
+		return {
+			tables: handle.tables,
+			state: handle.state,
+			subscribe: handle.subscribe,
+			setPeers: handle.setPeers,
+			setQueries: (next) => handle.setScopes(this.channelScopes(next)),
+			close: handle.close,
+			update: (table, id, data, options) => this.writeUpdate(table, id, data, options, scoped(table)),
+			create: (id, data) => this.writeCreate(id, data, scoped(id.slice(0, id.indexOf(":")))),
+			delete: (table, id) => this.writeDelete(table, id, scoped(table))
+		};
+	}
+	channelScopes(queries) {
+		return (Array.isArray(queries) ? queries : [queries]).map((q) => {
+			const final = "build" in q && typeof q.build === "function" ? q.build() : q;
+			const plan = final.innerQuery?.selectQuery?.plan;
+			if (!plan) throw new Error("channel(): pass a query, e.g. db.query('message').where({ conversation })");
+			return this.channels.scope(plan, {
+				isOne: final.isOne,
+				ignoreUnused: final.ignoresUnusedArgs
+			});
+		});
 	}
 	deregisterQuery(queryHash) {
 		const entry = this.runtime.state.queries.get(queryHash);
@@ -17023,21 +18632,44 @@ var Sp00kyClient = class {
 		if (Number.isFinite(ms)) this.runtime.update(recordPhase(queryHash, "frontend", ms));
 	}
 	async create(id, data) {
-		return (await this.runtime.run(write(this.env, {
-			kind: "create",
-			recordId: id,
-			data
-		}))).record ?? data;
+		return await this.writeCreate(id, data);
 	}
-	async update(_table, id, data, options) {
-		return (await this.runtime.run(write(this.env, {
-			kind: "update",
-			recordId: id,
-			data,
-			options
-		}))).record ?? data;
+	async update(table, id, data, options) {
+		return await this.writeUpdate(table, id, data, options);
+	}
+	async delete(table, id) {
+		await this.writeDelete(table, id);
+	}
+	async writeCreate(id, data, scope) {
+		const table = id.slice(0, id.indexOf(":"));
+		const { persistent, ephemeral } = this.channels.split(table, data);
+		this.channels.localCreate(table, id, data, scope);
+		return {
+			...(await this.runtime.run(write(this.env, {
+				kind: "create",
+				recordId: id,
+				data: persistent
+			}))).record ?? persistent,
+			...ephemeral ?? {}
+		};
+	}
+	async writeUpdate(table, id, data, options, scope) {
+		const tableName = table || id.slice(0, id.indexOf(":"));
+		const { persistent, ephemeral } = this.channels.split(tableName, data);
+		this.channels.local(tableName, id, persistent, ephemeral, scope);
+		if (ephemeral && Object.keys(persistent).length === 0) return data;
+		return {
+			...(await this.runtime.run(write(this.env, {
+				kind: "update",
+				recordId: id,
+				data: persistent,
+				options
+			}))).record ?? persistent,
+			...ephemeral ?? {}
+		};
 	}
-	async delete(_table, id) {
+	async writeDelete(table, id, scope) {
+		await this.channels.localDelete(table || id.slice(0, id.indexOf(":")), id, scope);
 		await this.runtime.run(write(this.env, {
 			kind: "delete",
 			recordId: id
@@ -17191,4 +18823,4 @@ var Sp00kyClient = class {
 };
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, FeatureFlagHandle, FeatureFlagModule, IMPERSONATION_ACCESS, ImpersonationTimers, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, ORIGIN_TOKEN_KEY, PUSH_ENDPOINT_KEY, PUSH_PAYLOAD_VERSION, REFUSAL_RECHECK_MIN_MS, SESSION_POLL_MS, SIGN_OUT_HOOK_TIMEOUT_MS, Sp00kyClient, WebPushError, WebPushModule, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, decodeTokenClaims, detectWebPushSupport, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, impersonationFromToken, isBlurhashValid, isImagePath, isPushPayload, renewDelayMs, sameImpersonation, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, FeatureFlagHandle, FeatureFlagModule, IMPERSONATION_ACCESS, ImpersonationTimers, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, ORIGIN_TOKEN_KEY, PUSH_ENDPOINT_KEY, PUSH_PAYLOAD_VERSION, REFUSAL_RECHECK_MIN_MS, SESSION_POLL_MS, SIGN_OUT_HOOK_TIMEOUT_MS, Sp00kyClient, WebPushError, WebPushModule, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, decodeTokenClaims, detectWebPushSupport, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, impersonationFromToken, isBlurhashValid, isImagePath, isPushPayload, matchesWhere, renewDelayMs, sameImpersonation, semverGt, surrealSignal, textToHtml, unusedArgs, webrtcTransport };