@mengine/medeo-client 1.0.1-alpha.2 → 1.1.0

package/dist/loro-relay-doc-ssdYpuef.js

@@ -0,0 +1,58 @@
+import { LoroDoc } from "loro-crdt";
+//#region src/relay/loro-relay-doc.ts
+/**
+* Loro OpLog-relay primitives: the doc shape and update classification an update
+* *host* needs, as opposed to an editing client.
+*
+* A relay never materializes DocState (`docs/concepts/oplog_docstate` §Relay
+* Server) — it keeps a detached `LoroDoc` that validates and accumulates updates
+* and exports diffs by version vector.
+*
+* These live in `medeo-client` rather than in `mengine-server` because two
+* separate hosts must classify identically: the real server (`apps/mengine-server`,
+* both storage implementations) and the in-process test double
+* (`testing/in-memory-mengine-server.ts`) that client-side tests push against. A
+* double with its own verdict logic drifts from the server it stands in for, and
+* the four push outcomes it produces are exactly what those tests assert on — so
+* the classification is shared code, not duplicated code.
+*/
+/** Build a fresh detached relay doc (no DocState materialization). */
+function newRelayDoc() {
+	const doc = new LoroDoc();
+	doc.detach();
+	return doc;
+}
+/** Load a detached relay doc from a stored snapshot. */
+function relayDocFromSnapshot(snapshot) {
+	const doc = newRelayDoc();
+	doc.import(snapshot);
+	return doc;
+}
+/** A full-oplog clone (via snapshot round-trip) for non-destructive probing. */
+function cloneRelayDoc(doc) {
+	return relayDocFromSnapshot(doc.export({ mode: "snapshot" }));
+}
+/**
+* Classify an incoming update against `doc` without mutating it.
+*
+* Deliberately version-delta based, not `ImportStatus`-shape based: in loro-crdt
+* 1.13.x the JS `import()` returns `success`/`pending` as objects whose ranges
+* are not reliably populated, and a pending (out-of-order) import still buffers
+* the orphan op into the oplog. So this imports into a throwaway snapshot-clone
+* and inspects whether the oplog frontiers advanced — letting the caller import
+* into its canonical doc only on `accepted`, keeping orphan bytes out of the log.
+*/
+function classifyUpdate(doc, update) {
+	const probe = cloneRelayDoc(doc);
+	let status;
+	try {
+		status = probe.import(update);
+	} catch {
+		return "corrupt_update";
+	}
+	if (status?.pending != null) return "missing_dependency";
+	if (probe.cmpWithFrontiers(doc.oplogFrontiers()) !== 1) return "duplicate";
+	return "accepted";
+}
+//#endregion
+export { newRelayDoc as n, relayDocFromSnapshot as r, classifyUpdate as t };

package/dist/relay.d.ts

@@ -0,0 +1,37 @@
+import { LoroDoc } from "loro-crdt";
+
+//#region src/relay/loro-relay-doc.d.ts
+/**
+ * Loro OpLog-relay primitives: the doc shape and update classification an update
+ * *host* needs, as opposed to an editing client.
+ *
+ * A relay never materializes DocState (`docs/concepts/oplog_docstate` §Relay
+ * Server) — it keeps a detached `LoroDoc` that validates and accumulates updates
+ * and exports diffs by version vector.
+ *
+ * These live in `medeo-client` rather than in `mengine-server` because two
+ * separate hosts must classify identically: the real server (`apps/mengine-server`,
+ * both storage implementations) and the in-process test double
+ * (`testing/in-memory-mengine-server.ts`) that client-side tests push against. A
+ * double with its own verdict logic drifts from the server it stands in for, and
+ * the four push outcomes it produces are exactly what those tests assert on — so
+ * the classification is shared code, not duplicated code.
+ */
+/** Build a fresh detached relay doc (no DocState materialization). */
+declare function newRelayDoc(): LoroDoc;
+/** Load a detached relay doc from a stored snapshot. */
+declare function relayDocFromSnapshot(snapshot: Uint8Array): LoroDoc;
+type ImportVerdict = 'accepted' | 'duplicate' | 'corrupt_update' | 'missing_dependency';
+/**
+ * Classify an incoming update against `doc` without mutating it.
+ *
+ * Deliberately version-delta based, not `ImportStatus`-shape based: in loro-crdt
+ * 1.13.x the JS `import()` returns `success`/`pending` as objects whose ranges
+ * are not reliably populated, and a pending (out-of-order) import still buffers
+ * the orphan op into the oplog. So this imports into a throwaway snapshot-clone
+ * and inspects whether the oplog frontiers advanced — letting the caller import
+ * into its canonical doc only on `accepted`, keeping orphan bytes out of the log.
+ */
+declare function classifyUpdate(doc: LoroDoc, update: Uint8Array): ImportVerdict;
+//#endregion
+export { type ImportVerdict, classifyUpdate, newRelayDoc, relayDocFromSnapshot };

package/dist/relay.js

@@ -0,0 +1,2 @@
+import { n as newRelayDoc, r as relayDocFromSnapshot, t as classifyUpdate } from "./loro-relay-doc-ssdYpuef.js";
+export { classifyUpdate, newRelayDoc, relayDocFromSnapshot };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { c as MirrorVideoDocumentAdapter, it as VideoDraft } from "./index-DRUGsbm2.js";
+import { i as MirrorVideoDocumentAdapter, tt as VideoDraft } from "./index-BUKA3L7o.js";
 
 //#region src/testing/in-memory-mengine-server.d.ts
 /**
@@ -29,6 +29,21 @@ declare class InMemoryMengineServer {
   private handleSnapshot;
   private handleBootstrap;
   private handleSync;
+  /**
+   * Push one update, classifying it exactly as the real server does.
+   *
+   * This shares `classifyUpdate` with `apps/mengine-server` rather than assuming
+   * success, because the four push verdicts are the contract clients are written
+   * against: a double that always acks makes `duplicate` / `rejected` untestable
+   * above the storage layer, so an ack-waiter or a doc handle could mishandle
+   * them and still show green. It also mirrors the real server's two subtler
+   * behaviors — a non-accepted update is NOT imported (orphan bytes stay out of
+   * the log), and `duplicate` / `rejected` report the version from *before* the
+   * push, since nothing was appended.
+   *
+   * Status codes match the wire contract: `missing_dependency` is 409 (retryable
+   * after catch-up), `corrupt_update` is 422 (never retryable).
+   */
   private handlePush;
   private handleEvents;
 }

package/dist/testing.js

@@ -1,4 +1,5 @@
-import { B as bytesToBase64, N as VIDEO_DOCUMENT_SCHEMA_VERSION, o as createMirrorVideoDocumentAdapter, z as base64ToBytes } from "./document-DgffKwRw.js";
+import { L as base64ToBytes, M as VIDEO_DOCUMENT_SCHEMA_VERSION, R as bytesToBase64, r as createMirrorVideoDocumentAdapter } from "./document-C98vSu7J.js";
+import { t as classifyUpdate } from "./loro-relay-doc-ssdYpuef.js";
 import { LoroDoc, VersionVector, encodeFrontiers } from "loro-crdt";
 //#region src/testing/in-memory-mengine-server.ts
 /**
@@ -35,10 +36,6 @@ var InMemoryMengineServer = class {
 		if (path.startsWith("sync") && method === "GET") return this.handleSync(url);
 		if (path === "updates" && method === "POST") return this.handlePush(init);
 		if (path === "events" && method === "GET") return this.handleEvents(init);
-		if (path === "audit" && method === "GET") return Response.json({ entries: this.updates.map((u) => ({
-			...u.meta,
-			update_seq: u.updateSeq
-		})) });
 		return new Response("not found", { status: 404 });
 	};
 	parsePath(url) {
@@ -85,6 +82,21 @@ var InMemoryMengineServer = class {
 			server_vv: bytesToBase64(this.doc.oplogVersion().encode())
 		});
 	}
+	/**
+	* Push one update, classifying it exactly as the real server does.
+	*
+	* This shares `classifyUpdate` with `apps/mengine-server` rather than assuming
+	* success, because the four push verdicts are the contract clients are written
+	* against: a double that always acks makes `duplicate` / `rejected` untestable
+	* above the storage layer, so an ack-waiter or a doc handle could mishandle
+	* them and still show green. It also mirrors the real server's two subtler
+	* behaviors — a non-accepted update is NOT imported (orphan bytes stay out of
+	* the log), and `duplicate` / `rejected` report the version from *before* the
+	* push, since nothing was appended.
+	*
+	* Status codes match the wire contract: `missing_dependency` is 409 (retryable
+	* after catch-up), `corrupt_update` is 422 (never retryable).
+	*/
 	async handlePush(init) {
 		const body = JSON.parse(typeof init?.body === "string" ? init.body : "{}");
 		if (body.update == null) return Response.json({
@@ -94,6 +106,25 @@ var InMemoryMengineServer = class {
 		}, { status: 400 });
 		const data = base64ToBytes(body.update);
 		const baseVV = this.doc.oplogVersion();
+		const serverVersion = this.version();
+		const verdict = classifyUpdate(this.doc, data);
+		if (verdict === "corrupt_update") return Response.json({
+			kind: "rejected",
+			code: "corrupt_update",
+			message: "update failed to decode",
+			server_version: serverVersion
+		}, { status: 422 });
+		if (verdict === "missing_dependency") return Response.json({
+			kind: "rejected",
+			code: "missing_dependency",
+			message: "update depends on operations that are not in the server log",
+			server_version: serverVersion
+		}, { status: 409 });
+		if (verdict === "duplicate") return Response.json({
+			kind: "duplicate",
+			update_seq: null,
+			version: serverVersion
+		});
 		this.doc.import(data);
 		this.hasSnapshot = true;
 		this.seq += 1;
@@ -161,6 +192,7 @@ function extractMeta(doc, baseVV) {
 		semantic_op: null,
 		payload: null,
 		intent: null,
+		actor: null,
 		message: null,
 		parse_error: false,
 		peer: "0",
@@ -171,11 +203,12 @@ function extractMeta(doc, baseVV) {
 	};
 	const [counterPart, peerPart] = change.id.split("@");
 	const message = change.msg ?? change.message ?? null;
-	const { semantic_op, payload, intent, parse_error } = parseMessage(message);
+	const { semantic_op, payload, intent, actor, parse_error } = parseMessage(message);
 	return {
 		semantic_op,
 		payload,
 		intent,
+		actor,
 		message,
 		parse_error,
 		peer: peers[Number(peerPart)] ?? peerPart ?? "0",
@@ -185,11 +218,17 @@ function extractMeta(doc, baseVV) {
 		frontiers
 	};
 }
+/**
+* Mirrors `apps/mengine-server`'s `parseMessage` / `parseActor`. Kept in step
+* deliberately: this double is what harness tests push against, so a divergence
+* here would let them assert metadata the real server never produces.
+*/
 function parseMessage(message) {
 	if (message == null || message === "") return {
 		semantic_op: null,
 		payload: null,
 		intent: null,
+		actor: null,
 		parse_error: false
 	};
 	try {
@@ -198,12 +237,14 @@ function parseMessage(message) {
 			semantic_op: null,
 			payload: null,
 			intent: null,
+			actor: null,
 			parse_error: true
 		};
 		return {
 			semantic_op: typeof parsed.semantic_op === "string" ? parsed.semantic_op : null,
 			payload: parsed.payload ?? null,
 			intent: typeof parsed.intent === "string" ? parsed.intent : null,
+			actor: parseActor(parsed.actor),
 			parse_error: false
 		};
 	} catch {
@@ -211,10 +252,21 @@ function parseMessage(message) {
 			semantic_op: null,
 			payload: null,
 			intent: null,
+			actor: null,
 			parse_error: true
 		};
 	}
 }
+/** A malformed `actor` yields null for the author alone, never `parse_error`. */
+function parseActor(actor) {
+	if (actor == null || typeof actor !== "object") return null;
+	const { user_id: userId, role } = actor;
+	if (typeof userId !== "string" || userId === "" || typeof role !== "string" || role === "") return null;
+	return {
+		user_id: userId,
+		role
+	};
+}
 //#endregion
 //#region src/testing/index.ts
 const ACTOR_TEST = "1001";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mengine/medeo-client",
-  "version": "1.0.1-alpha.2",
+  "version": "1.1.0",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
-    "./schemas": "./dist/schemas.js",
+    "./relay": "./dist/relay.js",
     "./testing": "./dist/testing.js",
     "./package.json": "./package.json"
   },
@@ -23,18 +23,16 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "immer": "^10.2.0",
     "loro-mirror": "^2.2.0",
     "zod": "^4.4.3",
-    "@mengine/storage": "1.0.1-alpha.2",
-    "@mengine/utils": "1.0.1-alpha.2",
-    "@mengine/sync": "1.0.1-alpha.2"
+    "@mengine/storage": "1.1.0",
+    "@mengine/sync": "1.1.0",
+    "@mengine/utils": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
     "@typescript/native-preview": "7.0.0-dev.20260521.1",
     "loro-crdt": "^1.13.6",
-    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
     "vite-plugin-wasm": "^3.6.0",
     "vite-plus": "^0.1.23",