@mengine/medeo-client 2.1.0 → 2.1.1-dsl.0

package/dist/storage-BW3tI_ER.js

@@ -0,0 +1,801 @@
+import { n as bytesToBase64, t as base64ToBytes } from "./base64-D-jd-dr5.js";
+import { LoroDoc, VersionVector } from "loro-crdt";
+import { 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/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
+export { covers as a, readMengineEventStream as c, MenginePushRejectedError as d, openManualDocument as i, MengineHttpClient as l, MedeoHttpDocStorage as n, decodeDocVersionMark as o, ManualSyncTransport as r, encodeDocVersionMark as s, MemoryDocStorage as t, MengineHttpRequestError as u };