@mengine/medeo-client 2.1.1-dsl.9 → 3.0.0

package/dist/index.js

@@ -1,10 +1,456 @@
 import { n as bytesToBase64, t as base64ToBytes } from "./base64-D-jd-dr5.js";
-import { a as covers, c as readMengineEventStream, d as MenginePushRejectedError, i as openManualDocument, l as MengineHttpClient, n as MedeoHttpDocStorage, o as decodeDocVersionMark, r as ManualSyncTransport, s as encodeDocVersionMark, t as MemoryDocStorage, u as MengineHttpRequestError } from "./storage-BW3tI_ER.js";
-import { _t as tupleHash, a as documentFormat, c as isInvalidAtomic, gt as resourceId, ht as relationId, i as assertDslDocument, mt as defaultIdFactory, o as medeoDslLoroShape, r as UnsupportedDocumentFormatError, s as captionContentCodec, t as DEFAULT_UNIT_TIME_MS, u as timeAnchorCodec } from "./video-draft-types-BnbfWrBx.js";
-import { a as DslEditor, c as DslProjectionError, i as createInitialMedeoDsl, n as toVideoDraft, o as MedeoDsl, r as toAudioScriptViews, s as resolveDslLayout, t as fromVideoDraft } from "./dsl-COyzz7Fp.js";
-import { UndoManager, VersionVector, decodeImportBlobMeta } from "loro-crdt";
+import { _ as defaultIdFactory, a as DslEditor, b as tupleHash, c as UnsupportedDocumentFormatError, d as medeoDslLoroShape, f as captionContentCodec, g as DslProjectionError, h as resolveDslLayout, i as createInitialMedeoDsl, l as assertDslDocument, m as timeAnchorCodec, n as toVideoDraft, o as toAudioScriptViews, p as isInvalidAtomic, r as DEFAULT_UNIT_TIME_MS, s as MedeoDsl, t as fromVideoDraft, u as documentFormat, v as relationId, y as resourceId } from "./dsl-Cpk8WxcZ.js";
+import { LoroDoc, UndoManager, VersionVector, decodeImportBlobMeta } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
-import { DisposableSet, EventBus } from "@mengine/utils";
+import { DisposableSet, EventBus, Task } from "@mengine/utils";
+import { BaseDocStorage, DummyConnection } from "@mengine/storage";
+//#region src/client/http-client.ts
+/**
+* Public route prefix of the mengine doc-collaboration API. Must stay in lockstep
+* with `apps/mengine-server`'s `API_PREFIX` — the two form the private wire
+* contract between this client and the relay server. Versioned, mengine-owned
+* namespace (mirrors the cluster's `/oapi/v1` precedent for an independent
+* subsystem) rather than folding into the shared `/api/v2/*` space.
+*/
+const MENGINE_API_PREFIX = "/api/mengine/v1";
+var MengineHttpRequestError = class extends Error {
+	status;
+	payload;
+	constructor(status, payload) {
+		super(`mengine request failed: ${status}`);
+		this.status = status;
+		this.payload = payload;
+		this.name = "MengineHttpRequestError";
+	}
+};
+/**
+* A push the server refused on its merits (`kind: 'rejected'`), as opposed to a
+* transport failure. Carries the server's machine `code` so callers can branch on
+* *why* rather than on an HTTP status:
+*
+* - `missing_dependency` (server answers 409) — retryable: the update depends on
+*   ops the server log lacks, so catching up and re-exporting resolves it.
+* - `corrupt_update` (server answers 422) — never valid, retrying cannot help.
+*
+* Distinct from {@link MengineHttpRequestError} (transport/status-level failure)
+* and from a raw `fetch` rejection (network down): the three are separate classes
+* so a caller can tell "the server said no" from "the server never answered".
+*/
+var MenginePushRejectedError = class extends Error {
+	code;
+	serverMessage;
+	serverVersion;
+	status;
+	constructor(code, serverMessage, serverVersion, status) {
+		super(`mengine rejected update: ${code}: ${serverMessage}`);
+		this.code = code;
+		this.serverMessage = serverMessage;
+		this.serverVersion = serverVersion;
+		this.status = status;
+		this.name = "MenginePushRejectedError";
+	}
+};
+var MengineHttpClient = class {
+	options;
+	fetchImpl;
+	constructor(options) {
+		this.options = options;
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+	}
+	async fetchSnapshot() {
+		return await this.requestJson("snapshot");
+	}
+	/** Read-only compatibility content and diagnostics at the same causal version. */
+	async fetchDraft() {
+		return this.requestJson("draft");
+	}
+	async fetchDraftAt(updateSeq) {
+		if (!Number.isSafeInteger(updateSeq) || updateSeq < 0) throw new Error("Invalid revision");
+		return this.requestJson(`revisions/${updateSeq}/draft`);
+	}
+	/**
+	* Loro VV-diff pull: send the caller's oplog `VersionVector.encode` as `from`
+	* (omit for a full pull) and receive exactly the updates it is missing plus
+	* the server's current VV. Replaces the old integer `after_update_id` cursor.
+	*/
+	async sync(fromVV) {
+		const query = fromVV != null ? `?from=${encodeURIComponent(bytesToBase64(fromVV))}` : "";
+		return await this.requestJson(`sync${query}`);
+	}
+	/** Audit trail: extracted metadata per accepted update, in log order. */
+	async audit() {
+		return await this.requestJson("audit");
+	}
+	/**
+	* Append one Loro update to the server log.
+	*
+	* Resolves for both accepted outcomes and hands the verdict back verbatim —
+	* `ack` (appended, `update_seq` allocated) and `duplicate` (already known, no
+	* row appended). A `duplicate` is NOT an error, but it is also not an ack: it
+	* means the bytes contributed nothing, so a caller waiting for its own write to
+	* land must be able to tell them apart. Hence the verdict is returned rather
+	* than collapsed into `void`.
+	*
+	* Rejections raise {@link MenginePushRejectedError} carrying the server's
+	* machine `code`. The server answers them with 409/422, so the failure arrives
+	* as a non-ok response; this method re-reads the parsed body to recover `code` /
+	* `server_version` instead of leaving the caller a bare status. Transport-level
+	* failures stay {@link MengineHttpRequestError}, and a dead network keeps
+	* surfacing as the underlying `fetch` rejection.
+	*/
+	async pushUpdate(update) {
+		let response;
+		try {
+			response = await this.requestJson("updates", {
+				method: "POST",
+				body: JSON.stringify({ update: bytesToBase64(update) })
+			});
+		} catch (error) {
+			throw asPushRejection(error) ?? error;
+		}
+		if (response.kind === "rejected") throw new MenginePushRejectedError(response.code, response.message, response.server_version, void 0);
+		return response;
+	}
+	eventsUrl() {
+		return this.endpoint("events");
+	}
+	headers() {
+		const headers = new Headers();
+		headers.set("accept", "application/json");
+		headers.set("content-type", "application/json");
+		const authToken = typeof this.options.authToken === "function" ? this.options.authToken() : this.options.authToken;
+		if (authToken != null && authToken !== "") headers.set("authorization", `Bearer ${authToken}`);
+		const userId = typeof this.options.userId === "function" ? this.options.userId() : this.options.userId;
+		if (userId != null && userId !== "") headers.set("medeo-user-id", userId);
+		return headers;
+	}
+	async fetch(input, init) {
+		return await this.fetchImpl(input, init);
+	}
+	async requestJson(path, init = {}) {
+		const headers = this.headers();
+		new Headers(init.headers).forEach((value, key) => {
+			headers.set(key, value);
+		});
+		const response = await this.fetchImpl(this.endpoint(path), {
+			...init,
+			headers
+		});
+		const payload = await safeReadJson(response);
+		if (!response.ok) throw new MengineHttpRequestError(response.status, payload);
+		return payload;
+	}
+	endpoint(path) {
+		return `${this.options.httpOrigin.replace(/\/$/, "")}${MENGINE_API_PREFIX}/docs/${encodeURIComponent(this.options.docId)}/${path}`;
+	}
+};
+/**
+* Recover a typed rejection from a failed request: the server sends `rejected`
+* bodies with a 409/422 status, so they surface as {@link MengineHttpRequestError}
+* whose payload still carries the machine `code`. Returns `undefined` for any
+* other failure so the caller rethrows the original.
+*/
+function asPushRejection(error) {
+	if (!(error instanceof MengineHttpRequestError)) return void 0;
+	const payload = error.payload;
+	if (payload == null || typeof payload !== "object") return void 0;
+	const body = payload;
+	if (body.kind !== "rejected" || typeof body.code !== "string") return void 0;
+	return new MenginePushRejectedError(body.code, body.message ?? "", body.server_version, error.status);
+}
+async function safeReadJson(response) {
+	const text = await response.text();
+	if (text.length === 0) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+//#endregion
+//#region src/client/sse.ts
+async function readMengineEventStream(options) {
+	const response = await options.client.fetch(options.client.eventsUrl(), {
+		headers: options.client.headers(),
+		signal: options.signal
+	});
+	if (!response.ok) throw new Error(`mengine event stream failed: ${response.status}`);
+	const reader = response.body?.getReader();
+	if (reader == null) throw new Error("mengine event stream response has no readable body");
+	options.onOpen?.();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	while (options.signal?.aborted !== true) {
+		const { done, value } = await reader.read();
+		if (done) return;
+		buffer += decoder.decode(value, { stream: true });
+		let splitAt = findSseFrameBoundary(buffer);
+		while (splitAt >= 0) {
+			const frame = buffer.slice(0, splitAt);
+			buffer = buffer.slice(buffer[splitAt] === "\r" ? splitAt + 4 : splitAt + 2);
+			handleSseFrame(frame, options);
+			splitAt = findSseFrameBoundary(buffer);
+		}
+	}
+}
+function handleSseFrame(frame, options) {
+	const event = parseSseFrame(frame);
+	if (event.event === "resync") {
+		options.onResync?.();
+		return;
+	}
+	if (event.event !== "update" || event.data.length === 0) return;
+	options.onUpdate(JSON.parse(event.data.join("\n")));
+}
+function parseSseFrame(frame) {
+	let event = null;
+	const data = [];
+	for (const line of frame.split(/\r?\n/)) if (line.startsWith("event:")) event = line.slice(6).trim();
+	else if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+	return {
+		event,
+		data
+	};
+}
+function findSseFrameBoundary(buffer) {
+	const lf = buffer.indexOf("\n\n");
+	const crlf = buffer.indexOf("\r\n\r\n");
+	if (lf < 0) return crlf;
+	if (crlf < 0) return lf;
+	return Math.min(lf, crlf);
+}
+//#endregion
+//#region src/manual-sync/doc-version-mark.ts
+/**
+* Encode a {@link DocVersionMark} for storage or transport.
+*
+* The mark stays opaque across the round trip — the string is not a version
+* number and must not be compared, ordered, or parsed. Its only use is
+* {@link decodeDocVersionMark} followed by `hasChangedSince`.
+*
+* Callers that persist this should know the encoded length grows with the number
+* of peers that have ever written to the document (one counter each), and the FE
+* mints a fresh peer per page load. Still small in practice (a few hundred bytes
+* for dozens of peers), but it grows with document age rather than size; version
+* vector compaction is deferred to a later phase.
+*/
+function encodeDocVersionMark(mark) {
+	return bytesToBase64(mark.encoded);
+}
+/**
+* Rebuild a mark from {@link encodeDocVersionMark}'s output.
+*
+* Returns `undefined` for input this did not produce (a legacy integer version,
+* a truncated value, an empty string). That is the honest answer — "I cannot
+* establish what you last saw" — and callers should treat it as "no baseline"
+* rather than as "unchanged". Decoding does not validate the bytes as a version
+* vector; `hasChangedSince` reports "changed" for an undecodable mark, which is
+* the conservative direction.
+*/
+function decodeDocVersionMark(encoded) {
+	if (encoded === "") return void 0;
+	try {
+		return {
+			__brand: "mengine-doc-version-mark",
+			encoded: base64ToBytes(encoded)
+		};
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/manual-sync/version-coverage.ts
+/**
+* Version-vector coverage: "does `outer` contain everything in `inner`?"
+*
+* This one predicate answers three different questions in the manual-sync document, which
+* is why it is factored out rather than inlined three times:
+*
+* | question                              | call                            |
+* | ------------------------------------- | ------------------------------- |
+* | is there anything left to push?       | `covers(watermark, localOplog)`  |
+* | did someone else write concurrently?  | `covers(localOplog, serverVV)`   |
+* | has the doc moved since I last read?  | `covers(seenVersion, localOplog)`|
+*
+* `VersionVector.compare` cannot be used for any of them: it returns `undefined`
+* for concurrent vectors, and concurrency is the NORMAL case here — the server
+* routinely holds peers the local doc has never seen, and after a collaborative
+* merge the local doc holds ops the watermark predates. Treating "concurrent" as
+* "not covered" is right for some of these and wrong for others, so the per-peer
+* counter check is the only formulation that stays correct for all three.
+*
+* Equality must NOT be used as a substitute either: once collaboration happens
+* the watermark legitimately *leads* the local doc (it carries other peers'
+* counters), so an equality test reports "still has ops to push" forever.
+*/
+function covers(outer, inner) {
+	for (const [peer, counter] of inner.toJSON()) if ((outer.get(peer) ?? 0) < counter) return false;
+	return true;
+}
+//#endregion
+//#region src/manual-sync/manual-sync-transport.ts
+/** Shared explicit pull/push lifecycle; model-specific editors never implement transport. */
+var ManualSyncTransport = class {
+	client;
+	doc;
+	watermark;
+	disposed = false;
+	constructor(client, doc, watermark) {
+		this.client = client;
+		this.doc = doc;
+		this.watermark = watermark;
+	}
+	editorPeerId() {
+		this.assertActive();
+		return this.doc.peerIdStr;
+	}
+	assertActive() {
+		if (this.disposed) throw new Error("ManualSyncDoc is disposed");
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.doc.free();
+	}
+	/**
+	* Mark the document state the caller has just observed, for a later
+	* {@link hasChangedSince}.
+	*
+	* This pair replaces the legacy integer-version comparison that
+	* `DraftVersionDetector` used to tell the LLM "the draft was modified
+	* externally, reload before editing". Comparing Loro version vectors covers
+	* all collaborative edits without a business revision field in the document.
+	*
+	* Same capability, not a stronger one: like the legacy detector, this only
+	* reports what changed between two moments the caller chose to sample.
+	*/
+	versionMark() {
+		this.assertActive();
+		return {
+			__brand: "mengine-doc-version-mark",
+			encoded: this.doc.oplogVersion().encode()
+		};
+	}
+	/**
+	* Has the document moved since `mark` was taken?
+	*
+	* Reports any advance, whoever caused it — including this document's own edits.
+	* The caller decides what is interesting: a detector sampling once per turn is
+	* asking "did anything happen", and its own edits legitimately count.
+	*/
+	hasChangedSince(mark) {
+		this.assertActive();
+		let previous;
+		try {
+			previous = VersionVector.decode(mark.encoded);
+		} catch {
+			return true;
+		}
+		return !covers(previous, this.doc.oplogVersion());
+	}
+	/**
+	* Fetch and merge everything the server has that this document lacks.
+	*
+	* Must run *before* the editor on each tool call. The editor validates
+	* against the local document, so editing a stale one validates against a world
+	* that no longer exists: the ADR 0015 spike confirmed that without pull-first
+	* an edit to a clip another writer had already deleted passes validation and is
+	* accepted by the server. Pulling afterwards cannot undo that.
+	*
+	* A failure is returned, not thrown — a transient network blip must not make
+	* the tool unusable (M2/A ruling; legacy tolerates read failures the same way).
+	* The caller proceeds on a possibly-stale document knowingly.
+	*/
+	async pull() {
+		this.assertActive();
+		const before = this.doc.oplogVersion();
+		try {
+			const response = await this.client.sync(before.encode());
+			this.assertActive();
+			const update = base64ToBytes(response.update);
+			if (update.byteLength > 0) this.doc.import(update);
+			return {
+				ok: true,
+				changed: !covers(before, this.doc.oplogVersion())
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				reason: "failed",
+				error: error instanceof Error ? error : new Error(String(error))
+			};
+		}
+	}
+	/**
+	* Push every local op the server has not confirmed, and report the verdict.
+	*
+	* The return value is the durability answer a tool needs before claiming
+	* success: only `ack` / `duplicate` mean the server holds the ops. This is why
+	* this class exists rather than an ack-waiter — with a direct call, "did it
+	* land" is simply the result.
+	*
+	* `duplicate` counts as durable: the bytes added nothing *because* the server
+	* already had them.
+	*/
+	async push() {
+		this.assertActive();
+		const localVersion = this.doc.oplogVersion();
+		if (covers(this.watermark, localVersion)) return {
+			kind: "nothing_to_push",
+			collaborated: false
+		};
+		const update = this.doc.export({
+			mode: "update",
+			from: this.watermark
+		});
+		try {
+			const response = await this.client.pushUpdate(update);
+			const serverVV = this.serverVVFrom(response.version?.server_vv);
+			if (serverVV != null) this.watermark = serverVV;
+			return {
+				kind: response.kind,
+				mengineUpdateSeq: response.version?.update_seq ?? response.update_seq ?? void 0,
+				updateSeq: response.update_seq ?? void 0,
+				collaborated: serverVV != null && !covers(localVersion, serverVV)
+			};
+		} catch (error) {
+			const failure = error instanceof Error ? error : new Error(String(error));
+			const rejected = error instanceof MenginePushRejectedError;
+			return {
+				kind: rejected ? "rejected" : "failed",
+				collaborated: false,
+				code: rejected ? error.code : void 0,
+				error: failure
+			};
+		}
+	}
+	/** Decode a wire `server_vv`, tolerating absence/corruption (never throws). */
+	serverVVFrom(serverVV) {
+		if (serverVV == null || serverVV === "") return void 0;
+		try {
+			return VersionVector.decode(base64ToBytes(serverVV));
+		} catch {
+			return;
+		}
+	}
+};
+async function openManualDocument(options, create) {
+	const response = await options.client.fetchSnapshot();
+	const doc = new LoroDoc();
+	try {
+		if (options.peerId !== void 0) doc.setPeerId(options.peerId);
+		if (doc.import(base64ToBytes(response.snapshot)).pending != null) throw new Error("Initial mengine snapshot has missing dependencies");
+		let watermark = doc.oplogVersion();
+		try {
+			if (response.version.server_vv) watermark = VersionVector.decode(base64ToBytes(response.version.server_vv));
+		} catch {}
+		return create(doc, watermark);
+	} catch (error) {
+		doc.free();
+		throw error;
+	}
+}
+//#endregion
 //#region src/manual-sync/manual-sync-doc.ts
 /** Explicit synchronization over the same DSL/editor used by the live Session. */
 var ManualSyncDoc = class ManualSyncDoc extends ManualSyncTransport {
@@ -33,6 +479,355 @@ var ManualSyncDoc = class ManualSyncDoc extends ManualSyncTransport {
 	}
 };
 //#endregion
+//#region src/storage/medeo-http-doc-storage.ts
+/**
+* SSE-backed {@link Connection} for the mengine-server document stream.
+*
+* It owns the live SSE read loop and reflects its lifecycle as connection
+* status: `connecting` while (re)establishing, `connected` once the stream is
+* open, back to `connecting` on a drop (auto-reconnect), `closed` on
+* `disconnect`. Reporting a drop as a status change is the whole point — the
+* synchronizer watches `onStatusChanged` and, on any change, tears down and
+* re-runs its connect cycle, which re-issues `getDocDiff(doc.version())` and so
+* recovers whatever the stream missed while it was down. Recovery therefore
+* lives in the synchronizer (keyed on the real doc version), not here.
+*
+* Update frames are forwarded via `onUpdate`, resync hints via `onResync`; this
+* connection keeps no version cursor and does no catch-up of its own. Dedup is
+* unnecessary because `LoroDoc.import` is idempotent by OpId/VV.
+*/
+var SseConnection = class {
+	client;
+	onUpdate;
+	onResync;
+	reconnectDelayMs;
+	inner = void 0;
+	event = new EventBus();
+	streamTask = null;
+	_status = "idle";
+	_error;
+	constructor(client, onUpdate, onResync, reconnectDelayMs) {
+		this.client = client;
+		this.onUpdate = onUpdate;
+		this.onResync = onResync;
+		this.reconnectDelayMs = reconnectDelayMs;
+	}
+	get status() {
+		return this._status;
+	}
+	get error() {
+		return this._error;
+	}
+	connect() {
+		if (this.streamTask != null) return;
+		const task = Task.spawn((scope) => this.runStreamLoop(scope.signal));
+		this.streamTask = task;
+		const release = () => {
+			if (this.streamTask === task) this.streamTask = null;
+		};
+		task.then(release, release);
+	}
+	disconnect() {
+		this.streamTask?.cancel();
+		this.streamTask = null;
+		this.setStatus("closed");
+	}
+	waitForConnected() {
+		return new Task((resolve, reject, scope) => {
+			if (this._status === "connected") {
+				resolve();
+				return;
+			}
+			const off = this.onStatusChanged((status, error) => {
+				if (status === "connected") {
+					off();
+					resolve();
+				} else if (status === "closed") {
+					off();
+					reject(error ?? /* @__PURE__ */ new Error("SSE connection closed"));
+				}
+			});
+			scope.disposer.add(off);
+		});
+	}
+	onStatusChanged(cb) {
+		return this.event.on("statusChanged", ({ status, error }) => cb(status, error));
+	}
+	setStatus(status, error) {
+		if (this._status === status && this._error === error) return;
+		this._status = status;
+		this._error = error;
+		this.event.emit("statusChanged", {
+			status,
+			error
+		});
+	}
+	async runStreamLoop(signal) {
+		while (!signal.aborted) {
+			this.setStatus("connecting");
+			try {
+				await readMengineEventStream({
+					client: this.client,
+					signal,
+					onOpen: () => this.setStatus("connected"),
+					onResync: this.onResync,
+					onUpdate: (event) => {
+						for (const update of event.updates) this.onUpdate(update);
+					}
+				});
+				if (!signal.aborted) this.setStatus("connecting", /* @__PURE__ */ new Error("SSE stream closed"));
+			} catch (error) {
+				if (signal.aborted) break;
+				this.setStatus("connecting", error instanceof Error ? error : new Error(String(error)));
+			}
+			if (signal.aborted) break;
+			try {
+				await Task.delay(this.reconnectDelayMs).abortOn(signal);
+			} catch {
+				break;
+			}
+		}
+	}
+};
+/**
+* Adapts the mengine-server HTTP/SSE protocol to the engine `DocStorage`
+* contract so `ClientServerSynchronizer` can treat it as a remote peer.
+*
+* Deliberately thin (mirrors the socket `DocStorage` in the playground): it
+* forwards live SSE updates and exposes a version-vector diff, and keeps NO
+* sync state of its own.
+*
+* - `getDocDiff(docId, knownVersion)` pulls the server-computed VV-diff via
+*   `GET /sync?from=<vv>` — the synchronizer passes the real `doc.version()`, so
+*   the response carries exactly the ops the doc is missing. `getDoc` (full
+*   `/snapshot`) stays for cold start, when the caller holds no version yet.
+* - `pushDocUpdate` forwards a Loro update; the server appends it.
+* - `subscribeDocUpdate` registers a callback for live SSE updates. It does no
+*   catch-up and keeps no cursor: after an SSE drop the connection reports a
+*   status change, and the synchronizer re-runs its cycle to catch up via
+*   `getDocDiff(doc.version())`. `LoroDoc.import` is idempotent (OpId/VV), so
+*   re-forwarded or echoed updates are harmless.
+*
+* It is bound to a single `docId` because `MengineHttpClient` is per-document.
+*/
+var MedeoHttpDocStorage = class {
+	options;
+	connection;
+	client;
+	docId;
+	events = new EventBus();
+	constructor(options) {
+		this.options = options;
+		this.client = options.client;
+		this.docId = options.docId;
+		this.connection = new SseConnection(this.client, (update) => this.emitUpdate(update), () => this.events.emit("resync"), options.sseReconnectDelayMs ?? 500);
+	}
+	get isReadonly() {
+		return this.options.readonlyMode ?? false;
+	}
+	async getDoc(docId) {
+		this.assertDocId(docId);
+		const snapshot = await this.client.fetchSnapshot();
+		this.reportServerVersion(snapshot.version?.server_vv);
+		const now = /* @__PURE__ */ new Date();
+		return {
+			docId,
+			data: base64ToBytes(snapshot.snapshot),
+			createdAt: now,
+			updatedAt: now
+		};
+	}
+	async getDocDiff(docId, knownVersion) {
+		this.assertDocId(docId);
+		const response = await this.client.sync(knownVersion);
+		this.reportServerVersion(response.server_vv);
+		return {
+			docId,
+			missing: base64ToBytes(response.update),
+			version: base64ToBytes(response.server_vv)
+		};
+	}
+	/**
+	* Forward one update to the server, returning what the server says it now holds.
+	*
+	* The returned `server_vv` is the server's own statement about itself, computed
+	* inside the write transaction. A caller tracking "what the remote has" can
+	* adopt it directly, which is strictly better than inferring that bound from
+	* the pushed blob: it also covers ops other peers wrote, so those stop being
+	* re-sent on every later push. `ack` and `duplicate` both carry it.
+	*
+	* The verdict itself stays on {@link subscribePushOutcome}, which reports
+	* failures too — a return value cannot. Previously the verdict was read and
+	* dropped, so a `duplicate` (bytes contributed nothing) was indistinguishable
+	* from a successful write.
+	*
+	* The error is still rethrown after being published: the synchronizer treats a
+	* throw as "retry this cycle", and swallowing it here would strand the update.
+	* Publishing is therefore additive observability, not error handling.
+	*/
+	async pushDocUpdate(update, _origin) {
+		this.assertDocId(update.docId);
+		if (this.isReadonly) throw new Error(`MedeoHttpDocStorage is readonly; refusing to push ${update.docId}`);
+		if (update.data.byteLength === 0) return {};
+		try {
+			const response = await this.client.pushUpdate(update.data);
+			const serverVV = this.reportServerVersion(response.version?.server_vv);
+			this.events.emit("pushOutcome", {
+				kind: response.kind,
+				updateSeq: response.update_seq ?? void 0,
+				serverVV
+			});
+			return { version: serverVV };
+		} catch (error) {
+			const failure = error instanceof Error ? error : new Error(String(error));
+			const rejected = error instanceof MenginePushRejectedError;
+			this.events.emit("pushOutcome", {
+				kind: rejected ? "rejected" : "failed",
+				code: rejected ? error.code : void 0,
+				error: failure
+			});
+			throw error;
+		}
+	}
+	/**
+	* Observe the server's verdict for every pushed update, including failures.
+	*
+	* This is the loud channel the `void`-returning `DocStorage.pushDocUpdate`
+	* cannot express. Consumers that need "did my write land" (the agent's
+	* tool-level ack wait) subscribe here.
+	*/
+	subscribePushOutcome(callback) {
+		return this.events.on("pushOutcome", callback);
+	}
+	/** Observe live hints that require VV catch-up without replacing the SSE connection. */
+	subscribeResync(callback) {
+		return this.events.on("resync", callback);
+	}
+	/** Authoritative HTTP reads and accepted pushes, never inferred from SSE bytes. */
+	subscribeServerVersion(callback) {
+		return this.events.on("serverVersion", callback);
+	}
+	reportServerVersion(encoded) {
+		const version = decodeServerVV(encoded);
+		if (version != null) this.events.emit("serverVersion", version);
+		return version;
+	}
+	async deleteDoc(_docId) {
+		throw new Error("MedeoHttpDocStorage does not support deleteDoc");
+	}
+	subscribeDocUpdate(callback) {
+		return this.events.on("update", ({ update, origin }) => callback(update, origin));
+	}
+	assertDocId(docId) {
+		if (docId !== this.docId) throw new Error(`MedeoHttpDocStorage is bound to ${this.docId}, received ${docId}`);
+	}
+	emitUpdate(base64Update) {
+		this.events.emit("update", {
+			update: {
+				docId: this.docId,
+				data: base64ToBytes(base64Update)
+			},
+			origin: void 0
+		});
+	}
+};
+/**
+* Decode the wire `server_vv` into raw bytes, tolerating absence. A server that
+* omits the version block still yields a usable outcome (the kind is the useful
+* part); only the version-coverage wait degrades, so this must not throw.
+*/
+function decodeServerVV(serverVV) {
+	if (serverVV == null || serverVV === "") return void 0;
+	try {
+		return base64ToBytes(serverVV);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/storage/memory-doc-storage.ts
+/**
+* Runtime-neutral local `DocStorage` backed by in-process memory.
+*
+* `IndexedDBDocStorage` is the browser-side local storage, but it requires
+* `indexedDB`/`idb`, which is absent in Node (FE/agent tests, unit tests, SSR).
+* The mengine runtime injects this implementation as the local peer in those
+* environments so the same `DocManager` + `ClientServerSynchronizer` wiring
+* works without a browser. It mirrors the merge-on-read and update-sequence
+* behavior of `IndexedDBDocStorage` so sync semantics are identical.
+*/
+var MemoryDocStorage = class extends BaseDocStorage {
+	connection = new DummyConnection();
+	entries = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		super(options);
+	}
+	async pushDocUpdate(update, origin) {
+		const entry = this.entry(update.docId);
+		if (entry.snapshot == null && entry.updates.length === 0) {
+			const now = this.now();
+			entry.snapshot = {
+				docId: update.docId,
+				data: update.data,
+				createdAt: now,
+				updatedAt: now
+			};
+		} else {
+			entry.seq += 1;
+			entry.updates.push({
+				docId: update.docId,
+				seq: entry.seq,
+				data: update.data,
+				createdAt: this.now()
+			});
+		}
+		this.event.emit("update", {
+			update: {
+				docId: update.docId,
+				data: update.data
+			},
+			origin
+		});
+		return {};
+	}
+	async deleteDoc(docId) {
+		this.entries.delete(docId);
+	}
+	async getDocSnapshot(docId) {
+		return this.entries.get(docId)?.snapshot ?? null;
+	}
+	async setDocSnapshot(snapshot) {
+		const entry = this.entry(snapshot.docId);
+		if (entry.snapshot == null || entry.snapshot.updatedAt <= snapshot.updatedAt) entry.snapshot = snapshot;
+		return true;
+	}
+	async getDocUpdates(docId) {
+		return [...this.entries.get(docId)?.updates ?? []];
+	}
+	async markUpdatesMerged(docId, updates) {
+		const entry = this.entries.get(docId);
+		if (!entry) return 0;
+		const merged = new Set(updates.map((update) => update.seq));
+		entry.updates = entry.updates.filter((update) => !merged.has(update.seq));
+		return merged.size;
+	}
+	entry(docId) {
+		let entry = this.entries.get(docId);
+		if (!entry) {
+			entry = {
+				snapshot: null,
+				updates: [],
+				seq: 0
+			};
+			this.entries.set(docId, entry);
+		}
+		return entry;
+	}
+	now() {
+		return /* @__PURE__ */ new Date();
+	}
+};
+//#endregion
 //#region src/session/document-mutation-guard.ts
 /**
 * @internal
@@ -209,6 +1004,7 @@ var MengineAckFailedError = class extends Error {
 var DocumentSession = class {
 	options;
 	model;
+	validateDocument;
 	docId;
 	local;
 	server;
@@ -235,9 +1031,10 @@ var DocumentSession = class {
 	* doc (e.g. nothing was edited since the last confirmed push).
 	*/
 	serverVVValue = null;
-	constructor(options, model) {
+	constructor(options, model, validateDocument) {
 		this.options = options;
 		this.model = model;
+		this.validateDocument = validateDocument;
 		this.mutationGuard = new DocumentMutationGuard(options.readonlyMode);
 		this.docId = options.docId;
 		this.local = options.localStorage ?? new MemoryDocStorage();
@@ -441,6 +1238,17 @@ var DocumentSession = class {
 		await this.local.connection.waitForConnected().abortOn(this.lifetime.signal);
 		if (this.destroyed) throw new Error("mengine doc session destroyed");
 		if (this.options.initialSnapshot) {
+			const preview = new LoroDoc();
+			try {
+				if (preview.import(this.options.initialSnapshot).pending) throw new Error("Snapshot has missing dependencies");
+				this.validateDocument(preview);
+				const cached = await this.local.getDoc(this.docId);
+				if (cached && preview.import(cached.data).pending) throw new Error("Cached document has missing dependencies");
+				this.validateDocument(preview);
+			} finally {
+				preview.free();
+			}
+			if (this.destroyed) throw new Error("mengine doc session destroyed");
 			await this.local.pushDocUpdate({
 				docId: this.docId,
 				data: this.options.initialSnapshot
@@ -637,7 +1445,7 @@ var MengineDocSession = class extends DocumentSession {
 				subscribe: (listener) => dsl.subscribe(listener),
 				dispose: () => dsl.dispose()
 			};
-		});
+		}, assertDslDocument);
 	}
 	get dsl() {
 		return this.document;