@mengine/medeo-client 1.0.1 → 1.2.0

package/dist/{loro-relay-doc-Br-ZJBHa.js → document-C0o_cjAH.js}

@@ -230,6 +230,16 @@ function effectiveVideoClipDurationMs(clip) {
 	const effective = Math.round(sourceMs / speed);
 	return Number.isFinite(effective) && effective > 0 ? effective : 0;
 }
+/**
+* The `timeline.unit_time_ms` the read-view states when the document states none.
+*
+* One frame at 30fps. A document legitimately has no such fact (display
+* granularity is the editor's, not the timeline's), but the read-view IDL marks
+* the field `@required`, so the projection has to name a value. This one is a
+* usable granularity; `0` — which a downstream consumer had been defaulting to —
+* is not, and passes any `>= 0` guard on its way to an editor that cannot use it.
+*/
+const DEFAULT_UNIT_TIME_MS = 33.333;
 //#endregion
 //#region src/timeline-core/types.ts
 /** Total document duration when there is no real content (matches FE bgm fallback). */
@@ -648,6 +658,42 @@ function seedAggregations(mainItems, speechItems) {
 	return order.map((host) => byHost.get(host));
 }
 /**
+* The four lanes in top-to-bottom stack order — the order a `tracks` list holds
+* them in (see {@link laneRank}).
+*
+* Exported so a document can be seeded with all four lanes up front. That seed is
+* not cosmetic: {@link ensureLaneTrack} is find-then-mint over a `LoroMovableList`,
+* so two concurrent writers that each mint the same absent lane both keep their
+* row, and the merged document holds two tracks for one lane. For the main lane
+* that is fatal — `videoDocumentSchema` allows at most one `video_clip` track, so
+* the merged document stops being projectable at all, symmetrically on both
+* replicas. Pre-seeding every lane makes `ensureLaneTrack` always take its find
+* branch, which removes the race by construction rather than by detection.
+*
+* What closes the race is that a track with the lane's `parts_kind` EXISTS — the
+* lookup is by kind, not by id. So a seed is only safe if it covers every lane:
+* a partial seed leaves the uncovered lanes exactly as exposed as before.
+*/
+const LANE_KINDS_IN_STACK_ORDER = [
+	"caption",
+	"video_clip",
+	"speech",
+	"bgm"
+];
+/**
+* The conventional track id for a lane (`main_track`, `<kind>_track`). Shared by
+* the up-front seed and {@link ensureLaneTrack}'s lazy mint so a document's lane
+* ids do not depend on which of the two created the track.
+*
+* Ids are cosmetic to the merge itself — lane lookup goes by `parts_kind`, so
+* drifting them apart would not reopen the concurrent-mint race. They matter to
+* readers that address a lane by id (the FE editor's panes, fixtures), which is
+* why there is one convention rather than two.
+*/
+function laneTrackId(kind) {
+	return kind === "video_clip" ? "main_track" : `${kind}_track`;
+}
+/**
 * Lane-stacking rank for the single `tracks` list (reference/17 §4): caption
 * (above) sits before the video_clip main track, which sits before speech / bgm
 * (below). The `tracks` array is kept in this top-to-bottom order so a freshly
@@ -678,14 +724,18 @@ function insertTrackByLaneOrder(tracks, track) {
 * Locate a lane's track row in the single `tracks` list by kind, minting an empty
 * row in lane-stacking order if absent (reference/17 §4: lane = `parts_kind`).
 * Ops use this to write authoritative items onto the right lane. The track id
-* mirrors the seed convention (`<kind>_track`).
+* comes from {@link laneTrackId}, shared with the up-front seed.
+*
+* The mint branch is a concurrency hazard, not a convenience: see
+* {@link LANE_KINDS_IN_STACK_ORDER}. A document seeded with all four lanes never
+* reaches it.
 */
 function ensureLaneTrack(draft, kind) {
 	draft.tracks ??= [];
 	let track = draft.tracks.find((t) => t?.parts_kind === kind);
 	if (track == null) {
 		track = {
-			id: kind === "video_clip" ? "main_track" : `${kind}_track`,
+			id: laneTrackId(kind),
 			parts_kind: kind,
 			is_hidden: void 0,
 			items: []
@@ -1239,6 +1289,20 @@ function deriveItem(item, isMain, speechHost, partLibrary) {
 * Project the authoritative `VideoDocument` back into the legacy `VideoDraft`
 * read-view, solving each item's absolute position, the `part_aggregations`, and
 * the total duration via the timeline-core cascade.
+*
+* The read-view is a compatibility contract, and the IDL declares
+* `Timeline.unit_time_ms` and `Track.is_hidden` `@required`
+* (`video_draft_comp.smithy`) — so a projection that omitted them handed every
+* consumer a payload that violated the shape it claims to satisfy, leaving each
+* one to invent its own default. Two already had, and they disagreed: the agent
+* harness used `unit_time_ms: 0`, director used a frame at 30fps. Defaulting here
+* makes the contract true at the one place that produces it.
+*
+* These two are defaultable because the projection knows their values on its own:
+* absent `unit_time_ms` means "no display granularity was ever stated" and absent
+* `is_hidden` means "this track was never hidden". `version` is NOT defaultable
+* here — its only honest value is server state (`update_seq`) that a
+* `VideoDocument` cannot see, so it stays absent and the HTTP layer fills it.
 */
 function fromVideoDocument(document) {
 	assertValidVideoDocument(document);
@@ -1254,7 +1318,7 @@ function fromVideoDocument(document) {
 		thumbnail_storage_key: document.meta.thumbnail_storage_key,
 		timeline: {
 			duration_ms: view.durationMs,
-			unit_time_ms: document.timeline?.unit_time_ms
+			unit_time_ms: document.timeline?.unit_time_ms ?? 33.333
 		},
 		video_creation_settings: clone(document.meta.video_creation_settings),
 		chat_session_id: document.meta.chat_session_id,
@@ -1350,7 +1414,7 @@ function draftTrack(track, absByPartId) {
 	return {
 		id: track.id,
 		parts_kind: track.parts_kind,
-		is_hidden: track.is_hidden,
+		is_hidden: track.is_hidden ?? false,
 		items: (track.items ?? []).map((item) => ({
 			part_id: item.part_id,
 			abs_time_position: absByPartId.get(item.part_id) ?? 0
@@ -1367,6 +1431,57 @@ function clone(value) {
 	return value;
 }
 //#endregion
+//#region src/document/initial-document.ts
+/**
+* Build the `VideoDocument` a newly created project starts from: the caller's
+* project facts, no parts, and one empty track per lane.
+*
+* The empty lane tracks are the reason this function exists rather than callers
+* assembling a document inline. Lane tracks are otherwise minted lazily by the
+* first op that needs one (`ensureLaneTrack`), which is find-then-mint over a
+* CRDT list — so if the Agent's first generation and a user edit race on an
+* empty document, each mints its own copy of the same lane and the merge keeps
+* both. Two video_clip tracks violate the at-most-one-main-track rule, and the
+* merged document becomes unprojectable for *every* reader (editor, render,
+* share) with no winning replica to fall back on. Seeding all four lanes up
+* front means `ensureLaneTrack` only ever finds, never mints, so the race cannot
+* happen on a document created here.
+*
+* All four, not just the main lane: the secondary lanes fail less loudly (a
+* duplicate pane rather than an unreadable document), but they fail by the same
+* mechanism, and covering only the fatal one would leave three live races.
+*
+* `timeline` is left absent: `unit_time_ms` is a display concern the editor
+* supplies, and total duration is derived on read (RFC 02 §6), so a new document
+* has no timeline fact to state.
+*/
+function buildInitialVideoDocument(facts) {
+	return {
+		meta: {
+			schema_version: VIDEO_DOCUMENT_SCHEMA_VERSION,
+			draft_id: facts.draftId,
+			project_id: facts.projectId,
+			owner_id: facts.ownerId,
+			thumbnail_storage_key: void 0,
+			chat_session_id: facts.chatSessionId,
+			video_creation_settings: facts.videoCreationSettings,
+			version: void 0
+		},
+		timeline: void 0,
+		tracks: emptyLaneTracks(),
+		part_library: {}
+	};
+}
+/** One empty track per lane, in lane-stacking order, with the conventional ids. */
+function emptyLaneTracks() {
+	return LANE_KINDS_IN_STACK_ORDER.map((kind) => ({
+		id: laneTrackId(kind),
+		parts_kind: kind,
+		is_hidden: void 0,
+		items: []
+	}));
+}
+//#endregion
 //#region src/document/mirror-read.ts
 /**
 * Project the mirror state (`VideoDocumentDraft`) into the authoritative
@@ -1536,60 +1651,4 @@ function toTrackRow(track) {
 	};
 }
 //#endregion
-//#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 { partDurationMs as A, reassignSpeechesToVideoClipsByTime as C, syncAggregatedClipsTimePosition as D, resolveSpeechOverlapByShiftingVideos as E, recordEntries as F, videoDocumentMirrorSchema as I, base64ToBytes as L, VIDEO_DOCUMENT_SCHEMA_VERSION as M, effectiveVideoClipDurationMs as N, TIMELINE_SKELETON_DURATION_MS as O, partUnionToDraft as P, bytesToBase64 as R, fillMainTrackTimeGaps as S, resolveAllSpeechOverlaps as T, ensureLaneTrack as _, createMirrorVideoDocument as a, cascadeAfterVideoClipChanges as b, buildSpeechHostMap as c, toVideoDocument as d, VideoDocumentValidationError as f, videoDocumentSchema as g, partUnionSchema as h, MirrorVideoDocumentAdapter as i, safeDurationMs as j, isEmptyVideoClip as k, derivePositionFromAbs as l, validateVideoDocument as m, newRelayDoc as n, createMirrorVideoDocumentAdapter as o, assertValidVideoDocument as p, relayDocFromSnapshot as r, readVideoDocumentFromDraft as s, classifyUpdate as t, fromVideoDocument as u, findLaneTrack as v, recalculateTimelineDuration as w, arrangeMainTrackSeamlessly as x, solveVideoDocument as y };
+export { partDurationMs as A, reassignSpeechesToVideoClipsByTime as C, syncAggregatedClipsTimePosition as D, resolveSpeechOverlapByShiftingVideos as E, partUnionToDraft as F, recordEntries as I, videoDocumentMirrorSchema as L, DEFAULT_UNIT_TIME_MS as M, VIDEO_DOCUMENT_SCHEMA_VERSION as N, TIMELINE_SKELETON_DURATION_MS as O, effectiveVideoClipDurationMs as P, base64ToBytes as R, fillMainTrackTimeGaps as S, resolveAllSpeechOverlaps as T, findLaneTrack as _, buildInitialVideoDocument as a, cascadeAfterVideoClipChanges as b, fromVideoDocument as c, assertValidVideoDocument as d, validateVideoDocument as f, ensureLaneTrack as g, LANE_KINDS_IN_STACK_ORDER as h, readVideoDocumentFromDraft as i, safeDurationMs as j, isEmptyVideoClip as k, toVideoDocument as l, videoDocumentSchema as m, createMirrorVideoDocument as n, buildSpeechHostMap as o, partUnionSchema as p, createMirrorVideoDocumentAdapter as r, derivePositionFromAbs as s, MirrorVideoDocumentAdapter as t, VideoDocumentValidationError as u, laneTrackId as v, recalculateTimelineDuration as w, arrangeMainTrackSeamlessly as x, solveVideoDocument as y, bytesToBase64 as z };

package/dist/{index-DLchEQG7.d.ts → index-DWVYLTjv.d.ts}

@@ -632,6 +632,16 @@ type VideoDraft = Omit<VideoDraft$1, 'part_library' | 'video_creation_settings'>
 interface Timeline {
   unit_time_ms: number | undefined;
 }
+/**
+ * The `timeline.unit_time_ms` the read-view states when the document states none.
+ *
+ * One frame at 30fps. A document legitimately has no such fact (display
+ * granularity is the editor's, not the timeline's), but the read-view IDL marks
+ * the field `@required`, so the projection has to name a value. This one is a
+ * usable granularity; `0` — which a downstream consumer had been defaulting to —
+ * is not, and passes any `>= 0` guard on its way to an editor that cannot use it.
+ */
+declare const DEFAULT_UNIT_TIME_MS = 33.333;
 /**
  * Project-level scalars that do not participate in track ordering. Grouped under
  * `meta` because the loro-mirror `schema()` root only accepts container schemas,
@@ -748,9 +758,66 @@ declare function derivePositionFromAbs(partId: string, abs: number, isMain: bool
  * Project the authoritative `VideoDocument` back into the legacy `VideoDraft`
  * read-view, solving each item's absolute position, the `part_aggregations`, and
  * the total duration via the timeline-core cascade.
+ *
+ * The read-view is a compatibility contract, and the IDL declares
+ * `Timeline.unit_time_ms` and `Track.is_hidden` `@required`
+ * (`video_draft_comp.smithy`) — so a projection that omitted them handed every
+ * consumer a payload that violated the shape it claims to satisfy, leaving each
+ * one to invent its own default. Two already had, and they disagreed: the agent
+ * harness used `unit_time_ms: 0`, director used a frame at 30fps. Defaulting here
+ * makes the contract true at the one place that produces it.
+ *
+ * These two are defaultable because the projection knows their values on its own:
+ * absent `unit_time_ms` means "no display granularity was ever stated" and absent
+ * `is_hidden` means "this track was never hidden". `version` is NOT defaultable
+ * here — its only honest value is server state (`update_seq`) that a
+ * `VideoDocument` cannot see, so it stays absent and the HTTP layer fills it.
  */
 declare function fromVideoDocument(document: VideoDocument): VideoDraft;
 //#endregion
+//#region src/document/initial-document.d.ts
+/**
+ * The project facts a freshly created document is built from — exactly the five
+ * fields Director sets when it creates a draft row, and nothing else.
+ *
+ * Deliberately not a whole `VideoDraft`: tracks and the part library of a new
+ * document are empty by definition, so accepting them would mean accepting
+ * values that must always be empty, and every such field is a place for a future
+ * caller to send something that is silently dropped. The narrow shape makes the
+ * "a new document has no content" rule structural instead of a convention.
+ */
+interface InitialDocumentFacts {
+  draftId: string;
+  projectId: string | undefined;
+  ownerId: string | undefined;
+  chatSessionId: string | undefined;
+  videoCreationSettings: VideoCreationSettings | undefined;
+}
+/**
+ * Build the `VideoDocument` a newly created project starts from: the caller's
+ * project facts, no parts, and one empty track per lane.
+ *
+ * The empty lane tracks are the reason this function exists rather than callers
+ * assembling a document inline. Lane tracks are otherwise minted lazily by the
+ * first op that needs one (`ensureLaneTrack`), which is find-then-mint over a
+ * CRDT list — so if the Agent's first generation and a user edit race on an
+ * empty document, each mints its own copy of the same lane and the merge keeps
+ * both. Two video_clip tracks violate the at-most-one-main-track rule, and the
+ * merged document becomes unprojectable for *every* reader (editor, render,
+ * share) with no winning replica to fall back on. Seeding all four lanes up
+ * front means `ensureLaneTrack` only ever finds, never mints, so the race cannot
+ * happen on a document created here.
+ *
+ * All four, not just the main lane: the secondary lanes fail less loudly (a
+ * duplicate pane rather than an unreadable document), but they fail by the same
+ * mechanism, and covering only the fatal one would leave three live races.
+ *
+ * `timeline` is left absent: `unit_time_ms` is a display concern the editor
+ * supplies, and total duration is derived on read (RFC 02 §6), so a new document
+ * has no timeline fact to state.
+ */
+declare function buildInitialVideoDocument(facts: InitialDocumentFacts): VideoDocument;
+//#endregion
 //#region src/document/validation.d.ts
 /**
  * Business-level schema guard for `VideoDocument` (RFC 03 §9). It is the gate
@@ -2029,4 +2096,4 @@ declare const videoDocumentSchema: z.ZodObject<{
   }, z.core.$loose>]>>>;
 }, z.core.$loose>;
 //#endregion
-export { VideoDraft as $, assertValidVideoDocument as A, PartKind as B, index_d_exports as C, VideoDocumentMirrorSchema as D, VideoDocumentDraft as E, derivePositionFromAbs as F, TrackItem as G, SpeechPart as H, fromVideoDocument as I, VideoClipPart as J, TrackItemTimePosition as K, toVideoDocument as L, DerivedItemPosition as M, SpeechHostMap as N, videoDocumentMirrorSchema as O, buildSpeechHostMap as P, VideoDocumentValidationIssueCode as Q, BgmPart as R, ValidationError as S, TrackItemDraft as T, Timeline as U, PartUnion as V, Track as W, VideoDocumentSchemaVersion as X, VideoDocument as Y, VideoDocumentValidationIssue as Z, PlannedSemanticOpKind as _, MirrorVideoDocumentOptions as a, SpeedShift as at, SchemaValidator as b, CommitOptions as c, TrackItem$1 as ct, SemanticEditor as d, VideoDraftPartUnion as et, SemanticOpInput as f, ImplementedSemanticOpKind as g, IMPLEMENTED_SEMANTIC_OP_KINDS as h, MirrorVideoDocumentAdapter as i, PartAggregation as it, validateVideoDocument as j, VideoDocumentValidationError as k, OpActor as l, TransactAudit as m, videoDocumentSchema as n, CaptionPart$1 as nt, createMirrorVideoDocument as o, Timeline$1 as ot, SemanticOpName as p, VIDEO_DOCUMENT_SCHEMA_VERSION as q, readVideoDocumentFromDraft as r, CaptionStyle as rt, createMirrorVideoDocumentAdapter as s, Track$1 as st, partUnionSchema as t, Attachment as tt, SemanticDocumentAdapter as u, SemanticOpKind as v, TrackDraft as w, SnapshotReadable as x, isImplementedSemanticOpKind as y, CaptionPart as z };
+export { VideoDocumentSchemaVersion as $, assertValidVideoDocument as A, BgmPart as B, index_d_exports as C, VideoDocumentMirrorSchema as D, VideoDocumentDraft as E, SpeechHostMap as F, SpeechPart as G, DEFAULT_UNIT_TIME_MS as H, buildSpeechHostMap as I, TrackItem as J, Timeline as K, derivePositionFromAbs as L, InitialDocumentFacts as M, buildInitialVideoDocument as N, videoDocumentMirrorSchema as O, DerivedItemPosition as P, VideoDocument as Q, fromVideoDocument as R, ValidationError as S, TrackItemDraft as T, PartKind as U, CaptionPart as V, PartUnion as W, VIDEO_DOCUMENT_SCHEMA_VERSION as X, TrackItemTimePosition as Y, VideoClipPart as Z, PlannedSemanticOpKind as _, MirrorVideoDocumentOptions as a, CaptionPart$1 as at, SchemaValidator as b, CommitOptions as c, SpeedShift as ct, SemanticEditor as d, TrackItem$1 as dt, VideoDocumentValidationIssue as et, SemanticOpInput as f, ImplementedSemanticOpKind as g, IMPLEMENTED_SEMANTIC_OP_KINDS as h, MirrorVideoDocumentAdapter as i, Attachment as it, validateVideoDocument as j, VideoDocumentValidationError as k, OpActor as l, Timeline$1 as lt, TransactAudit as m, videoDocumentSchema as n, VideoDraft as nt, createMirrorVideoDocument as o, CaptionStyle as ot, SemanticOpName as p, Track as q, readVideoDocumentFromDraft as r, VideoDraftPartUnion as rt, createMirrorVideoDocumentAdapter as s, PartAggregation as st, partUnionSchema as t, VideoDocumentValidationIssueCode as tt, SemanticDocumentAdapter as u, Track$1 as ut, SemanticOpKind as v, TrackDraft as w, SnapshotReadable as x, isImplementedSemanticOpKind as y, toVideoDocument as z };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { $ as VideoDraft, A as assertValidVideoDocument, B as PartKind, C as index_d_exports, D as VideoDocumentMirrorSchema, E as VideoDocumentDraft, F as derivePositionFromAbs, G as TrackItem, H as SpeechPart, I as fromVideoDocument, J as VideoClipPart, K as TrackItemTimePosition, L as toVideoDocument, M as DerivedItemPosition, N as SpeechHostMap, O as videoDocumentMirrorSchema, P as buildSpeechHostMap, Q as VideoDocumentValidationIssueCode, R as BgmPart, S as ValidationError, T as TrackItemDraft, U as Timeline, V as PartUnion, W as Track, X as VideoDocumentSchemaVersion, Y as VideoDocument, Z as VideoDocumentValidationIssue, _ as PlannedSemanticOpKind, a as MirrorVideoDocumentOptions, at as SpeedShift, b as SchemaValidator, c as CommitOptions, ct as TrackItem$1, d as SemanticEditor, et as VideoDraftPartUnion, f as SemanticOpInput, g as ImplementedSemanticOpKind, h as IMPLEMENTED_SEMANTIC_OP_KINDS, i as MirrorVideoDocumentAdapter, it as PartAggregation, j as validateVideoDocument, k as VideoDocumentValidationError, l as OpActor, m as TransactAudit, n as videoDocumentSchema, nt as CaptionPart$1, o as createMirrorVideoDocument, ot as Timeline$1, p as SemanticOpName, q as VIDEO_DOCUMENT_SCHEMA_VERSION, r as readVideoDocumentFromDraft, rt as CaptionStyle, s as createMirrorVideoDocumentAdapter, st as Track$1, t as partUnionSchema, tt as Attachment, u as SemanticDocumentAdapter, v as SemanticOpKind, w as TrackDraft, x as SnapshotReadable, y as isImplementedSemanticOpKind, z as CaptionPart } from "./index-DLchEQG7.js";
-import { LoroDoc, PeerID, VersionVector } from "loro-crdt";
+import { $ as VideoDocumentSchemaVersion, A as assertValidVideoDocument, B as BgmPart, C as index_d_exports, D as VideoDocumentMirrorSchema, E as VideoDocumentDraft, F as SpeechHostMap, G as SpeechPart, H as DEFAULT_UNIT_TIME_MS, I as buildSpeechHostMap, J as TrackItem, K as Timeline, L as derivePositionFromAbs, M as InitialDocumentFacts, N as buildInitialVideoDocument, O as videoDocumentMirrorSchema, P as DerivedItemPosition, Q as VideoDocument, R as fromVideoDocument, S as ValidationError, T as TrackItemDraft, U as PartKind, V as CaptionPart, W as PartUnion, X as VIDEO_DOCUMENT_SCHEMA_VERSION, Y as TrackItemTimePosition, Z as VideoClipPart, _ as PlannedSemanticOpKind, a as MirrorVideoDocumentOptions, at as CaptionPart$1, b as SchemaValidator, c as CommitOptions, ct as SpeedShift, d as SemanticEditor, dt as TrackItem$1, et as VideoDocumentValidationIssue, f as SemanticOpInput, g as ImplementedSemanticOpKind, h as IMPLEMENTED_SEMANTIC_OP_KINDS, i as MirrorVideoDocumentAdapter, it as Attachment, j as validateVideoDocument, k as VideoDocumentValidationError, l as OpActor, lt as Timeline$1, m as TransactAudit, n as videoDocumentSchema, nt as VideoDraft, o as createMirrorVideoDocument, ot as CaptionStyle, p as SemanticOpName, q as Track, r as readVideoDocumentFromDraft, rt as VideoDraftPartUnion, s as createMirrorVideoDocumentAdapter, st as PartAggregation, t as partUnionSchema, tt as VideoDocumentValidationIssueCode, u as SemanticDocumentAdapter, ut as Track$1, v as SemanticOpKind, w as TrackDraft, x as SnapshotReadable, y as isImplementedSemanticOpKind, z as toVideoDocument } from "./index-DWVYLTjv.js";
+import { PeerID } from "loro-crdt";
 import { DocState } from "@mengine/sync";
-import { BaseDocStorage, Connection, DocDiff, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
+import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
 
 //#region src/client/base64.d.ts
 declare function bytesToBase64(bytes: Uint8Array): string;
@@ -474,66 +474,6 @@ declare class ManualSyncDoc {
   private serverVVFrom;
 }
 //#endregion
-//#region src/manual-sync/version-coverage.d.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.
- */
-declare function covers(outer: VersionVector, inner: VersionVector): boolean;
-//#endregion
-//#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
 //#region src/storage/medeo-http-doc-storage.d.ts
 interface MedeoHttpDocStorageOptions {
   docId: string;
@@ -555,20 +495,21 @@ interface MedeoHttpDocStorageOptions {
 type PushOutcomeKind = 'ack' | 'duplicate' | 'rejected' | 'failed';
 interface PushOutcome {
   kind: PushOutcomeKind;
-  /** The bytes this outcome describes — lets a waiter match its own update. */
-  update: Uint8Array;
   /** Server-allocated sequence number; only present for `ack`. */
   updateSeq?: number | undefined;
   /**
    * The server oplog version vector *after* handling this push (`ack` and
    * `duplicate` both carry it; encoded `VersionVector`).
    *
-   * This — not the pushed bytes — is what an "is my write durable" waiter should
-   * key on. The same ops can reach the server either as the individual blob the
-   * push job carried or as a merged `export({from: serverVV})` blob produced by
-   * the synchronizer's sync path, so byte identity is not a reliable match.
-   * Version coverage is, and it makes `duplicate` satisfy a waiter correctly: the
-   * bytes appended nothing precisely because the server already held them.
+   * This is what an "is my write durable" waiter keys on, and it is deliberately
+   * the ONLY correlation handle here. An earlier revision also carried the pushed
+   * bytes so a waiter could match its own update; that was removed because byte
+   * identity is not a reliable match — the same ops can reach the server either
+   * as the individual blob the push job carried or as a merged
+   * `export({from: serverVV})` blob produced by the synchronizer's sync path.
+   * Version coverage is reliable, and it makes `duplicate` satisfy a waiter
+   * correctly: the bytes appended nothing precisely because the server already
+   * held them. Offering both invited the wrong one.
    */
   serverVV?: Uint8Array | undefined;
   /** Server machine code for `rejected` (e.g. `missing_dependency`). */
@@ -608,19 +549,24 @@ declare class MedeoHttpDocStorage implements DocStorage {
   getDoc(docId: string): Promise<DocSnapshotRecord | null>;
   getDocDiff(docId: string, knownVersion?: Uint8Array): Promise<DocDiff | null>;
   /**
-   * Forward one update to the server.
+   * 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 `DocStorage` contract returns `void`, so the server's verdict cannot be
-   * the return value — it is published on {@link subscribePushOutcome} instead,
-   * for BOTH outcomes and failures. That channel is what makes the push
-   * observable; previously the verdict was read and dropped, so a `duplicate`
-   * (bytes contributed nothing) was indistinguishable from a successful write.
+   * 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.
    */
-  pushDocUpdate(update: DocUpdate, _origin: unknown): Promise<void>;
+  pushDocUpdate(update: DocUpdate, _origin: unknown): Promise<DocPushReceipt>;
   /**
    * Observe the server's verdict for every pushed update, including failures.
    *
@@ -651,7 +597,11 @@ interface MengineDocSessionUpdateEvent {
 }
 /**
  * Raised by {@link MengineDocSession.waitForServerAck} when the local edits it
- * was asked to confirm did not reach the server in time, or were refused.
+ * was asked to confirm were not acknowledged as durable.
+ *
+ * Named `...AckFailed`, not `...AckTimeout`: two of the three `reason` values are
+ * not timeouts, and the earlier name made callers reach for a retry-after-delay
+ * that is wrong for `rejected`.
  *
  * The distinction the caller needs is "was it written": if this throws, treat the
  * write as NOT durable. `reason` says which failure it was, and `code` carries the
@@ -663,7 +613,7 @@ interface MengineDocSessionUpdateEvent {
  *   catch-up; `corrupt_update` never is.
  * - `failed` — transport/network failure; the server's answer is unknown.
  */
-declare class MengineAckTimeoutError extends Error {
+declare class MengineAckFailedError extends Error {
   readonly reason: 'timeout' | 'rejected' | 'failed';
   readonly code: string | undefined;
   readonly cause: Error | undefined;
@@ -753,7 +703,7 @@ declare class MengineDocSession {
    * Returns early when the server is already known to be current, so a caller
    * with nothing outstanding does not block.
    *
-   * @throws {MengineAckTimeoutError} on timeout, rejection, or transport failure.
+   * @throws {MengineAckFailedError} on timeout, rejection, or transport failure.
    */
   waitForServerAck(options?: WaitForServerAckOptions): Promise<void>;
   /**
@@ -805,7 +755,7 @@ declare class MemoryDocStorage extends BaseDocStorage {
   readonly connection: Connection;
   private readonly entries;
   constructor(options?: DocStorageOptions);
-  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<void>;
+  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<DocPushReceipt>;
   deleteDoc(docId: string): Promise<void>;
   protected getDocSnapshot(docId: string): Promise<DocSnapshotRecord | null>;
   protected setDocSnapshot(snapshot: DocSnapshotRecord): Promise<boolean>;
@@ -1026,13 +976,48 @@ interface SolvedVideoDocument {
 declare function solveVideoDocument(document: VideoDocument): SolvedVideoDocument;
 /** The named container a secondary lane lives in. */
 type SecondaryLane = 'speech' | 'caption' | 'bgm';
+/** A lane's track kind: the `video_clip` main lane plus the three secondary lanes. */
+type LaneKind = SecondaryLane | 'video_clip';
+/**
+ * The four lanes in top-to-bottom stack order — the order a `tracks` list holds
+ * them in (see {@link laneRank}).
+ *
+ * Exported so a document can be seeded with all four lanes up front. That seed is
+ * not cosmetic: {@link ensureLaneTrack} is find-then-mint over a `LoroMovableList`,
+ * so two concurrent writers that each mint the same absent lane both keep their
+ * row, and the merged document holds two tracks for one lane. For the main lane
+ * that is fatal — `videoDocumentSchema` allows at most one `video_clip` track, so
+ * the merged document stops being projectable at all, symmetrically on both
+ * replicas. Pre-seeding every lane makes `ensureLaneTrack` always take its find
+ * branch, which removes the race by construction rather than by detection.
+ *
+ * What closes the race is that a track with the lane's `parts_kind` EXISTS — the
+ * lookup is by kind, not by id. So a seed is only safe if it covers every lane:
+ * a partial seed leaves the uncovered lanes exactly as exposed as before.
+ */
+declare const LANE_KINDS_IN_STACK_ORDER: readonly LaneKind[];
+/**
+ * The conventional track id for a lane (`main_track`, `<kind>_track`). Shared by
+ * the up-front seed and {@link ensureLaneTrack}'s lazy mint so a document's lane
+ * ids do not depend on which of the two created the track.
+ *
+ * Ids are cosmetic to the merge itself — lane lookup goes by `parts_kind`, so
+ * drifting them apart would not reopen the concurrent-mint race. They matter to
+ * readers that address a lane by id (the FE editor's panes, fixtures), which is
+ * why there is one convention rather than two.
+ */
+declare function laneTrackId(kind: LaneKind): string;
 /**
  * Locate a lane's track row in the single `tracks` list by kind, minting an empty
  * row in lane-stacking order if absent (reference/17 §4: lane = `parts_kind`).
  * Ops use this to write authoritative items onto the right lane. The track id
- * mirrors the seed convention (`<kind>_track`).
+ * comes from {@link laneTrackId}, shared with the up-front seed.
+ *
+ * The mint branch is a concurrency hazard, not a convenience: see
+ * {@link LANE_KINDS_IN_STACK_ORDER}. A document seeded with all four lanes never
+ * reaches it.
  */
-declare function ensureLaneTrack(draft: VideoDocumentDraft, kind: SecondaryLane | 'video_clip'): TrackDraft;
+declare function ensureLaneTrack(draft: VideoDocumentDraft, kind: LaneKind): TrackDraft;
 /** Find a secondary lane's track row without minting it. */
 declare function findLaneTrack(draft: VideoDocumentDraft, kind: SecondaryLane): TrackDraft | undefined;
 //#endregion
@@ -1079,4 +1064,4 @@ declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipR
  */
 declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
 //#endregion
-export { type Aggregation, type Attachment, type BgmPart, type CaptionPart, type CaptionStyle, type CommitOptions, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImplementedSemanticOpKind, type ImportVerdict, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, MemoryDocStorage, MengineAckTimeoutError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type OpActor, type PartAggregation, type PartKind, type PartUnion, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, SchemaValidator, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, type VideoDocumentSchemaVersion, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type WaitForServerAckOptions, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, classifyUpdate, covers, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, mainTrackRanges, newRelayDoc, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, relayDocFromSnapshot, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };
+export { type Aggregation, type Attachment, type BgmPart, type CaptionPart, type CaptionStyle, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImplementedSemanticOpKind, type InitialDocumentFacts, LANE_KINDS_IN_STACK_ORDER, type LaneKind, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type OpActor, type PartAggregation, type PartKind, type PartUnion, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, SchemaValidator, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, type VideoDocumentSchemaVersion, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type WaitForServerAckOptions, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-D7D4PA-g.js";
-import { A as partDurationMs, C as reassignSpeechesToVideoClipsByTime, D as syncAggregatedClipsTimePosition, E as resolveSpeechOverlapByShiftingVideos, F as recordEntries, I as videoDocumentMirrorSchema, L as base64ToBytes, M as VIDEO_DOCUMENT_SCHEMA_VERSION, N as effectiveVideoClipDurationMs, O as TIMELINE_SKELETON_DURATION_MS, P as partUnionToDraft, R as bytesToBase64, S as fillMainTrackTimeGaps, T as resolveAllSpeechOverlaps, _ as ensureLaneTrack, a as createMirrorVideoDocument, b as cascadeAfterVideoClipChanges, c as buildSpeechHostMap, d as toVideoDocument, f as VideoDocumentValidationError, g as videoDocumentSchema, h as partUnionSchema, i as MirrorVideoDocumentAdapter, j as safeDurationMs, k as isEmptyVideoClip, l as derivePositionFromAbs, m as validateVideoDocument, n as newRelayDoc, o as createMirrorVideoDocumentAdapter, p as assertValidVideoDocument, r as relayDocFromSnapshot, s as readVideoDocumentFromDraft, t as classifyUpdate, u as fromVideoDocument, v as findLaneTrack, w as recalculateTimelineDuration, x as arrangeMainTrackSeamlessly, y as solveVideoDocument } from "./loro-relay-doc-Br-ZJBHa.js";
+import { A as partDurationMs, C as reassignSpeechesToVideoClipsByTime, D as syncAggregatedClipsTimePosition, E as resolveSpeechOverlapByShiftingVideos, F as partUnionToDraft, I as recordEntries, L as videoDocumentMirrorSchema, M as DEFAULT_UNIT_TIME_MS, N as VIDEO_DOCUMENT_SCHEMA_VERSION, O as TIMELINE_SKELETON_DURATION_MS, P as effectiveVideoClipDurationMs, R as base64ToBytes, S as fillMainTrackTimeGaps, T as resolveAllSpeechOverlaps, _ as findLaneTrack, a as buildInitialVideoDocument, b as cascadeAfterVideoClipChanges, c as fromVideoDocument, d as assertValidVideoDocument, f as validateVideoDocument, g as ensureLaneTrack, h as LANE_KINDS_IN_STACK_ORDER, i as readVideoDocumentFromDraft, j as safeDurationMs, k as isEmptyVideoClip, l as toVideoDocument, m as videoDocumentSchema, n as createMirrorVideoDocument, o as buildSpeechHostMap, p as partUnionSchema, r as createMirrorVideoDocumentAdapter, s as derivePositionFromAbs, t as MirrorVideoDocumentAdapter, u as VideoDocumentValidationError, v as laneTrackId, w as recalculateTimelineDuration, x as arrangeMainTrackSeamlessly, y as solveVideoDocument, z as bytesToBase64 } from "./document-C0o_cjAH.js";
 import { z } from "zod";
 import { LoroDoc, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
@@ -2348,13 +2348,18 @@ var MedeoHttpDocStorage = class {
 		};
 	}
 	/**
-	* Forward one update to the server.
+	* Forward one update to the server, returning what the server says it now holds.
 	*
-	* The `DocStorage` contract returns `void`, so the server's verdict cannot be
-	* the return value — it is published on {@link subscribePushOutcome} instead,
-	* for BOTH outcomes and failures. That channel is what makes the push
-	* observable; previously the verdict was read and dropped, so a `duplicate`
-	* (bytes contributed nothing) was indistinguishable from a successful write.
+	* 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.
@@ -2362,21 +2367,22 @@ var MedeoHttpDocStorage = class {
 	*/
 	async pushDocUpdate(update, _origin) {
 		this.assertDocId(update.docId);
-		if (this.isReadonly || update.data.byteLength === 0) return;
+		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 = decodeServerVV(response.version?.server_vv);
 			this.events.emit("pushOutcome", {
 				kind: response.kind,
-				update: update.data,
 				updateSeq: response.update_seq ?? void 0,
-				serverVV: decodeServerVV(response.version?.server_vv)
+				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",
-				update: update.data,
 				code: rejected ? error.code : void 0,
 				error: failure
 			});
@@ -2469,6 +2475,7 @@ var MemoryDocStorage = class extends BaseDocStorage {
 			},
 			origin
 		});
+		return {};
 	}
 	async deleteDoc(docId) {
 		this.entries.delete(docId);
@@ -2511,7 +2518,11 @@ var MemoryDocStorage = class extends BaseDocStorage {
 //#region src/session/mengine-doc-session.ts
 /**
 * Raised by {@link MengineDocSession.waitForServerAck} when the local edits it
-* was asked to confirm did not reach the server in time, or were refused.
+* was asked to confirm were not acknowledged as durable.
+*
+* Named `...AckFailed`, not `...AckTimeout`: two of the three `reason` values are
+* not timeouts, and the earlier name made callers reach for a retry-after-delay
+* that is wrong for `rejected`.
 *
 * The distinction the caller needs is "was it written": if this throws, treat the
 * write as NOT durable. `reason` says which failure it was, and `code` carries the
@@ -2523,7 +2534,7 @@ var MemoryDocStorage = class extends BaseDocStorage {
 *   catch-up; `corrupt_update` never is.
 * - `failed` — transport/network failure; the server's answer is unknown.
 */
-var MengineAckTimeoutError = class extends Error {
+var MengineAckFailedError = class extends Error {
 	reason;
 	code;
 	cause;
@@ -2532,7 +2543,7 @@ var MengineAckTimeoutError = class extends Error {
 		this.reason = reason;
 		this.code = code;
 		this.cause = cause;
-		this.name = "MengineAckTimeoutError";
+		this.name = "MengineAckFailedError";
 	}
 };
 /**
@@ -2617,13 +2628,13 @@ var MengineDocSession = class {
 	* Returns early when the server is already known to be current, so a caller
 	* with nothing outstanding does not block.
 	*
-	* @throws {MengineAckTimeoutError} on timeout, rejection, or transport failure.
+	* @throws {MengineAckFailedError} on timeout, rejection, or transport failure.
 	*/
 	async waitForServerAck(options = {}) {
 		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
 		const timeoutMs = options.timeoutMs ?? 15e3;
 		const target = this.manager.connectDoc(this.docId).version();
-		if (this.serverVVValue != null && covers$1(this.serverVVValue, target)) return;
+		if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) return;
 		await new Promise((resolve, reject) => {
 			let off = () => {};
 			let done = false;
@@ -2636,14 +2647,14 @@ var MengineDocSession = class {
 				else reject(error);
 			};
 			const timer = setTimeout(() => {
-				settle(new MengineAckTimeoutError("timeout", void 0, void 0, `mengine did not acknowledge the update within ${timeoutMs}ms`));
+				settle(new MengineAckFailedError("timeout", void 0, void 0, `mengine did not acknowledge the update within ${timeoutMs}ms`));
 			}, timeoutMs);
 			off = this.server.subscribePushOutcome((outcome) => {
 				if (outcome.kind === "rejected" || outcome.kind === "failed") {
-					settle(new MengineAckTimeoutError(outcome.kind, outcome.code, outcome.error, outcome.error?.message ?? `mengine push ${outcome.kind}`));
+					settle(new MengineAckFailedError(outcome.kind, outcome.code, outcome.error, outcome.error?.message ?? `mengine push ${outcome.kind}`));
 					return;
 				}
-				if (outcome.serverVV != null && covers$1(outcome.serverVV, target)) settle(void 0);
+				if (outcome.serverVV != null && serverCovers(outcome.serverVV, target)) settle(void 0);
 			});
 		});
 	}
@@ -2746,24 +2757,25 @@ var MengineDocSession = class {
 	}
 };
 /**
-* True when the server version `serverVV` includes everything in `target`.
+* True when the *encoded* server version `serverVV` includes everything in
+* `target`. Thin decode wrapper over the shared {@link covers} predicate — an
+* undecodable blob is treated as "does not cover", so a corrupt server response
+* leaves a waiter waiting rather than falsely acking it.
 *
-* `VersionVector.compare` returns `undefined` for concurrent vectors — which is
-* the normal case here, since the server usually holds ops from other peers that
-* the local target does not. Concurrency alone must therefore NOT be read as "not
-* yet acked", so compare per-peer counters instead: every peer in `target` must
-* have advanced at least as far on the server. Extra server-side peers are
-* irrelevant to whether *our* ops landed.
+* The coverage rule itself (per-peer counters, never `VersionVector.compare`,
+* never equality) lives in `manual-sync/version-coverage.ts` with the reasoning.
+* An earlier revision reimplemented it here with a near-identical comment block;
+* two copies of one rule is exactly the duplication this project has been bitten
+* by repeatedly.
 */
-function covers$1(serverVV, target) {
+function serverCovers(serverVV, target) {
 	let server;
 	try {
 		server = VersionVector.decode(serverVV);
 	} catch {
 		return false;
 	}
-	for (const [peer, counter] of target.toJSON()) if ((server.get(peer) ?? 0) < counter) return false;
-	return true;
+	return covers(server, target);
 }
 //#endregion
-export { IMPLEMENTED_SEMANTIC_OP_KINDS, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckTimeoutError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, classifyUpdate, covers, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, mainTrackRanges, newRelayDoc, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, relayDocFromSnapshot, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };
+export { DEFAULT_UNIT_TIME_MS, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };

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 { $ as VideoDraft, i as MirrorVideoDocumentAdapter } from "./index-DLchEQG7.js";
+import { i as MirrorVideoDocumentAdapter, nt as VideoDraft } from "./index-DWVYLTjv.js";
 
 //#region src/testing/in-memory-mengine-server.d.ts
 /**

package/dist/testing.js

@@ -1,4 +1,5 @@
-import { L as base64ToBytes, M as VIDEO_DOCUMENT_SCHEMA_VERSION, R as bytesToBase64, o as createMirrorVideoDocumentAdapter, t as classifyUpdate } from "./loro-relay-doc-Br-ZJBHa.js";
+import { N as VIDEO_DOCUMENT_SCHEMA_VERSION, R as base64ToBytes, r as createMirrorVideoDocumentAdapter, z as bytesToBase64 } from "./document-C0o_cjAH.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
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mengine/medeo-client",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -14,6 +14,7 @@
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
+    "./relay": "./dist/relay.js",
     "./testing": "./dist/testing.js",
     "./package.json": "./package.json"
   },
@@ -24,9 +25,9 @@
   "dependencies": {
     "loro-mirror": "^2.2.0",
     "zod": "^4.4.3",
-    "@mengine/storage": "1.0.1",
-    "@mengine/sync": "1.0.1",
-    "@mengine/utils": "1.0.1"
+    "@mengine/sync": "1.2.0",
+    "@mengine/storage": "1.2.0",
+    "@mengine/utils": "1.2.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",