@mengine/medeo-client 1.0.1-alpha.1 → 1.0.1

package/dist/index.js

@@ -1,5 +1,7 @@
-import { A as isEmptyVideoClip, B as bytesToBase64, C as fillMainTrackTimeGaps, D as resolveSpeechOverlapByShiftingVideos, E as resolveAllSpeechOverlaps, F as speedOf, I as partUnionToDraft, L as recordEntries, M as safeDurationMs, N as VIDEO_DOCUMENT_SCHEMA_VERSION, O as syncAggregatedClipsTimePosition, P as effectiveVideoClipDurationMs, R as videoDocumentMirrorSchema, S as arrangeMainTrackSeamlessly, T as recalculateTimelineDuration, _ as videoDocumentSchema, a as createMirrorVideoDocument, b as solveVideoDocument, c as readVideoDocumentFromDraft, d as fromVideoDocument, f as toVideoDocument, g as partUnionSchema, h as validateVideoDocument, i as MirrorVideoDocumentAdapter, j as partDurationMs, k as TIMELINE_SKELETON_DURATION_MS, l as buildSpeechHostMap, m as assertValidVideoDocument, n as createPlainMemoryAdapter, o as createMirrorVideoDocumentAdapter, p as VideoDocumentValidationError, r as generatePartId, s as writeVideoDocumentToDraft, t as PlainMemoryAdapter, u as derivePositionFromAbs, v as ensureLaneTrack, w as reassignSpeechesToVideoClipsByTime, x as cascadeAfterVideoClipChanges, y as findLaneTrack, z as base64ToBytes } from "./document-DgffKwRw.js";
-import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
+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 { z } from "zod";
+import { LoroDoc, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
 import { DisposableSet, EventBus, Task } from "@mengine/utils";
 import { BaseDocStorage, DummyConnection } from "@mengine/storage";
@@ -22,6 +24,33 @@ var MengineHttpRequestError = class extends Error {
 		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;
@@ -51,15 +80,34 @@ var MengineHttpClient = class {
 	async audit() {
 		return await this.requestJson("audit");
 	}
-	async pushUpdate(update, baseVersion = null) {
-		const response = await this.requestJson("updates", {
-			method: "POST",
-			body: JSON.stringify({
-				update: bytesToBase64(update),
-				base_version: baseVersion
-			})
-		});
-		if (response.kind === "rejected") throw new MengineHttpRequestError(409, response);
+	/**
+	* 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() {
@@ -95,6 +143,20 @@ var MengineHttpClient = class {
 		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;
@@ -156,6 +218,566 @@ function findSseFrameBoundary(buffer) {
 	return Math.min(lf, crlf);
 }
 //#endregion
+//#region src/editor/id-gen.ts
+/**
+* Part-id generation, aligned with the online ecosystem.
+*
+* The authoritative online producers — agent-harness (`@harness/shared`
+* `genObjId`) and director.v2 (`common/obj_id.py` `gen_obj_id`) — both mint part
+* ids as `` `${prefix}_${ulid()}` ``, and real captured drafts use exactly that
+* shape (`clip_…` / `spe_…` / `cap_…` / `bgm_…`, each a 26-char ULID). The engine
+* previously emitted `vc_<base36 timestamp><6 random>`, a different prefix AND a
+* different encoding — the sole cross-repo id divergence. This module removes it
+* by emitting the same `<prefix>_<ULID>` bytes.
+*
+* The ULID is generated inline (Crockford Base32, 48-bit time + 80-bit random)
+* rather than pulling the `ulid` npm package: the randomness class matches the
+* old generator (both `Math.random`-based) and it keeps `@mengine/medeo-client`
+* dependency-free for a purely mechanical id string. Part ids only need to be
+* unique and lexicographically time-sortable, which this satisfies.
+*/
+/** Crockford Base32 alphabet (no I, L, O, U), per the ULID spec. */
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIME_LEN = 10;
+const RANDOM_LEN = 16;
+function encodeTime(now) {
+	let out = "";
+	let ms = now;
+	for (let i = TIME_LEN - 1; i >= 0; i--) {
+		const mod = ms % 32;
+		out = CROCKFORD[mod] + out;
+		ms = (ms - mod) / 32;
+	}
+	return out;
+}
+function encodeRandom() {
+	let out = "";
+	for (let i = 0; i < RANDOM_LEN; i++) out += CROCKFORD[Math.floor(Math.random() * 32)];
+	return out;
+}
+/** A 26-char Crockford Base32 ULID (10-char time + 16-char random). */
+function ulid() {
+	return encodeTime(Date.now()) + encodeRandom();
+}
+function generatePartId(prefix) {
+	return `${prefix}_${ulid()}`;
+}
+//#endregion
+//#region src/editor/schemas/shared.ts
+const clipIdSchema = z.string().min(1).describe("The clip part ID on the timeline");
+const clipIdsSchema = z.array(clipIdSchema).min(1).refine((ids) => new Set(ids).size === ids.length, { message: "Duplicate clip IDs are not allowed" }).describe("List of clip part IDs (no duplicates allowed)");
+const mediaIdSchema = z.string().min(1).describe("The media asset ID");
+const speechIdSchema = z.string().min(1).describe("The speech part ID on the timeline");
+const timelineMsSchema = z.number().int().min(0).describe("Time position in milliseconds on the timeline (>= 0)");
+const positiveMsSchema = z.number().int().positive().describe("Duration in milliseconds (> 0)");
+const volumeSchema = z.number().min(-60).max(20).describe("Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)");
+const speechIdsSchema = z.array(speechIdSchema).min(1).refine((ids) => new Set(ids).size === ids.length, { message: "Duplicate speech IDs are not allowed" }).describe("List of speech part IDs (no duplicates allowed)");
+const tangentHandleSchema = z.object({
+	x: z.number().finite(),
+	y: z.number().finite()
+}).describe("Bezier tangent handle (x, y)");
+const speedKeyframeSchema = z.object({
+	position: z.number().min(0).max(1),
+	rate: z.number().min(0),
+	in_tangent: tangentHandleSchema.optional(),
+	out_tangent: tangentHandleSchema.optional()
+}).describe("A speed keyframe: normalized position (0..1), rate, optional tangents");
+/**
+* A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.
+* Mirrors the IDL `SpeedShift`: `category` is `linear` | `curve`, and `config`
+* is a discriminated union — `{ linear: { speed } }` for a constant multiplier
+* (the multiplier projection reads at `config.linear.speed`) or `{ curve: {
+* keyframes } }` for a Bezier-controlled variable speed (RFC 02 / `reference/16`
+* §0). Exactly one of `linear` / `curve` is present.
+*/
+const speedShiftSchema = z.object({
+	category: z.enum(["linear", "curve"]),
+	mode: z.string(),
+	config: z.union([z.object({ linear: z.object({ speed: z.number().finite().positive() }) }), z.object({ curve: z.object({ keyframes: z.array(speedKeyframeSchema).min(2) }) })])
+}).describe("Speed shift: linear multiplier or Bezier curve, mirroring the IDL shape");
+const voiceSchema = z.object({
+	id: z.string().min(1),
+	name: z.string()
+}).describe("TTS voice summary attached to a speech");
+//#endregion
+//#region src/editor/schemas/speech-assets.ts
+/**
+* The materialized TTS result shared by `AddSpeeches` / `ChangeSpeechScript` /
+* `ChangeSpeechVoice` (see `results/phase-4-side-effect-payload-contract.md`
+* §1/§2). The side effect (TTS/ASR + billing) runs upstream; the op receives the
+* stable speech + caption parts and writes them as authoritative facts. No
+* cascade runs on write — the projection derives absolute positions on read.
+*
+* Each speech carries the anchoring fact directly (RFC 02 §4): the host video
+* clip `anchor_part_id` and the `offset_ms` within it. The upstream caller
+* already knows which clip a speech attaches to, so the op writes
+* `{ mode:'anchored', anchorPartId, offsetMs }` verbatim — no write-time
+* host-picking. Captions anchor to their speech via the caption part's
+* `start_ms` (offset within the speech).
+*/
+const speechAssetSchema = z.object({
+	speech_id: speechIdSchema.describe("The speech part ID (= side-effect speech_parts[].id)"),
+	anchor_part_id: clipIdSchema.describe("Host video clip part ID the speech anchors to (RFC 02 §4)"),
+	offset_ms: timelineMsSchema.describe("Offset within the host clip (speech.abs = host.abs + offset_ms)"),
+	audio_storage_key: z.string().min(1),
+	duration_ms: positiveMsSchema,
+	audio_script: z.string(),
+	volume: volumeSchema,
+	voice: voiceSchema,
+	origin_speech_id: z.string().min(1),
+	caption_ids: z.array(z.string().min(1)).describe("Caption part IDs owned by this speech")
+});
+const captionAssetSchema = z.object({
+	caption_id: z.string().min(1).describe("The caption part ID (= side-effect created_caption_parts[].id)"),
+	speech_part_id: speechIdSchema.describe("The owning speech part ID"),
+	text: z.string(),
+	start_ms: timelineMsSchema.describe("Offset within the host speech (caption.abs = speech.abs + start_ms)"),
+	duration_ms: positiveMsSchema
+});
+/** A materialized speech-subtree write (speeches + their captions). */
+const speechAssetsSchema = z.object({
+	speeches: z.array(speechAssetSchema).min(1).describe("Materialized speech parts to write"),
+	captions: z.array(captionAssetSchema).describe("Materialized caption parts owned by the speeches")
+});
+//#endregion
+//#region src/editor/schemas/add-speeches.ts
+/**
+* Add speeches (and their captions). TTS runs upstream; the stable speech /
+* caption parts arrive materialized (see `speech-assets.ts`). The op writes the
+* parts and each speech's `{ mode:'anchored', anchorPartId, offsetMs }` fact
+* verbatim — no write-time host-picking, no cascade (RFC 02 §4). The projection
+* derives absolute positions on read.
+*/
+const addSpeechesInputSchema = speechAssetsSchema.describe("Materialized speeches + captions to add");
+//#endregion
+//#region src/editor/schemas/add-video-clips.ts
+/**
+* Add video clips to a track. Each clip's duration facts are separated so a
+* single number is never overloaded (RFC 02 / `reference/16` §0b):
+*
+* - `media_duration_ms` is the source media's intrinsic full length (a resource
+*   fact, written to the part);
+* - `play_in` / `play_out` are the optional trim window into that media; when
+*   omitted the whole media is used (`play_in=0`, `play_out=media_duration_ms`).
+*
+* The clip's effective timeline duration is derived by the projection from the
+* trim window and `speed_shift` — it is never an input here.
+*/
+const addVideoClipsInputSchema = z.object({
+	clips: z.array(z.object({
+		media_id: mediaIdSchema.describe("The media asset ID for the video clip"),
+		start_ms: timelineMsSchema.optional().describe("Absolute start time in milliseconds on the timeline"),
+		media_duration_ms: positiveMsSchema.describe("The source media's intrinsic full length in ms"),
+		play_in: timelineMsSchema.optional().describe("Trim window start in the media (default 0)"),
+		play_out: positiveMsSchema.optional().describe("Trim window end in the media (default media_duration_ms)"),
+		track_id: z.string().min(1).optional().describe("Target track ID (optional, defaults to main track)")
+	})).min(1).describe("List of video clips to create"),
+	before_clip_id: z.string().min(1).optional().describe("Insert new clips before this clip ID"),
+	after_clip_id: z.string().min(1).optional().describe("Insert new clips after this clip ID")
+}).superRefine((data, ctx) => {
+	if (data.before_clip_id != null && data.after_clip_id != null) {
+		ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: "Cannot provide both before_clip_id and after_clip_id"
+		});
+		return;
+	}
+	const hasRelative = data.before_clip_id != null || data.after_clip_id != null;
+	for (let i = 0; i < data.clips.length; i++) {
+		const clip = data.clips[i];
+		if (hasRelative && clip.start_ms != null) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `clips[${i}].start_ms must not be provided when using before_clip_id or after_clip_id`,
+			path: [
+				"clips",
+				i,
+				"start_ms"
+			]
+		});
+		if (!hasRelative && clip.start_ms == null) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `clips[${i}].start_ms is required when not using relative positioning`,
+			path: [
+				"clips",
+				i,
+				"start_ms"
+			]
+		});
+		const playIn = clip.play_in ?? 0;
+		const playOut = clip.play_out ?? clip.media_duration_ms;
+		if (playOut > clip.media_duration_ms) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `clips[${i}].play_out ${playOut}ms exceeds media_duration_ms ${clip.media_duration_ms}ms`,
+			path: [
+				"clips",
+				i,
+				"play_out"
+			]
+		});
+		if (playIn >= playOut) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `clips[${i}].play_in ${playIn}ms must be less than play_out ${playOut}ms`,
+			path: [
+				"clips",
+				i,
+				"play_in"
+			]
+		});
+	}
+});
+//#endregion
+//#region src/editor/schemas/adjust-bgm-volume.ts
+const adjustBgmVolumeInputSchema = z.object({ bgm: z.array(z.object({
+	bgm_id: clipIdSchema.describe("The bgm part ID to adjust volume for"),
+	volume: volumeSchema.describe("Volume in decibels (-60.0 to 20.0; 0.0 = original)")
+})).min(1).describe("List of bgm parts with their new volume settings") });
+//#endregion
+//#region src/editor/schemas/adjust-speech-volume.ts
+const adjustSpeechVolumeInputSchema = z.object({ speeches: z.array(z.object({
+	speech_id: speechIdSchema.describe("The speech part ID to adjust volume for"),
+	volume: volumeSchema.describe("Volume in decibels (-60.0 to 20.0; 0.0 = original)")
+})).min(1).describe("List of speeches with their new volume settings") });
+//#endregion
+//#region src/editor/schemas/adjust-video-clip-duration.ts
+/**
+* Re-trim existing video clips (the user-facing "adjust duration" gesture is a
+* trim of the source window). The new `play_in` / `play_out` are the facts; the
+* effective timeline duration is derived from them and the clip's `speed_shift`,
+* and the change reflows downstream clips, speeches, and the timeline inside the
+* op's transaction (no caller-materialized cascade).
+*/
+const adjustVideoClipDurationInputSchema = z.object({ clips: z.array(z.object({
+	clip_id: clipIdSchema.describe("The video clip part ID to re-trim"),
+	play_in: timelineMsSchema.describe("New trim window start in the source media"),
+	play_out: positiveMsSchema.describe("New trim window end in the source media")
+})).min(1).describe("Video clips with their new trim windows") });
+//#endregion
+//#region src/editor/schemas/adjust-video-clip-volume.ts
+const adjustVideoClipVolumeInputSchema = z.object({ clips: z.array(z.object({
+	clip_id: clipIdSchema.describe("The video clip part ID to adjust volume for"),
+	volume: volumeSchema.describe("Volume in decibels (-60.0 to 20.0; 0.0 = original)")
+})).min(1).describe("List of video clips with their new volume settings") });
+//#endregion
+//#region src/editor/schemas/change-speech.ts
+/**
+* Change a speech's script or voice. Both re-run TTS upstream and return the
+* regenerated speech / caption parts in the same materialized shape as
+* `AddSpeeches` (`speech-assets.ts`); the op upserts them by id (the speech part
+* id is preserved across a re-TTS), re-seats at `start_ms`, and reflows. Old
+* caption parts no longer owned by the speech are removed via `caption_ids`.
+*/
+const changeSpeechScriptInputSchema = speechAssetsSchema.describe("Regenerated speeches + captions (new script)");
+const changeSpeechVoiceInputSchema = speechAssetsSchema.describe("Regenerated speeches + captions (new voice)");
+//#endregion
+//#region src/editor/schemas/delete-bgm.ts
+/**
+* Remove the document BGM. Pure document edit: clears the bgm lane and removes
+* the bgm part. Takes no input (a document holds at most one bgm); an empty
+* object keeps the op signature uniform with the rest.
+*/
+const deleteBgmInputSchema = z.object({}).describe("Remove the document BGM (no parameters)");
+//#endregion
+//#region src/editor/schemas/delete-speeches.ts
+/**
+* Delete speeches with their captions. Pure document edit (no side effect): the
+* op removes each speech part, cascade-deletes the captions it owns (via
+* `caption_ids` / `speech_part_id`), drops their track items, and reflows.
+*/
+const deleteSpeechesInputSchema = z.object({ speech_ids: speechIdsSchema.describe("Speech part IDs to delete (their captions cascade-delete)") });
+//#endregion
+//#region src/editor/schemas/delete-video-clips.ts
+/**
+* How a delete handles the anchored subtree (speeches anchored to a deleted clip,
+* and their captions) — a delete-op policy, not a data-model field (reference/17
+* §6). `cascade` (default) removes the subtree; `detach` keeps the direct
+* anchored children, re-pinning them to `absolute` so they stay on the timeline.
+*/
+const anchoredDeletePolicySchema = z.enum(["cascade", "detach"]);
+const deleteVideoClipsInputSchema = z.object({
+	clip_ids: clipIdsSchema.describe("List of video clip part IDs to delete from the main track"),
+	on_anchored: anchoredDeletePolicySchema.optional().describe("How to treat anchored children (default cascade)")
+});
+//#endregion
+//#region src/editor/schemas/move-speeches.ts
+/**
+* Move speeches in time. Pure document edit: the op re-seats each speech at its
+* new absolute `start_ms`; the cascade reassigns it to the host video clip,
+* resolves overlaps, and reflows. Captions follow their speech.
+*/
+const moveSpeechesInputSchema = z.object({ speeches: z.array(z.object({
+	speech_id: speechIdSchema.describe("The speech part ID to move"),
+	new_start_ms: timelineMsSchema.describe("New absolute start time on the timeline")
+})).min(1).describe("Speeches to move to new positions") });
+//#endregion
+//#region src/editor/schemas/move-video-clips-by-anchor.ts
+/**
+* Where the moved block lands on the main track.
+*
+* A discriminated union rather than two optional `before_clip_id` /
+* `after_clip_id` fields (the shape `addVideoClips` had to use, because there the
+* two modes share a whole clip description): here the alternatives carry nothing
+* in common, so making them mutually exclusive *by type* removes three runtime
+* `superRefine` checks that would otherwise have to be written and tested.
+*
+* `track_start` is an explicit member, not the absence of an anchor. The
+* agent-harness mutation this maps from treats "neither anchor given" as
+* "move to the front" (`applyBatchMoveVideoClips` falls back to `insertIndex = 0`),
+* which is a default buried in a tool description. Requiring the caller to name
+* that intent keeps a forgotten field from silently reordering the timeline.
+*/
+const moveAnchorSchema = z.discriminatedUnion("position", [
+	z.object({
+		position: z.literal("before"),
+		clip_id: clipIdSchema.describe("The moved block lands immediately before this clip")
+	}),
+	z.object({
+		position: z.literal("after"),
+		clip_id: clipIdSchema.describe("The moved block lands immediately after this clip")
+	}),
+	z.object({ position: z.literal("track_start") })
+]).describe("Where the moved block lands: before/after a reference clip, or at the head of the track");
+/**
+* What happens to the speeches anchored to the clips being moved.
+*
+* - `follow` keeps each speech anchored where it is, so it travels with its clip
+*   to the new position. In the anchored model this is the *no-op* branch: a
+*   speech's authoritative fact is `{ anchorPartId, offsetMs }` and its absolute
+*   time is derived on read from the host's position, so moving the host moves
+*   the speech with no write to the speech at all.
+* - `keep_absolute` preserves each speech's current absolute landing instead, then
+*   re-anchors it to whichever clip now covers that time (RFC 02 §9.1/§11.1). This
+*   is the branch that costs an extra pass, and the one the FE timeline uses.
+*
+* **Required, with no default**, matching `deleteVideoClips` and
+* `replaceVideoClipSequence`. The two branches decide which picture the user's
+* narration ends up over, which is too consequential to infer from a missing
+* field — and neither branch is "safe enough" to be the implicit one.
+*/
+const movedClipAnchoredPolicySchema = z.enum(["follow", "keep_absolute"]);
+/**
+* Reorder a set of main-track clips relative to a reference clip.
+*
+* Distinct from `moveVideoClips`, which positions clips by absolute time
+* (`new_start_ms`) and is what the FE timeline dispatches after a drag. Main-track
+* clips are `sequential`-positioned, so absolute time is not authoritative state
+* there (RFC 02 §4/§7): `moveVideoClips` has to *guess* an index back out of the
+* time it was handed, whereas an anchor already is the ordinal fact being changed.
+* Keeping them separate also isolates blast radius — this method can diverge on
+* speech policy without touching the FE path.
+*
+* `clip_ids` need not be contiguous. They move as one block, keeping their
+* relative order, which is the agent-harness `batch_move_video_clips` contract.
+*/
+const moveVideoClipsByAnchorInputSchema = z.object({
+	clip_ids: clipIdsSchema.describe("Clips to move as one block, keeping their relative order. Need not be contiguous on the track."),
+	anchor: moveAnchorSchema,
+	on_anchored: movedClipAnchoredPolicySchema.describe("What happens to speeches anchored to the moved clips (required — see the policy doc)")
+});
+//#endregion
+//#region src/editor/schemas/move-video-clips.ts
+const moveVideoClipsInputSchema = z.object({ clips: z.array(z.object({
+	clip_id: clipIdSchema.describe("The video clip part ID to move"),
+	new_start_ms: timelineMsSchema.describe("New absolute start time in milliseconds on the timeline"),
+	new_track_id: z.string().min(1).optional().describe("Target track ID to move the clip to (optional)")
+})).min(1).describe("List of video clips to move to new positions") });
+//#endregion
+//#region src/editor/schemas/replace-video-clip-content.ts
+/**
+* Replace the media backing existing video clips. The media import runs upstream
+* (Director); its stable result — the new media id, intrinsic length, and the
+* reset trim window — arrives materialized (see
+* `results/phase-4-side-effect-payload-contract.md` §4). Director resets
+* `play_in=0` / `play_out=media_duration_ms` and clears `speed_shift` on
+* replacement. The clip `part_id`s (hence their track items) are unchanged; the
+* editor reflows the main track from the new effective durations.
+*/
+const replaceVideoClipContentInputSchema = z.object({ clips: z.array(z.object({
+	clip_id: clipIdSchema.describe("Existing video clip part ID to re-point"),
+	origin_media_id: mediaIdSchema.describe("The new media asset ID"),
+	media_duration_ms: positiveMsSchema.describe("The new media's intrinsic full length"),
+	play_in: timelineMsSchema.describe("Trim window start in the new media (usually 0)"),
+	play_out: positiveMsSchema.describe("Trim window end in the new media (usually = media_duration_ms)"),
+	volume: volumeSchema
+})).min(1).describe("Video clips whose media is being replaced") });
+//#endregion
+//#region src/editor/schemas/replace-video-clip-sequence.ts
+/**
+* What happens to the speeches anchored to the clips being replaced.
+*
+* - `remap` re-anchors each surviving speech to the new clip in the SAME POSITION
+*   of the sequence, keeping its offset — old[i]'s children become new[i]'s
+*   children. An old clip with no counterpart (fewer new clips than old) has its
+*   subtree deleted, because there is nothing left to anchor to.
+* - `cascade` deletes every anchored speech (and its captions) outright, like
+*   `deleteVideoClips`.
+*
+* **Required, with no default.** The two branches differ in whether the user's
+* narration survives, and the agent tool that drives this op makes its
+* `preserve_speeches` flag required for that reason. A default here would let a
+* caller that forgot the field silently delete speech.
+*/
+const anchoredReplacePolicySchema = z.enum(["remap", "cascade"]);
+/**
+* Replace a contiguous run of main-track clips with a new run.
+*
+* A composite of delete + insert that cannot be expressed as the two ops in
+* sequence, because the anchored speeches have to survive *across* the swap: with
+* `remap` they are re-anchored positionally, which needs both the old and the new
+* ids in the same transaction (ADR 0009 — the cascade stays in the editor, callers
+* never re-wire anchors themselves).
+*
+* Duration facts follow `addVideoClips`: `media_duration_ms` is the source's
+* intrinsic length and the trim window defaults to the whole media. The effective
+* timeline duration is derived by the projection, never an input.
+*
+* `media_id` is optional: omitting it creates a **deliberate empty placeholder
+* clip** (`origin_media_id: ''`) — structure with no picture. This is the only op
+* that can produce one, and it is authoritative state, unlike the gap fillers the
+* read-side solve mints (which never enter the document).
+*/
+const replaceVideoClipSequenceInputSchema = z.object({
+	old_clip_ids: clipIdsSchema.describe("The clips being replaced: a contiguous main-track run, listed in timeline order"),
+	new_clips: z.array(z.object({
+		media_id: mediaIdSchema.optional().describe("The replacement media asset ID. Omit to create an empty placeholder clip."),
+		media_duration_ms: positiveMsSchema.describe("The source media's intrinsic full length in ms"),
+		play_in: timelineMsSchema.optional().describe("Trim window start in the media (default 0)"),
+		play_out: positiveMsSchema.optional().describe("Trim window end in the media (default media_duration_ms)")
+	})).min(1).describe("The replacement clips, in the order they take on the track"),
+	on_anchored: anchoredReplacePolicySchema.describe("What happens to speeches anchored to the replaced clips (required — see the policy doc)")
+}).superRefine((data, ctx) => {
+	for (let i = 0; i < data.new_clips.length; i++) {
+		const clip = data.new_clips[i];
+		const playIn = clip.play_in ?? 0;
+		const playOut = clip.play_out ?? clip.media_duration_ms;
+		if (playOut > clip.media_duration_ms) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `new_clips[${i}].play_out ${playOut}ms exceeds media_duration_ms ${clip.media_duration_ms}ms`,
+			path: [
+				"new_clips",
+				i,
+				"play_out"
+			]
+		});
+		if (playIn >= playOut) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `new_clips[${i}].play_in ${playIn}ms must be less than play_out ${playOut}ms`,
+			path: [
+				"new_clips",
+				i,
+				"play_in"
+			]
+		});
+	}
+});
+//#endregion
+//#region src/editor/schemas/set-bgm.ts
+/**
+* Set the document BGM. The media's stable result (storage key) arrives
+* materialized from upstream (see
+* `results/phase-4-side-effect-payload-contract.md` §3). The op upserts the bgm
+* part and seats it on the bgm lane; its effective length is always the whole
+* timeline, derived by the projection on read — so there is no `duration_ms`
+* input or fact (RFC 02 / `reference/16` §0b). A `bgm_id` lets the op replace an
+* existing bgm part by id.
+*/
+const setBgmInputSchema = z.object({
+	bgm_id: z.string().min(1).describe("The bgm part ID to write"),
+	audio_storage_key: z.string().min(1),
+	origin_media_id: mediaIdSchema,
+	volume: volumeSchema
+});
+//#endregion
+//#region src/editor/schemas/set-caption-style.ts
+/**
+* Set the caption visual style. GLOBAL by design: the style applies to every
+* caption part in the document — it carries NO `caption_id`. This mirrors the FE,
+* whose caption-style store (`caption-style.ts:persistCaptionStylePatch`) iterates
+* ALL captions and writes the same normalized style to each; the product has a
+* single document-wide caption style, not per-caption styling.
+*
+* Every field is optional and maps to a `CaptionStyle` attribute (snake_case
+* IDL). A field present in the input is written to every caption; a field ABSENT
+* from the input is left untouched on each caption (the editor merges the patch
+* onto each caption's existing style — this is a value edit, not a full-style
+* replace, so a partial patch such as "recolor only" does not wipe font size).
+*
+* Pure document edit, no cascade — captions keep their positions; only the style
+* sub-map of each caption part changes.
+*/
+const setCaptionStyleInputSchema = z.object({
+	font_id: z.string().min(1).optional().describe("Font ID referencing a font from the font library"),
+	font_size: z.number().positive().optional().describe("Font size in points"),
+	font_color: z.string().min(1).optional().describe("Font color as hex string, e.g. \"#FFFFFF\""),
+	font_weight: z.number().int().optional().describe("Numeric font weight, e.g. 400 or 700"),
+	entrance_animation: z.string().optional().describe("Entrance animation preset ID, e.g. \"fade\" or \"none\""),
+	entrance_animation_duration_ms: z.number().min(0).optional().describe("Entrance animation duration in ms"),
+	stroke_color: z.string().min(1).optional().describe("Outline/stroke color as hex string, e.g. \"#000000\""),
+	stroke_width: z.number().min(0).optional().describe("Outline/stroke width in pixels"),
+	position_x: z.number().optional().describe("Caption center X as a fraction (0.0 to 1.0)"),
+	position_y: z.number().optional().describe("Caption center Y as a fraction (0.0 to 1.0)")
+}).describe("Document-wide caption style patch (no caption_id; applies to every caption)");
+//#endregion
+//#region src/editor/schemas/set-caption-visibility.ts
+/**
+* Toggle caption visibility (the caption track's `is_hidden` flag). Pure
+* document edit, no cascade — captions keep their positions; only the lane's
+* hidden flag changes.
+*/
+const setCaptionVisibilityInputSchema = z.object({ is_hidden: z.boolean().describe("Whether the caption track is hidden") });
+//#endregion
+//#region src/editor/schemas/set-video-clip-speed-shift.ts
+/**
+* Set the playback speed of existing video clips. Per the speed-shift decision
+* (`reference/16` §0): the op writes only the `speed_shift` fact — it does NOT
+* store an effective `duration_ms` (projection derives it from the trim window /
+* speed) and does NOT scale anchored speeches' relative offsets (offsets stay
+* put; the cascade reflows absolute positions). A `null` speed_shift clears the
+* speed back to original (1×).
+*/
+const setVideoClipSpeedShiftInputSchema = z.object({ clips: z.array(z.object({
+	clip_id: clipIdSchema.describe("The video clip part ID to set speed for"),
+	speed_shift: speedShiftSchema.nullable().describe("The new speed setting, or null to reset to 1×")
+})).min(1).describe("Video clips with their new speed settings") });
+//#endregion
+//#region src/editor/schemas/index.ts
+var schemas_exports = /* @__PURE__ */ __exportAll({
+	addSpeechesInputSchema: () => addSpeechesInputSchema,
+	addVideoClipsInputSchema: () => addVideoClipsInputSchema,
+	adjustBgmVolumeInputSchema: () => adjustBgmVolumeInputSchema,
+	adjustSpeechVolumeInputSchema: () => adjustSpeechVolumeInputSchema,
+	adjustVideoClipDurationInputSchema: () => adjustVideoClipDurationInputSchema,
+	adjustVideoClipVolumeInputSchema: () => adjustVideoClipVolumeInputSchema,
+	anchoredDeletePolicySchema: () => anchoredDeletePolicySchema,
+	anchoredReplacePolicySchema: () => anchoredReplacePolicySchema,
+	changeSpeechScriptInputSchema: () => changeSpeechScriptInputSchema,
+	changeSpeechVoiceInputSchema: () => changeSpeechVoiceInputSchema,
+	clipIdSchema: () => clipIdSchema,
+	clipIdsSchema: () => clipIdsSchema,
+	deleteBgmInputSchema: () => deleteBgmInputSchema,
+	deleteSpeechesInputSchema: () => deleteSpeechesInputSchema,
+	deleteVideoClipsInputSchema: () => deleteVideoClipsInputSchema,
+	mediaIdSchema: () => mediaIdSchema,
+	moveAnchorSchema: () => moveAnchorSchema,
+	moveSpeechesInputSchema: () => moveSpeechesInputSchema,
+	moveVideoClipsByAnchorInputSchema: () => moveVideoClipsByAnchorInputSchema,
+	moveVideoClipsInputSchema: () => moveVideoClipsInputSchema,
+	movedClipAnchoredPolicySchema: () => movedClipAnchoredPolicySchema,
+	positiveMsSchema: () => positiveMsSchema,
+	replaceVideoClipContentInputSchema: () => replaceVideoClipContentInputSchema,
+	replaceVideoClipSequenceInputSchema: () => replaceVideoClipSequenceInputSchema,
+	setBgmInputSchema: () => setBgmInputSchema,
+	setCaptionStyleInputSchema: () => setCaptionStyleInputSchema,
+	setCaptionVisibilityInputSchema: () => setCaptionVisibilityInputSchema,
+	setVideoClipSpeedShiftInputSchema: () => setVideoClipSpeedShiftInputSchema,
+	speechAssetsSchema: () => speechAssetsSchema,
+	speechIdSchema: () => speechIdSchema,
+	speechIdsSchema: () => speechIdsSchema,
+	speedShiftSchema: () => speedShiftSchema,
+	timelineMsSchema: () => timelineMsSchema,
+	voiceSchema: () => voiceSchema,
+	volumeSchema: () => volumeSchema
+});
+//#endregion
 //#region src/editor/snapshot-utils.ts
 function isMap(value) {
 	return value instanceof Map;
@@ -260,6 +882,27 @@ var SchemaValidator = class {
 		const knownIds = this.mainTrackIds(doc);
 		for (const clip of parsed.clips) if (!knownIds.has(clip.clip_id)) throw new ValidationError("move_clip_not_found", `clip_id "${clip.clip_id}" not present on main_track`, { clip_id: clip.clip_id });
 	}
+	/**
+	* The anchor must not be one of the clips being moved. Unlike the schema's
+	* mutual exclusions this needs the input read as a whole, so it stays here.
+	*
+	* Rejected rather than normalized: "put this block before itself" has no
+	* defensible outcome — treating it as a no-op hides a caller bug behind a
+	* success, and picking any surviving neighbour invents an intent. The legacy
+	* `applyBatchMoveVideoClips` omits this check (a self-anchor there silently
+	* lands the block at its own pre-move index); director's original move tool
+	* did enforce it (`_validate_position`: "不是被移动的clips"), and that is the
+	* behaviour worth keeping.
+	*/
+	validateMoveVideoClipsByAnchor(input, doc) {
+		const parsed = this.parse(moveVideoClipsByAnchorInputSchema, input, "move_by_anchor_invalid_input");
+		const knownIds = this.mainTrackIds(doc);
+		for (const clipId of parsed.clip_ids) if (!knownIds.has(clipId)) throw new ValidationError("move_by_anchor_clip_not_found", `clip_id "${clipId}" not present on main_track`, { clip_id: clipId });
+		if (parsed.anchor.position === "track_start") return;
+		const anchorId = parsed.anchor.clip_id;
+		if (!knownIds.has(anchorId)) throw new ValidationError("move_by_anchor_anchor_not_found", `anchor clip_id "${anchorId}" not present on main_track`, { anchor_clip_id: anchorId });
+		if (parsed.clip_ids.includes(anchorId)) throw new ValidationError("move_by_anchor_anchor_is_moved", `anchor clip_id "${anchorId}" is itself being moved`, { anchor_clip_id: anchorId });
+	}
 	validateDeleteVideoClips(input, doc) {
 		const parsed = this.parse(deleteVideoClipsInputSchema, input, "delete_invalid_input");
 		const knownIds = this.mainTrackIds(doc);
@@ -294,6 +937,26 @@ var SchemaValidator = class {
 			});
 		}
 	}
+	/**
+	* `old_clip_ids` must name a **contiguous run of the main track, in track
+	* order**. A sparse or reordered selection is rejected rather than normalized:
+	* a sparse selection has no single stretch to swap, so the insert index, the
+	* positional speech remap, and the resulting order would each need a different
+	* arbitrary choice. Mirrors the agent tool's own contract ("must be a
+	* contiguous main-track sequence listed in timeline order").
+	*/
+	validateReplaceVideoClipSequence(input, doc) {
+		const parsed = this.parse(replaceVideoClipSequenceInputSchema, input, "replace_sequence_invalid_input");
+		const items = readMainTrackItems(doc.snapshot());
+		const indexById = new Map(items.map((it, index) => [it.part_id, index]));
+		const indices = [];
+		for (const clipId of parsed.old_clip_ids) {
+			const index = indexById.get(clipId);
+			if (index == null) throw new ValidationError("replace_sequence_clip_not_found", `clip_id "${clipId}" not present on main_track`, { clip_id: clipId });
+			indices.push(index);
+		}
+		for (let i = 1; i < indices.length; i++) if (indices[i] !== (indices[i - 1] ?? 0) + 1) throw new ValidationError("replace_sequence_not_contiguous", `old_clip_ids must be a contiguous main-track run in track order, got indices [${indices.join(", ")}]`, { indices });
+	}
 	validateAdjustVideoClipDuration(input, doc) {
 		const parsed = this.parse(adjustVideoClipDurationInputSchema, input, "adjust_duration_invalid_input");
 		const snapshot = doc.snapshot();
@@ -463,11 +1126,9 @@ function readPartLibrary(draft) {
 var SemanticEditor = class {
 	doc;
 	validator;
-	idFactory;
-	constructor(doc, validator = new SchemaValidator(), idFactory = generatePartId) {
+	constructor(doc, validator = new SchemaValidator()) {
 		this.doc = doc;
 		this.validator = validator;
-		this.idFactory = idFactory;
 	}
 	async moveVideoClips(input, options) {
 		this.validator.validateMoveVideoClips(input, this.doc);
@@ -486,6 +1147,44 @@ var SemanticEditor = class {
 			reparentSpeechesAfterMainTrackChange(draft, beforeRanges);
 		}, audit("MoveVideoClips", input, options));
 	}
+	/**
+	* Reorder main-track clips relative to an anchor clip, moving them as one block.
+	*
+	* The ordinal sibling of `moveVideoClips`: main-track clips are
+	* `sequential`-positioned, so their order is the authoritative fact and absolute
+	* time is derived on read (RFC 02 §4/§7). A caller that already knows "put these
+	* after that one" should say so, instead of computing a timeline offset that this
+	* editor would only have to resolve back into an index.
+	*
+	* `on_anchored` decides the speech treatment and is required. Note the asymmetry
+	* in cost: `follow` writes nothing to the speeches (their `{ anchorPartId,
+	* offsetMs }` facts stay valid and the derived absolute time moves with the host),
+	* while `keep_absolute` runs the extra re-parent pass that preserves each
+	* speech's absolute landing. `moveVideoClips` is permanently `keep_absolute`,
+	* matching the FE timeline it serves.
+	*/
+	async moveVideoClipsByAnchor(input, options) {
+		this.validator.validateMoveVideoClipsByAnchor(input, this.doc);
+		this.doc.transact((draft) => {
+			const items = mainTrackItems(draft);
+			if (items == null) return;
+			const beforeRanges = mainTrackRanges(draft);
+			const targets = new Set(input.clip_ids);
+			const movedIndices = [];
+			for (let i = 0; i < items.length; i++) {
+				const partId = items[i]?.part_id;
+				if (partId != null && targets.has(partId)) movedIndices.push(i);
+			}
+			if (movedIndices.length === 0) return;
+			const insertIndex = anchorInsertIndex(items, input.anchor);
+			const moved = movedIndices.map((index) => items[index]);
+			for (let i = movedIndices.length - 1; i >= 0; i--) items.splice(movedIndices[i], 1);
+			const removedBefore = movedIndices.filter((index) => index < insertIndex).length;
+			items.splice(insertIndex - removedBefore, 0, ...moved);
+			if (input.on_anchored === "keep_absolute") reparentSpeechesAfterMainTrackChange(draft, beforeRanges);
+			else refreshAnchoredFallbackAbs(draft);
+		}, audit("MoveVideoClipsByAnchor", input, options));
+	}
 	async deleteVideoClips(input, options) {
 		this.validator.validateDeleteVideoClips(input, this.doc);
 		const targets = new Set(input.clip_ids);
@@ -509,7 +1208,7 @@ var SemanticEditor = class {
 			track.items ??= [];
 			let at = insertIndex;
 			for (const clip of input.clips) {
-				const partId = this.idFactory("clip");
+				const partId = generatePartId("clip");
 				setPart(draft, partId, { video_clip: {
 					id: partId,
 					kind: "video_clip",
@@ -527,6 +1226,65 @@ var SemanticEditor = class {
 			}
 		}, audit("AddVideoClips", input, options));
 	}
+	/**
+	* Swap a contiguous run of main-track clips for a new run, in one transaction.
+	*
+	* Composite by necessity, not convenience: with `on_anchored: 'remap'` each
+	* surviving speech is re-anchored to the new clip in the **same position of the
+	* sequence** (old[i] → new[i]), which needs both id sets live at once. Splitting
+	* it into `deleteVideoClips` + `addVideoClips` would leave the caller holding the
+	* anchor re-wiring — the cascade-in-the-caller mistake ADR 0009 retires.
+	*
+	* Positional pairing, not by count: when there are fewer new clips than old, the
+	* unmatched old clips have no counterpart, so their anchored subtrees are deleted
+	* (there is nothing to anchor to). When there are more new clips than old, the
+	* extra ones simply arrive with no children.
+	*
+	* The new clips are inserted where the run started, so surrounding order is
+	* preserved. Every position is derived on read (RFC 02 §7) — this writes only the
+	* facts: track order, the trim windows, and the surviving anchors.
+	*/
+	async replaceVideoClipSequence(input, options) {
+		this.validator.validateReplaceVideoClipSequence(input, this.doc);
+		this.doc.transact((draft) => {
+			const track = mainTrackRow(draft);
+			if (track?.items == null) return;
+			const targets = new Set(input.old_clip_ids);
+			const insertIndex = track.items.findIndex((item) => item?.part_id != null && targets.has(item.part_id));
+			const at = insertIndex < 0 ? track.items.length : insertIndex;
+			const newItems = [];
+			const newClipIds = [];
+			for (const clip of input.new_clips) {
+				const partId = generatePartId("clip");
+				setPart(draft, partId, { video_clip: {
+					id: partId,
+					kind: "video_clip",
+					play_in: clip.play_in ?? 0,
+					play_out: clip.play_out ?? clip.media_duration_ms,
+					volume: 0,
+					origin_media_id: clip.media_id ?? ""
+				} });
+				newItems.push({
+					part_id: partId,
+					time_position: { mode: "sequential" },
+					fallback_abs_ms: void 0
+				});
+				newClipIds.push(partId);
+			}
+			if (input.on_anchored === "remap") for (let i = 0; i < input.old_clip_ids.length; i++) {
+				const newClipId = newClipIds[i];
+				if (newClipId == null) {
+					deleteAnchoredSubtree(draft, input.old_clip_ids[i]);
+					continue;
+				}
+				reanchorAnchoredChildren(draft, input.old_clip_ids[i], newClipId);
+			}
+			else for (const clipId of targets) deleteAnchoredSubtree(draft, clipId);
+			track.items = track.items.filter((item) => item?.part_id == null || !targets.has(item.part_id));
+			for (const clipId of targets) deletePart(draft, clipId);
+			track.items.splice(at, 0, ...newItems);
+		}, audit("ReplaceVideoClipSequence", input, options));
+	}
 	async adjustVideoClipVolume(input, options) {
 		this.validator.validateAdjustVideoClipVolume(input, this.doc);
 		this.doc.transact((draft) => {
@@ -686,12 +1444,23 @@ var SemanticEditor = class {
 	/**
 	* Set the document BGM. The media's stable result arrives materialized.
 	*
-	* KNOWN GAP (non-blocking): when the BGM comes from the public library, the
-	* Director must also register project-level stock media ownership. That is a
-	* separate "register-only, no draft write" side effect Director does not yet
-	* expose; until it does, a public-library BGM set here will not auto-appear in
-	* the project media library. The document edit itself is complete and correct.
-	* See `docs/projects/medeo-integration/results/phase-4-op-side-effect-classification.md`.
+	* KNOWN GAP (non-blocking, FE callers only): a public-library BGM also needs
+	* project-level media ownership registered, or it plays but never appears in
+	* the project's media library. This editor deliberately does not do it — the
+	* document edit is complete and correct, and ownership is a side effect owned
+	* by whoever holds the authoritative media data (memota), not by a CRDT write.
+	*
+	* Who is affected, as of 2026-08-13: the agent harness registers it on BOTH
+	* its legacy and mengine paths (shared `resolveMutation` calls memota
+	* `attachMedia` directly), and FE's legacy REST path gets it from Director.
+	* Only FE's mengine path is missing it. FE cannot call memota directly:
+	* `attachMedia` is exposed on memota's internal contract only, so the fix is a
+	* Director proxy route — NOT a new Director business endpoint, since Director
+	* stopped owning media ownership entirely (`a2951355`, 2026-08-05).
+	*
+	* Tracked as a Phase 7 gate (it must land before "new documents default to
+	* mengine" makes public-library BGM a routine operation). See
+	* `docs/projects/medeo-integration/results/phase-6-m4-legacy-refresh-isolation.md`.
 	*/
 	async setBgm(input, options) {
 		this.validator.validateSetBgm(input, this.doc);
@@ -829,7 +1598,8 @@ function audit(kind, payload, options) {
 	return {
 		kind,
 		payload,
-		intent: options?.intent ?? null
+		intent: options?.intent ?? null,
+		...options?.actor ? { actor: options.actor } : {}
 	};
 }
 function mainTrackRow(draft) {
@@ -851,6 +1621,23 @@ function mainTrackItems(draft) {
 	track.items ??= [];
 	return track.items;
 }
+/**
+* Resolve a `MoveAnchor` into an insertion slot in the **pre-extraction** item
+* list; the caller adjusts for items removed ahead of it.
+*
+* A missing anchor cannot reach here — `validateMoveVideoClipsByAnchor` rejects it
+* loudly first. This deliberately differs from `computeAddInsertIndex`, which
+* falls back to appending: adding clips with a stale anchor still has an obvious
+* intent (put them somewhere), while moving to a slot that no longer exists does
+* not. The `-1` guard stays as a defence-in-depth for a caller that bypassed
+* validation, and appending is the least destructive reading.
+*/
+function anchorInsertIndex(items, anchor) {
+	if (anchor.position === "track_start") return 0;
+	const index = items.findIndex((item) => item?.part_id === anchor.clip_id);
+	if (index < 0) return items.length;
+	return anchor.position === "before" ? index : index + 1;
+}
 function moveItem(items, from, to) {
 	if (from === to) return;
 	const [moved] = items.splice(from, 1);
@@ -883,9 +1670,16 @@ function normalizeSpeedShift(input) {
 function writeSpeechAssets(draft, assets) {
 	const captionById = new Map(assets.captions.map((c) => [c.caption_id, c]));
 	const speechTrack = ensureLaneTrack(draft, "speech");
-	const captionTrack = ensureLaneTrack(draft, "caption");
 	speechTrack.items ??= [];
-	captionTrack.items ??= [];
+	let captionItems;
+	const ensureCaptionItems = () => {
+		if (captionItems == null) {
+			const track = ensureLaneTrack(draft, "caption");
+			track.items ??= [];
+			captionItems = track.items;
+		}
+		return captionItems;
+	};
 	const ranges = mainTrackRanges(draft);
 	const hostStartMs = (anchorPartId) => ranges.find((r) => r.partId === anchorPartId)?.startMs;
 	for (const speech of assets.speeches) {
@@ -894,8 +1688,9 @@ function writeSpeechAssets(draft, assets) {
 		const removedCaptionIds = priorCaptionIds.filter((id) => id != null && !nextCaptionIds.has(id));
 		for (const captionId of removedCaptionIds) deletePart(draft, captionId);
 		if (removedCaptionIds.length > 0) {
+			const lane = findLaneTrack(draft, "caption");
 			const removed = new Set(removedCaptionIds);
-			captionTrack.items = captionTrack.items.filter((it) => it?.part_id == null || !removed.has(it.part_id));
+			if (lane?.items != null) lane.items = lane.items.filter((it) => it?.part_id == null || !removed.has(it.part_id));
 		}
 		const priorSpeech = draft.part_library?.[speech.speech_id]?.speech;
 		setPart(draft, speech.speech_id, { speech: {
@@ -927,7 +1722,7 @@ function writeSpeechAssets(draft, assets) {
 				start_ms: caption.start_ms
 			} });
 			const captionAbs = speechAbs == null ? void 0 : speechAbs + caption.start_ms;
-			placeRelative(captionTrack.items, captionId, speech.speech_id, caption.start_ms, captionAbs);
+			placeRelative(ensureCaptionItems(), captionId, speech.speech_id, caption.start_ms, captionAbs);
 		}
 	}
 }
@@ -1043,120 +1838,54 @@ function detachAnchoredChildren(draft, clipId) {
 		item.fallback_abs_ms = void 0;
 	}
 }
-/** Delete every speech (with its captions) anchored to the given video clip (RFC 02 §9.2). */
-function deleteAnchoredSubtree(draft, clipId) {
-	const anchored = (findLaneTrack(draft, "speech")?.items ?? []).filter((it) => it?.time_position?.mode === "anchored" && it.time_position.anchorPartId === clipId).map((it) => it.part_id).filter((id) => id != null);
-	for (const speechId of anchored) deleteSpeechSubtree(draft, speechId);
-}
-//#endregion
-//#region src/editor/journal.ts
-/**
-* Wire a plain-memory adapter + editor that share a recording id factory, so
-* every mutating transact lands in `journal` with ordered `generated_ids`.
-*/
-function createEditSandbox(document, options) {
-	const adapter = createPlainMemoryAdapter(document, options);
-	return {
-		adapter,
-		editor: new SemanticEditor(adapter, new SchemaValidator(), adapter.idFactory),
-		journal: adapter.journal
-	};
-}
 /**
-* Re-drive `doc` from a recorded journal, forcing each entry's `generated_ids`
-* through a queue-backed id factory. Never mints fresh ids: an empty queue on
-* demand throws `unrecorded id`; leftover ids after an entry throws
-* `unconsumed ids`. Legacy entries without `generated_ids` are treated as `[]`.
+* Re-anchor the direct anchored children of `fromClipId` onto `toClipId`, keeping
+* each child's `offsetMs` unchanged.
+*
+* "Same offset into the replacement" is the whole point: a speech that started
+* 100ms into the clip it narrated still starts 100ms into the clip that replaced
+* it, whatever the two clips' durations are. Absolute time is NOT preserved here
+* (that is `moveVideoClips`' rule, where the clip stays and the timeline reflows
+* around it) — the clip itself is being swapped out, so following it is what keeps
+* narration attached to the picture it describes.
+*
+* `fallback_abs_ms` is deliberately left alone: it is the orphan-recovery snapshot
+* (RFC 02 §11.1), refreshed by the projection on the next read. Writing a guess
+* here would make this op compete with the follow-the-clock refresh for the same
+* LWW unit.
+*
+* Only direct children move: captions anchor to their speech, so they follow it
+* without a rewrite.
 */
-async function replayJournal(doc, journal) {
-	const queue = [];
-	const idFactory = (_prefix) => {
-		const id = queue.shift();
-		if (id == null) throw new Error("unrecorded id");
-		return id;
-	};
-	const editor = new SemanticEditor(doc, new SchemaValidator(), idFactory);
-	for (const entry of journal) {
-		queue.push(...entry.generated_ids ?? []);
-		await dispatchEntry(editor, entry);
-		if (queue.length > 0) throw new Error("unconsumed ids");
+function reanchorAnchoredChildren(draft, fromClipId, toClipId) {
+	const speechTrack = findLaneTrack(draft, "speech");
+	if (speechTrack?.items == null) return;
+	for (const item of speechTrack.items) {
+		const timePosition = item?.time_position;
+		if (timePosition?.mode !== "anchored" || timePosition.anchorPartId !== fromClipId) continue;
+		item.time_position = {
+			...timePosition,
+			anchorPartId: toClipId
+		};
 	}
 }
-/** Dispatch one journal entry to the matching editor method; payload is passed through. */
-async function dispatchEntry(editor, entry) {
-	const payload = entry.payload;
-	const options = entry.intent != null ? { intent: entry.intent } : void 0;
-	switch (entry.kind) {
-		case "MoveVideoClips":
-			await editor.moveVideoClips(payload, options);
-			return;
-		case "DeleteVideoClips":
-			await editor.deleteVideoClips(payload, options);
-			return;
-		case "AddVideoClips":
-			await editor.addVideoClips(payload, options);
-			return;
-		case "AdjustVideoClipVolume":
-			await editor.adjustVideoClipVolume(payload, options);
-			return;
-		case "SetVideoClipSpeedShift":
-			await editor.setVideoClipSpeedShift(payload, options);
-			return;
-		case "ReplaceVideoClipContent":
-			await editor.replaceVideoClipContent(payload, options);
-			return;
-		case "AdjustVideoClipDuration":
-			await editor.adjustVideoClipDuration(payload, options);
-			return;
-		case "AddSpeeches":
-			await editor.addSpeeches(payload, options);
-			return;
-		case "DeleteSpeeches":
-			await editor.deleteSpeeches(payload, options);
-			return;
-		case "MoveSpeeches":
-			await editor.moveSpeeches(payload, options);
-			return;
-		case "ChangeSpeechScript":
-			await editor.changeSpeechScript(payload, options);
-			return;
-		case "ChangeSpeechVoice":
-			await editor.changeSpeechVoice(payload, options);
-			return;
-		case "AdjustSpeechVolume":
-			await editor.adjustSpeechVolume(payload, options);
-			return;
-		case "SetCaptionVisibility":
-			await editor.setCaptionVisibility(payload, options);
-			return;
-		case "SetCaptionStyle":
-			await editor.setCaptionStyle(payload, options);
-			return;
-		case "SetBgm":
-			await editor.setBgm(payload, options);
-			return;
-		case "DeleteBgm":
-			await editor.deleteBgm(payload, options);
-			return;
-		case "AdjustBgmVolume":
-			await editor.adjustBgmVolume(payload, options);
-			return;
-		default: {
-			const _exhaustive = entry.kind;
-			throw new Error(`replayJournal: unsupported kind ${String(_exhaustive)}`);
-		}
-	}
+/** Delete every speech (with its captions) anchored to the given video clip (RFC 02 §9.2). */
+function deleteAnchoredSubtree(draft, clipId) {
+	const anchored = (findLaneTrack(draft, "speech")?.items ?? []).filter((it) => it?.time_position?.mode === "anchored" && it.time_position.anchorPartId === clipId).map((it) => it.part_id).filter((id) => id != null);
+	for (const speechId of anchored) deleteSpeechSubtree(draft, speechId);
 }
 //#endregion
 //#region src/editor/types.ts
 /** Runtime list of the frozen, implemented kinds (for guards / introspection). */
 const IMPLEMENTED_SEMANTIC_OP_KINDS = [
 	"MoveVideoClips",
+	"MoveVideoClipsByAnchor",
 	"DeleteVideoClips",
 	"AddVideoClips",
 	"AdjustVideoClipVolume",
 	"SetVideoClipSpeedShift",
 	"ReplaceVideoClipContent",
+	"ReplaceVideoClipSequence",
 	"AdjustVideoClipDuration",
 	"AddSpeeches",
 	"DeleteSpeeches",
@@ -1174,6 +1903,288 @@ function isImplementedSemanticOpKind(kind) {
 	return IMPLEMENTED_SEMANTIC_OP_KINDS.includes(kind);
 }
 //#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-doc.ts
+/**
+* Agent-facing document with explicit `pull()` / `push()` over one Loro
+* document, with no background sync (ADR 0015 D1–D4).
+*
+* It deliberately does NOT reuse `MengineDocSession`'s stack. That stack —
+* SSE + local `DocStorage` + `ClientServerSynchronizer` + `DocManager` — is
+* correct for a browser editor and actively wrong here:
+*
+* - Its retry backoff lands *outside* the tool-call lifetime, so a write can
+*   settle seconds after the tool already told the LLM what happened.
+* - It has no durable local queue in the harness, so pending pushes die with the
+*   process — that is lost data, reported as success.
+* - Agent semantics require the document to change only at points the agent can
+*   name. If it converged on its own between tool calls, "what state was this
+*   decision based on" would be unanswerable, and a remote change could land
+*   mid-edit.
+*
+* What replaces the whole background job queue is one variable: the **watermark**,
+* the version the server has confirmed. `push()` exports `{mode:'update', from:
+* watermark}` and only advances it on a confirmed verdict, so a failed push is
+* retried implicitly — the next push carries both the failed ops and any new
+* ones, in one blob. No queue, no timer, no retry bookkeeping.
+*
+* Two non-obvious properties of that watermark, both verified against a real
+* server in the ADR 0015 spike:
+*
+* - It can legitimately *lead* the local document (it carries other peers'
+*   counters). Exporting `from` a leading watermark does not error; the blob
+*   correctly contains only the local peer's new ops. So a collaborative merge
+*   does not force a pull before pushing.
+* - Therefore every emptiness/coverage test must be one-directional containment,
+*   never equality. See {@link covers}.
+*
+* Lifecycle: one `LoroDoc` per document, shared across agent loops with a
+* refcount held by the caller's session registry. Rebuilding the doc per tool
+* call would mint a new peer each time and permanently inflate the document's
+* version vector for every future reader.
+*
+* Not thread-safe by design and it does not need to be: harness tool calls run
+* serially (`execToolCalls` is a `for` + `await`).
+*/
+var ManualSyncDoc = class ManualSyncDoc {
+	client;
+	doc;
+	adapter;
+	editor;
+	/**
+	* The version the server is known to hold. Starts empty (nothing confirmed)
+	* and only ever moves forward on a verdict that proves the server took our ops.
+	*/
+	watermark = new VersionVector(/* @__PURE__ */ new Map());
+	constructor(client, doc) {
+		this.client = client;
+		this.doc = doc;
+		this.adapter = new MirrorVideoDocumentAdapter(doc);
+		this.editor = new SemanticEditor(this.adapter);
+	}
+	/**
+	* Open an existing server document.
+	*
+	* Fetches the snapshot up front rather than starting empty and converging: the
+	* agent's first act is to read the document, so there is no useful state before
+	* the snapshot lands. This also fails fast and loudly on a document that does
+	* not exist, instead of `MengineDocSession.waitForContent()`'s behavior of
+	* waiting forever for content that will never arrive.
+	*/
+	static async open(options) {
+		const doc = new LoroDoc();
+		if (options.peerId != null) doc.setPeerId(options.peerId);
+		const response = await options.client.fetchSnapshot();
+		doc.import(base64ToBytes(response.snapshot));
+		const manualSyncDoc = new ManualSyncDoc(options.client, doc);
+		manualSyncDoc.watermark = manualSyncDoc.serverVVFrom(response.version.server_vv) ?? doc.oplogVersion();
+		return manualSyncDoc;
+	}
+	/** Current document read model (authoritative shape). */
+	snapshot() {
+		return this.adapter.snapshot();
+	}
+	/**
+	* The Loro peer this document writes as.
+	*
+	* Exposed because the peer is an externally-meaningful fact, not an internal
+	* detail: it is the identity every op this document emits is attributed to, and
+	* callers mint it under rules of their own (the harness reserves a range so a
+	* peer id alone says "Agent wrote this"). Being able to read it back means those
+	* rules can be verified against the live document rather than against whatever
+	* was passed to the constructor.
+	*/
+	editorPeerId() {
+		return this.doc.peerIdStr;
+	}
+	/** Current document projected to the legacy `VideoDraft` read shape. */
+	draft() {
+		return fromVideoDocument(this.adapter.snapshot());
+	}
+	/**
+	* 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". Under mengine `meta.version` never
+	* changes, so that detector would go permanently silent; comparing version
+	* vectors restores the same capability.
+	*
+	* Same capability, not a stronger one: like the legacy detector, this only
+	* reports what changed between two moments the caller chose to sample.
+	*/
+	versionMark() {
+		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) {
+		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. `SemanticEditor` 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() {
+		const before = this.doc.oplogVersion();
+		try {
+			const update = base64ToBytes((await this.client.sync(before.encode())).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() {
+		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,
+				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;
+		}
+	}
+};
+//#endregion
 //#region src/storage/medeo-http-doc-storage.ts
 /**
 * SSE-backed {@link Connection} for the mengine-server document stream.
@@ -1336,10 +2347,51 @@ var MedeoHttpDocStorage = class {
 			version: base64ToBytes(response.server_vv)
 		};
 	}
+	/**
+	* Forward one update to the server.
+	*
+	* 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 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 || update.data.byteLength === 0) return;
-		await this.client.pushUpdate(update.data);
+		try {
+			const response = await this.client.pushUpdate(update.data);
+			this.events.emit("pushOutcome", {
+				kind: response.kind,
+				update: update.data,
+				updateSeq: response.update_seq ?? void 0,
+				serverVV: decodeServerVV(response.version?.server_vv)
+			});
+		} 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
+			});
+			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);
 	}
 	async deleteDoc(_docId) {
 		throw new Error("MedeoHttpDocStorage does not support deleteDoc");
@@ -1360,6 +2412,19 @@ var MedeoHttpDocStorage = class {
 		});
 	}
 };
+/**
+* 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
 /**
@@ -1445,6 +2510,32 @@ var MemoryDocStorage = class extends BaseDocStorage {
 //#endregion
 //#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.
+*
+* 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
+* server's machine code when the push was rejected on its merits:
+*
+* - `timeout` — no verdict within the deadline. Ambiguous by nature: the push may
+*   still land later. The caller should surface it as unconfirmed, not as "failed".
+* - `rejected` — the server refused. `missing_dependency` is retryable after
+*   catch-up; `corrupt_update` never is.
+* - `failed` — transport/network failure; the server's answer is unknown.
+*/
+var MengineAckTimeoutError = class extends Error {
+	reason;
+	code;
+	cause;
+	constructor(reason, code, cause, message) {
+		super(message);
+		this.reason = reason;
+		this.code = code;
+		this.cause = cause;
+		this.name = "MengineAckTimeoutError";
+	}
+};
+/**
 * A live editing session for one Medeo document — the single entry point clients
 * (FE draft driver, Agent, embeds) use to open, edit, and observe a document.
 *
@@ -1478,6 +2569,12 @@ var MengineDocSession = class {
 	adapterValue = null;
 	editorValue = null;
 	started = false;
+	/**
+	* Latest server oplog version seen on a push outcome. Lets `waitForServerAck`
+	* return without waiting when the server is already known to cover the local
+	* doc (e.g. nothing was edited since the last confirmed push).
+	*/
+	serverVVValue = null;
 	constructor(options) {
 		this.options = options;
 		this.docId = options.docId;
@@ -1491,32 +2588,74 @@ var MengineDocSession = class {
 		this.manager = new DocManager(this.local, this.synchronizer);
 	}
 	/**
-	* The editor for local edits. Each op method validates, writes, and commits
-	* itself as one SemanticOp (single commit carrying its audit message), so
-	* callers just call `session.editor.someOp(...)` — there is no separate commit
-	* step. The committed change drives DocManager's local-update push.
+	* Observe every push verdict, including `duplicate` and failures.
+	*
+	* Exposed so a host can log/meter the four outcomes (rfc/05 §3 asks for
+	* explicit ack/rejected semantics). Most callers want the higher-level
+	* {@link waitForServerAck} instead.
 	*/
-	get editor() {
-		if (this.editorValue == null) throw new Error("mengine doc session is not started");
-		return this.editorValue;
+	subscribePushOutcome(callback) {
+		return this.server.subscribePushOutcome(callback);
 	}
 	/**
-	* Opaque version token of the local oplog (base64 `VersionVector.encode`).
-	* Equality-comparable only: equal means no observed change (local or
-	* remote-arrived) since the token was taken. Throws when not started.
+	* Resolve once the server has durably accepted the local document state as of
+	* *now* — the capability an Agent tool needs to answer "did my edit land?"
+	* before reporting success.
+	*
+	* Call it right after the editor ops whose durability matters. It snapshots the
+	* local doc's current version and resolves on the first push outcome whose
+	* `serverVV` covers that version, i.e. the server log is at least as advanced as
+	* the local doc was when this was called.
+	*
+	* Version coverage, not byte identity, is the acceptance test — for two reasons:
+	* the ops may reach the server inside a merged blob rather than as the exact
+	* bytes a push job carried, and a `duplicate` verdict then correctly satisfies
+	* the wait (the bytes appended nothing *because* the server already had them).
+	* A `rejected` / `failed` outcome rejects immediately with that reason rather
+	* than burning the whole timeout, since neither will resolve by waiting.
+	*
+	* 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.
 	*/
-	version() {
+	async waitForServerAck(options = {}) {
 		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
-		return bytesToBase64(this.adapterValue.doc.oplogVersion().encode());
+		const timeoutMs = options.timeoutMs ?? 15e3;
+		const target = this.manager.connectDoc(this.docId).version();
+		if (this.serverVVValue != null && covers$1(this.serverVVValue, target)) return;
+		await new Promise((resolve, reject) => {
+			let off = () => {};
+			let done = false;
+			const settle = (error) => {
+				if (done) return;
+				done = true;
+				clearTimeout(timer);
+				off();
+				if (error == null) resolve();
+				else reject(error);
+			};
+			const timer = setTimeout(() => {
+				settle(new MengineAckTimeoutError("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}`));
+					return;
+				}
+				if (outcome.serverVV != null && covers$1(outcome.serverVV, target)) settle(void 0);
+			});
+		});
 	}
 	/**
-	* The live document adapter, exposed for journal replay (commit channel).
-	* Replaying through it still goes SemanticEditor → Loro → mengine-server —
-	* no write bypass. Typed by the narrow interface on purpose.
+	* The editor for local edits. Each op method validates, writes, and commits
+	* itself as one SemanticOp (single commit carrying its audit message), so
+	* callers just call `session.editor.someOp(...)` — there is no separate commit
+	* step. The committed change drives DocManager's local-update push.
 	*/
-	get documentAdapter() {
-		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
-		return this.adapterValue;
+	get editor() {
+		if (this.editorValue == null) throw new Error("mengine doc session is not started");
+		return this.editorValue;
 	}
 	/** Current document snapshot (read model). */
 	snapshot() {
@@ -1555,6 +2694,9 @@ var MengineDocSession = class {
 		});
 		this.disposables.add(unsubscribe);
 		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => this.events.emit("state", state)));
+		this.disposables.add(this.server.subscribePushOutcome((outcome) => {
+			if (outcome.serverVV != null) this.serverVVValue = outcome.serverVV;
+		}));
 		await this.waitForContent();
 		return this.snapshot();
 	}
@@ -1603,5 +2745,25 @@ var MengineDocSession = class {
 		}
 	}
 };
+/**
+* True when the server version `serverVV` includes everything in `target`.
+*
+* `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.
+*/
+function covers$1(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;
+}
 //#endregion
-export { IMPLEMENTED_SEMANTIC_OP_KINDS, MedeoHttpDocStorage, MemoryDocStorage, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, derivePositionFromAbs, effectiveVideoClipDurationMs, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+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 };