@mengine/medeo-client 1.2.1-alpha.9 → 1.3.0

package/dist/index.js

@@ -1,5 +1,6 @@
-import { $ as base64ToBytes, A as findLaneTrack, B as syncAggregatedClipsTimePosition, C as VideoDocumentValidationError, D as videoDocumentSchema, E as partUnionSchema, F as fillMainTrackTimeGaps, G as DEFAULT_UNIT_TIME_MS, H as isEmptyVideoClip, I as reassignSpeechesToVideoClipsByTime, J as effectiveVideoClipDurationMs, K as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, L as recalculateTimelineDuration, M as solveVideoDocument, N as cascadeAfterVideoClipChanges, O as LANE_KINDS_IN_STACK_ORDER, P as arrangeMainTrackSeamlessly, Q as videoDocumentMirrorSchema, R as resolveAllSpeechOverlaps, S as toVideoDocument, T as validateVideoDocument, U as partDurationMs, V as TIMELINE_SKELETON_DURATION_MS, W as safeDurationMs, X as partUnionToDraft, Y as speedOf, Z as recordEntries, _ as EntityTimelineProjectionError, a as applyEntityTimelineProjection, b as derivePositionFromAbs, c as writeVideoDocumentToDraft, d as resolveEntityTimelineLayout, et as bytesToBase64, f as decodeEntityRelationRows, g as hasSequence, h as createRelationId, i as MirrorVideoDocumentAdapter, j as laneTrackId, k as ensureLaneTrack, l as readVideoDocumentFromDraft, m as createEntityId, n as createPlainMemoryAdapter, o as createMirrorVideoDocument, p as isJsonObject, q as VIDEO_DOCUMENT_SCHEMA_VERSION, r as generatePartId, s as createMirrorVideoDocumentAdapter, t as PlainMemoryAdapter, u as projectEntityTimeline, v as buildInitialVideoDocument, w as assertValidVideoDocument, x as fromVideoDocument, y as buildSpeechHostMap, z as resolveSpeechOverlapByShiftingVideos } from "./document-Df6awJDH.js";
-import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, 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 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";
 import { DisposableSet, EventBus, Task } from "@mengine/utils";
@@ -12,7 +13,7 @@ import { BaseDocStorage, DummyConnection } from "@mengine/storage";
 * namespace (mirrors the cluster's `/oapi/v1` precedent for an independent
 * subsystem) rather than folding into the shared `/api/v2/*` space.
 */
-const MENGINE_API_PREFIX$1 = "/api/mengine/v1";
+const MENGINE_API_PREFIX = "/api/mengine/v1";
 var MengineHttpRequestError = class extends Error {
 	status;
 	payload;
@@ -134,12 +135,12 @@ var MengineHttpClient = class {
 			...init,
 			headers
 		});
-		const payload = await safeReadJson$1(response);
+		const payload = await safeReadJson(response);
 		if (!response.ok) throw new MengineHttpRequestError(response.status, payload);
 		return payload;
 	}
 	endpoint(path) {
-		return `${this.options.httpOrigin.replace(/\/$/, "")}${MENGINE_API_PREFIX$1}/docs/${encodeURIComponent(this.options.docId)}/${path}`;
+		return `${this.options.httpOrigin.replace(/\/$/, "")}${MENGINE_API_PREFIX}/docs/${encodeURIComponent(this.options.docId)}/${path}`;
 	}
 };
 /**
@@ -156,7 +157,7 @@ function asPushRejection(error) {
 	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$1(response) {
+async function safeReadJson(response) {
 	const text = await response.text();
 	if (text.length === 0) return null;
 	try {
@@ -217,2169 +218,565 @@ function findSseFrameBoundary(buffer) {
 	return Math.min(lf, crlf);
 }
 //#endregion
-//#region src/entity-editor/entity-graph-http-client.ts
-const MENGINE_API_PREFIX = "/api/mengine/v1";
-const numericMarkerValidation$1 = { compareMarkerPoints: (_marker, _range, left, right) => {
-	if (typeof left !== "number" || !Number.isFinite(left) || typeof right !== "number" || !Number.isFinite(right)) throw new Error("entity-state requires finite numeric Marker coordinates");
-	return left < right ? -1 : left > right ? 1 : 0;
-} };
-/** Browser-safe authenticated CAS client for a document's Entity graph. */
-var EntityGraphHttpClient = class {
-	options;
-	transport;
-	endpoint;
-	constructor(options) {
-		this.options = options;
-		this.transport = new MengineHttpClient(options);
-		const origin = options.httpOrigin.replace(/\/$/, "");
-		this.endpoint = `${origin}${MENGINE_API_PREFIX}/docs/${encodeURIComponent(options.docId)}/entity-state`;
-	}
-	async fetchState() {
-		return this.request({ method: "GET" });
-	}
-	/**
-	* Replace the complete Entity graph under the baseline revision.
-	*
-	* Deletion intent is derived from baseline IDs omitted from `nextRows`, so a
-	* transient create-then-remove never becomes a request to delete unknown
-	* persisted data.
-	*/
-	async commit(baseState, nextRows, options = {}) {
-		if (!isNonNegativeSafeInteger(baseState.revision)) throw new Error("Entity graph revision must be a non-negative safe integer");
-		const baseRows = cloneAndValidateRows(baseState.rows);
-		const next = cloneAndValidateRows(nextRows);
-		const nextEntityIds = new Set(next.entities.map((row) => row.entityId));
-		const nextRelationIds = new Set(next.relations.map((row) => row.relationId));
-		const deletedEntityIds = baseRows.entities.map((row) => row.entityId).filter((entityId) => !nextEntityIds.has(entityId)).sort();
-		const deletedRelationIds = baseRows.relations.map((row) => row.relationId).filter((relationId) => !nextRelationIds.has(relationId)).sort();
-		return this.request({
-			method: "POST",
-			body: JSON.stringify({
-				expected_revision: baseState.revision,
-				rows: toWireRows(next),
-				deleted_entity_ids: deletedEntityIds,
-				deleted_relation_ids: deletedRelationIds,
-				...options.migrationBaseVv === void 0 ? {} : { migration_base_vv: options.migrationBaseVv }
-			})
-		});
-	}
-	async request(init) {
-		const response = await this.transport.fetch(this.endpoint, {
-			...init,
-			headers: this.transport.headers()
-		});
-		const payload = await safeReadJson(response);
-		if (!response.ok) throw new MengineHttpRequestError(response.status, payload);
-		return parseWireState(payload, this.options.docId);
+//#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;
 	}
-};
-function parseWireState(value, expectedDocId) {
-	if (!isRecord(value) || typeof value.doc_id !== "string" || !isNonNegativeSafeInteger(value.revision)) throw new Error("Invalid entity-state response envelope");
-	if (value.doc_id !== expectedDocId) throw new Error(`Entity-state response doc_id mismatch: expected "${expectedDocId}"`);
-	const rows = parseWireRows(value.rows);
-	decodeEntityRelationRows(rows, numericMarkerValidation$1);
-	return {
-		revision: value.revision,
-		rows
-	};
-}
-function parseWireRows(value) {
-	if (!isRecord(value) || !Array.isArray(value.entities) || !Array.isArray(value.relations)) throw new Error("Invalid entity-state response rows");
-	return {
-		entities: value.entities.map(parseWireEntity),
-		relations: value.relations.map(parseWireRelation)
-	};
-}
-function parseWireEntity(value) {
-	if (!isRecord(value) || !isJsonObject(value.payload)) throw new Error("Invalid Entity row in entity-state response");
-	return {
-		entityId: createEntityId(requiredString(value.entity_id, "entity_id")),
-		entityKind: requiredString(value.entity_kind, "entity_kind"),
-		payload: structuredClone(value.payload)
-	};
-}
-function parseWireRelation(value) {
-	if (!isRecord(value) || !isJsonObject(value.metadata) || !isJsonObject(value.trace)) throw new Error("Invalid Relation row in entity-state response");
-	return {
-		relationId: createRelationId(requiredString(value.relation_id, "relation_id")),
-		relationKind: requiredString(value.relation_kind, "relation_kind"),
-		endpoint0EntityId: createEntityId(requiredString(value.endpoint_0_entity_id, "endpoint_0_entity_id")),
-		endpoint1EntityId: createEntityId(requiredString(value.endpoint_1_entity_id, "endpoint_1_entity_id")),
-		metadata: structuredClone(value.metadata),
-		trace: structuredClone(value.trace)
-	};
-}
-function cloneAndValidateRows(rows) {
-	const clone = structuredClone(rows);
-	decodeEntityRelationRows(clone, numericMarkerValidation$1);
-	return clone;
-}
-function toWireRows(rows) {
-	return {
-		entities: rows.entities.map((row) => ({
-			entity_id: row.entityId,
-			entity_kind: row.entityKind,
-			payload: row.payload
-		})),
-		relations: rows.relations.map((row) => ({
-			relation_id: row.relationId,
-			relation_kind: row.relationKind,
-			endpoint_0_entity_id: row.endpoint0EntityId,
-			endpoint_1_entity_id: row.endpoint1EntityId,
-			metadata: row.metadata,
-			trace: row.trace
-		}))
-	};
+	return out;
 }
-function requiredString(value, field) {
-	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) throw new Error(`Invalid ${field} in entity-state response`);
-	return value;
+function encodeRandom() {
+	let out = "";
+	for (let i = 0; i < RANDOM_LEN; i++) out += CROCKFORD[Math.floor(Math.random() * 32)];
+	return out;
 }
-function isRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
+/** A 26-char Crockford Base32 ULID (10-char time + 16-char random). */
+function ulid() {
+	return encodeTime(Date.now()) + encodeRandom();
 }
-function isNonNegativeSafeInteger(value) {
-	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-async function safeReadJson(response) {
-	const text = await response.text();
-	if (text.length === 0) return null;
-	try {
-		return JSON.parse(text);
-	} catch {
-		return text;
-	}
+function generatePartId(prefix) {
+	return `${prefix}_${ulid()}`;
 }
 //#endregion
-//#region src/entity-editor/media-asset-import.ts
-const numericCoordinates = { compareMarkerPoints: (_marker, _range, left, right) => {
-	if (typeof left !== "number" || typeof right !== "number" || !Number.isFinite(left) || !Number.isFinite(right)) throw new Error("Media editor requires numeric coordinates");
-	return left - right;
-} };
-/** Import at the editor boundary, not at asset generation time. Existing provenance is retained. */
-function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, selection = {}) {
-	if (!fact.assetId || fact.assetId.trim() !== fact.assetId) throw new Error("Expected an asset id");
-	if (![
-		"image",
-		"video",
-		"audio",
-		"voice"
-	].includes(fact.kind)) throw new Error("Unsupported media kind");
-	if (fact.kind !== "image" && (!Number.isFinite(fact.durationMs) || fact.durationMs <= 0)) throw new Error(`${fact.kind} ${fact.assetId} requires its factual positive duration`);
-	if ((fact.kind === "audio" || fact.kind === "voice") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
-	decodeEntityRelationRows(initial, numericCoordinates);
-	const entities = structuredClone([...initial.entities]);
-	const relations = structuredClone([...initial.relations]);
-	const assets = entities.filter((row) => {
-		const external = row.payload.external;
-		return row.entityKind === "asset" && isJsonObject(external) && external.system === (fact.kind === "voice" ? "memota-speech" : "memota") && external.key === fact.assetId && (selection.assetEntityId === void 0 || row.entityId === selection.assetEntityId);
-	});
-	if (selection.assetEntityId !== void 0 && assets.length !== 1) throw new Error("Selected Asset does not match the recalled asset facts");
-	if (assets.length > 1) throw new Error(`Ambiguous Asset bindings for ${fact.assetId}; select assetEntityId explicitly`);
-	const mintEntity = () => {
-		const id = createEntityId(idFactory("entity"));
-		if (entities.some((row) => row.entityId === id)) throw new Error(`Duplicate entity id ${id}`);
-		return id;
-	};
-	let asset = assets[0];
-	if (asset === void 0) {
-		asset = {
-			entityId: mintEntity(),
-			entityKind: "asset",
-			payload: {
-				external: {
-					system: fact.kind === "voice" ? "memota-speech" : "memota",
-					key: fact.assetId
-				},
-				...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey }
-			}
-		};
-		entities.push(asset);
-	} else if (fact.storageKey !== void 0) {
-		if (asset.payload.storageKey !== void 0 && asset.payload.storageKey !== fact.storageKey) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
-		if (asset.payload.storageKey === void 0) {
-			asset = {
-				...asset,
-				payload: {
-					...asset.payload,
-					storageKey: fact.storageKey
-				}
-			};
-			const assetIndex = entities.findIndex((row) => row.entityId === asset.entityId);
-			entities[assetIndex] = asset;
-		}
-	}
-	const bindings = relations.filter((row) => row.relationKind === "physical-asset" && (row.endpoint0EntityId === asset.entityId || row.endpoint1EntityId === asset.entityId) && (selection.contentEntityId === void 0 || (row.endpoint0EntityId === asset.entityId ? row.endpoint1EntityId : row.endpoint0EntityId) === selection.contentEntityId));
-	const contentIds = new Set(bindings.map((row) => row.endpoint0EntityId === asset.entityId ? row.endpoint1EntityId : row.endpoint0EntityId));
-	if (selection.contentEntityId !== void 0 && contentIds.size !== 1) throw new Error("Selected media Entity is not bound to the selected Asset");
-	if (contentIds.size > 1) throw new Error(`Ambiguous media bindings for ${fact.assetId}; select contentEntityId explicitly`);
-	let content;
-	if (bindings[0] !== void 0) {
-		const relation = bindings[0];
-		content = entities.find((row) => row.entityId === (relation.endpoint0EntityId === asset.entityId ? relation.endpoint1EntityId : relation.endpoint0EntityId));
-		const extent = content?.payload.extent;
-		if (content?.entityKind !== fact.kind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs) || fact.kind === "voice" && !sameVoice(content.payload.voice, fact.voice)) throw new Error(`Media facts conflict with existing binding for ${fact.assetId}`);
-	} else {
-		const payload = {
-			extent: fact.kind === "image" ? {
-				kind: "unbounded",
-				start: 0
-			} : {
-				kind: "bounded",
-				start: 0,
-				end: fact.durationMs
-			},
-			sampling: fact.kind === "image" ? "constant" : "native",
-			coordinateSpace: "milliseconds",
-			...fact.kind === "voice" ? { voice: {
-				system: fact.voice.system,
-				key: fact.voice.key,
-				...fact.voice.name === void 0 ? {} : { name: fact.voice.name }
-			} } : {}
-		};
-		const createdContent = {
-			entityId: mintEntity(),
-			entityKind: fact.kind,
-			payload
-		};
-		content = createdContent;
-		entities.push(createdContent);
-		const relationId = createRelationId(idFactory("relation"));
-		if (relations.some((row) => row.relationId === relationId)) throw new Error(`Duplicate relation id ${relationId}`);
-		relations.push({
-			relationId,
-			relationKind: "physical-asset",
-			endpoint0EntityId: createdContent.entityId,
-			endpoint1EntityId: asset.entityId,
-			metadata: {},
-			trace: {}
-		});
-	}
-	const rows = {
-		entities,
-		relations
-	};
-	decodeEntityRelationRows(rows, numericCoordinates);
-	if (content === void 0) throw new Error(`Media Entity could not be resolved for ${fact.assetId}`);
-	return {
-		rows,
-		assetEntityId: asset.entityId,
-		contentEntityId: content.entityId
-	};
-}
-function sameVoice(left, right) {
-	return isJsonObject(left) && left.system === right.system && left.key === right.key && left.name === right.name && Object.keys(left).every((key) => key === "system" || key === "key" || key === "name");
-}
+//#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/entity-editor/entity-timeline-editor.ts
-const roleOrder = {
-	caption: 0,
-	video_clip: 1,
-	speech: 2,
-	bgm: 3
-};
-const defaultIdFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`;
+//#region src/editor/schemas/speech-assets.ts
 /**
-* Graph-native timeline authoring over authoritative Medeo Entity and Relation rows.
+* 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 mutation is applied to a detached graph, validated as a complete DSL set,
-* and committed only after validation succeeds.
+* 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).
 */
-var EntityTimelineEditor = class {
-	idFactory;
-	state;
-	constructor(initialRows, idFactory = defaultIdFactory) {
-		this.idFactory = idFactory;
-		this.state = cloneRows(initialRows);
-	}
-	rows() {
-		return cloneRows(this.state);
-	}
-	insertClip(input) {
-		const requestedOrder = input.clipPayload?.order;
-		const order = typeof requestedOrder === "number" ? requestedOrder : nextSequentialOrder(this.state, createEntityId(input.trackEntityId));
-		return this.insertPlacedClip({
-			trackEntityId: input.trackEntityId,
-			contentEntityId: input.contentEntityId,
-			sourceRange: input.sourceRange,
-			duration: input.duration,
-			placement: input.targetRange === void 0 ? {
-				kind: "sequential",
-				order
-			} : {
-				kind: "absolute",
-				targetRange: input.targetRange
-			},
-			clipPayload: input.clipPayload
-		});
-	}
-	insertPlacedClip(input) {
-		return this.transact((draft) => this.insertPlacedClipIntoDraft(draft, input));
-	}
-	updateClipMarker(input) {
-		this.transact((draft) => {
-			const { marker } = requireClipTopology(draft, input.clipEntityId);
-			const payload = { ...cloneJsonObject(marker.payload, "Sequence Marker payload") };
-			if (input.sourceRange !== void 0) payload.sourceRange = cloneJsonValue(input.sourceRange, "sourceRange");
-			if (input.duration !== void 0) payload.duration = cloneJsonValue(input.duration, "duration");
-			if (Object.hasOwn(input, "targetRange")) if (input.targetRange === void 0) {
-				delete payload.targetRange;
-				if (!hasOutgoingClipAnchor(draft, input.clipEntityId)) {
-					const trackId = otherEndpoint(requireOneRelation(draft, createEntityId(input.clipEntityId), "track-clip"), input.clipEntityId);
-					const clipPayload = { ...cloneJsonObject(requireEntityKind(draft, input.clipEntityId, "clip").payload, "Clip payload") };
-					clipPayload.order ??= nextSequentialOrder(draft, trackId);
-					replaceEntity(draft, createEntityId(input.clipEntityId), {
-						...requireEntityKind(draft, input.clipEntityId, "clip"),
-						payload: clipPayload
-					});
-				}
-			} else {
-				payload.targetRange = cloneJsonValue(input.targetRange, "targetRange");
-				const clip = requireEntityKind(draft, input.clipEntityId, "clip");
-				const clipPayload = { ...cloneJsonObject(clip.payload, "Clip payload") };
-				delete clipPayload.order;
-				replaceEntity(draft, clip.entityId, {
-					...clip,
-					payload: clipPayload
-				});
-			}
-			if (Object.hasOwn(input, "timeRemapping")) if (input.timeRemapping === void 0) delete payload.timeRemapping;
-			else payload.timeRemapping = cloneJsonValue(input.timeRemapping, "timeRemapping");
-			replaceEntity(draft, marker.entityId, {
-				...marker,
-				payload
-			});
-		});
-	}
-	setClipPlacement(input) {
-		this.transact((draft) => this.applyClipPlacement(draft, input.clipEntityId, input.placement));
-	}
-	moveSequentialClips(input) {
-		if (input.clipEntityIds.length === 0) throw new Error("At least one Clip is required");
-		this.transact((draft) => {
-			const original = resolveEntityTimelineLayout(draft);
-			this.normalizeMainSequential(draft);
-			const before = resolveEntityTimelineLayout(draft);
-			const targetIds = new Set(input.clipEntityIds);
-			if (targetIds.size !== input.clipEntityIds.length) throw new Error("Clip ids must be unique");
-			const placements = input.clipEntityIds.map((id) => before.clips.get(id));
-			if (placements.some((placement) => placement === void 0 || placement.mode !== "sequential")) throw new Error("moveSequentialClips accepts only sequential Clips");
-			const trackIds = new Set(placements.map((placement) => placement.trackEntityId));
-			if (trackIds.size !== 1) throw new Error("Moved Clips must belong to one Track");
-			const trackId = [...trackIds][0];
-			const track = before.tracks.find((candidate) => candidate.entityId === trackId);
-			if (track?.role !== "video_clip") throw new Error("Only the video_clip Track supports sequential block moves");
-			const ordered = track.clips.filter((placement) => placement.mode === "sequential").map((placement) => placement.clipEntityId);
-			if (input.anchor.position !== "trackStart" && targetIds.has(input.anchor.clipEntityId)) throw new Error("Move anchor cannot be one of the moved Clips");
-			const moved = ordered.filter((id) => targetIds.has(id));
-			if (moved.length !== targetIds.size) throw new Error("Every moved Clip must exist on the target Track");
-			const remaining = ordered.filter((id) => !targetIds.has(id));
-			let insertAt = 0;
-			if (input.anchor.position !== "trackStart") {
-				const anchorIndex = remaining.indexOf(input.anchor.clipEntityId);
-				if (anchorIndex < 0) throw new Error("Move anchor Clip does not exist on the target Track");
-				insertAt = anchorIndex + (input.anchor.position === "after" ? 1 : 0);
-			}
-			[
-				...remaining.slice(0, insertAt),
-				...moved,
-				...remaining.slice(insertAt)
-			].forEach((clipId, order) => setClipOrder(draft, clipId, order));
-			if (input.onAnchored === "keepAbsolute") {
-				const affected = outgoingAnchorChildren(draft, new Set(track.clips.map((clip) => clip.clipEntityId))).filter((childId) => clipRole(draft, childId) === "speech").map((childId) => {
-					const placement = original.clips.get(childId);
-					if (placement === void 0) throw new Error(`Anchored child Clip "${childId}" is not placed`);
-					return {
-						childId,
-						start: placement.start
-					};
-				});
-				const after = resolveEntityTimelineLayout(draft);
-				for (const child of affected) this.reanchorAtAbsolute(draft, child.childId, child.start, after);
-			}
-			this.resolveOneVoiceoverOverlap(draft);
-		});
-	}
-	moveClipsToStarts(input) {
-		if (input.moves.length === 0) throw new Error("At least one Clip move is required");
-		this.transact((draft) => {
-			const original = resolveEntityTimelineLayout(draft);
-			const originalVideo = original.tracks.find((track) => track.role === "video_clip");
-			if (originalVideo === void 0) throw new Error("The timeline has no video_clip Track");
-			const preservedVoiceovers = outgoingAnchorChildren(draft, new Set(originalVideo.clips.map((clip) => clip.clipEntityId))).filter((clipId) => clipRole(draft, clipId) === "speech").map((clipId) => ({
-				clipId,
-				start: original.clips.get(clipId).start
-			}));
-			this.normalizeMainSequential(draft);
-			for (const move of input.moves) {
-				finiteNonNegative(move.newStartMs, "newStartMs");
-				requireClipOnRole(draft, move.clipEntityId, "video_clip");
-				const track = resolveEntityTimelineLayout(draft).tracks.find((candidate) => candidate.role === "video_clip");
-				const ordered = track.clips.map((clip) => clip.clipEntityId);
-				const from = ordered.indexOf(move.clipEntityId);
-				if (from < 0) throw new Error(`Clip "${move.clipEntityId}" is not on the video_clip Track`);
-				const remaining = track.clips.filter((clip) => clip.clipEntityId !== move.clipEntityId);
-				let cursor = 0;
-				let target = remaining.length;
-				for (const [index, clip] of remaining.entries()) {
-					if (move.newStartMs <= cursor + clip.duration / 2) {
-						target = index;
-						break;
-					}
-					cursor += clip.duration;
-				}
-				const next = [...ordered];
-				next.splice(from, 1);
-				next.splice(target, 0, move.clipEntityId);
-				next.forEach((clipId, order) => setClipOrder(draft, clipId, order));
-			}
-			const after = resolveEntityTimelineLayout(draft);
-			for (const voiceover of preservedVoiceovers) this.reanchorAtAbsolute(draft, voiceover.clipId, voiceover.start, after);
-			this.resolveOneVoiceoverOverlap(draft);
-		});
-	}
-	moveClip(input) {
-		this.transact((draft) => {
-			const topology = requireClipTopology(draft, input.clipEntityId);
-			const track = requireEntityKind(draft, input.trackEntityId, "track");
-			requireTrackTimeline(draft, track.entityId);
-			this.relinkRelation(draft, topology.trackRelation, {
-				endpoint0EntityId: track.entityId,
-				endpoint1EntityId: topology.clip.entityId
-			});
-		});
-	}
-	replaceClipContent(input) {
-		this.transact((draft) => {
-			const topology = requireClipTopology(draft, input.clipEntityId);
-			const content = requireSequenceContent(draft, input.contentEntityId);
-			const payload = {
-				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
-				sourceRange: cloneJsonValue(input.sourceRange, "sourceRange"),
-				duration: cloneJsonValue(input.duration, "duration")
-			};
-			delete payload.targetRange;
-			delete payload.timeRemapping;
-			if (input.targetRange !== void 0) payload.targetRange = cloneJsonValue(input.targetRange, "targetRange");
-			if (input.timeRemapping !== void 0) payload.timeRemapping = cloneJsonValue(input.timeRemapping, "timeRemapping");
-			replaceEntity(draft, topology.marker.entityId, {
-				...topology.marker,
-				payload
-			});
-			if (!hasOutgoingClipAnchor(draft, topology.clip.entityId)) {
-				const clipPayload = { ...cloneJsonObject(topology.clip.payload, "Clip payload") };
-				if (input.targetRange === void 0) clipPayload.order ??= nextSequentialOrder(draft, otherEndpoint(topology.trackRelation, topology.clip.entityId));
-				else delete clipPayload.order;
-				replaceEntity(draft, topology.clip.entityId, {
-					...topology.clip,
-					payload: clipPayload
-				});
-			}
-			this.relinkRelation(draft, topology.markerContentRelation, {
-				endpoint0EntityId: topology.marker.entityId,
-				endpoint1EntityId: content.entityId
-			});
-		});
-	}
-	insertMediaClip(input) {
-		return this.transact((draft) => {
-			if (input.placement.kind === "sequential") this.normalizeMainSequential(draft);
-			const imported = importMediaAsset(draft, input.media, this.idFactory);
-			replaceRows(draft, imported.rows);
-			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
-			const sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
-			const clipId = this.insertPlacedClipIntoDraft(draft, {
-				trackEntityId: track.entityId,
-				contentEntityId: imported.contentEntityId,
-				sourceRange,
-				duration: {
-					mode: "fixed",
-					value: sourceRange.end - sourceRange.start
-				},
-				placement: input.placement,
-				...input.clipEntityId === void 0 ? {} : { clipEntityId: input.clipEntityId },
-				...input.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(input.volume) } }
-			});
-			if (input.placement.kind === "sequential") this.resolveOneVoiceoverOverlap(draft);
-			return clipId;
-		});
-	}
-	insertMediaClips(input) {
-		if (input.clips.length === 0) throw new Error("At least one media Clip is required");
-		return this.transact((draft) => {
-			this.normalizeMainSequential(draft);
-			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
-			const ordered = resolveEntityTimelineLayout(draft).tracks.find((candidate) => candidate.entityId === track.entityId)?.clips ?? [];
-			let insertAt = ordered.length;
-			const insertion = input.insertion;
-			if (insertion.kind === "before" || insertion.kind === "after") {
-				const anchorIndex = ordered.findIndex((clip) => clip.clipEntityId === insertion.clipEntityId);
-				if (anchorIndex >= 0) insertAt = anchorIndex + (insertion.kind === "after" ? 1 : 0);
-			} else {
-				const startMs = finiteNonNegative(insertion.startMs, "firstStart.startMs");
-				let cursor = 0;
-				for (const [index, clip] of ordered.entries()) {
-					if (startMs <= cursor + clip.duration / 2) {
-						insertAt = index;
-						break;
-					}
-					cursor += clip.duration;
-				}
-			}
-			const created = [];
-			for (const [offset, clip] of input.clips.entries()) {
-				const imported = importMediaAsset(draft, clip.media, this.idFactory);
-				replaceRows(draft, imported.rows);
-				const sourceRange = requirePositiveRange(clip.sourceRange, "sourceRange");
-				created.push(this.insertPlacedClipIntoDraft(draft, {
-					trackEntityId: track.entityId,
-					contentEntityId: imported.contentEntityId,
-					sourceRange,
-					duration: {
-						mode: "fixed",
-						value: sourceRange.end - sourceRange.start
-					},
-					placement: {
-						kind: "sequential",
-						order: ordered.length + offset
-					},
-					...clip.clipEntityId === void 0 ? {} : { clipEntityId: clip.clipEntityId },
-					...clip.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(clip.volume) } }
-				}));
-			}
-			const desired = ordered.map((clip) => clip.clipEntityId);
-			desired.splice(insertAt, 0, ...created);
-			desired.forEach((clipId, order) => setClipOrder(draft, clipId, order));
-			this.resolveOneVoiceoverOverlap(draft);
-			return created;
-		});
-	}
-	replaceMediaClip(input) {
-		this.transact((draft) => {
-			this.normalizeMainSequential(draft);
-			const topology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
-			const imported = importMediaAsset(draft, input.media, this.idFactory);
-			replaceRows(draft, imported.rows);
-			const sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
-			const markerPayloadValue = {
-				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
-				sourceRange,
-				duration: {
-					mode: "fixed",
-					value: sourceRange.end - sourceRange.start
-				}
-			};
-			delete markerPayloadValue.timeRemapping;
-			resizeAbsoluteTarget(markerPayloadValue, sourceRange.end - sourceRange.start);
-			replaceEntity(draft, topology.marker.entityId, {
-				...topology.marker,
-				payload: markerPayloadValue
-			});
-			this.relinkRelation(draft, topology.markerContentRelation, {
-				endpoint0EntityId: topology.marker.entityId,
-				endpoint1EntityId: createEntityId(imported.contentEntityId)
-			});
-			this.resolveOneVoiceoverOverlap(draft);
-		});
-	}
-	setClipVolume(input) {
-		this.transact((draft) => {
-			const topology = requireClipTopology(draft, input.clipEntityId);
-			requireSupportedRole(draft, topology);
-			replaceEntity(draft, topology.clip.entityId, {
-				...topology.clip,
-				payload: {
-					...topology.clip.payload,
-					volume: requireVolume(input.volume)
-				}
-			});
-		});
-	}
-	setClipSpeed(input) {
-		this.transact((draft) => {
-			const initialTopology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
-			const content = requireSequenceContent(draft, otherEndpoint(initialTopology.markerContentRelation, initialTopology.marker.entityId));
-			if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip speed is supported only for Video or Image content");
-			const initialPayload = cloneJsonObject(initialTopology.marker.payload, "Sequence Marker payload");
-			const priorSource = requirePositiveRange(initialPayload.sourceRange, "sourceRange");
-			if (input.timeRemapping === null && initialPayload.timeRemapping === void 0) return;
-			this.normalizeMainSequential(draft);
-			const topology = requireClipTopology(draft, input.clipEntityId);
-			const payload = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
-			let sourceRange = priorSource;
-			if (content.entityKind === "image" && initialPayload.timeRemapping === void 0 && input.timeRemapping !== null) sourceRange = {
-				start: 0,
-				end: markerDuration(initialPayload, priorSource)
-			};
-			if (input.timeRemapping === null) {
-				delete payload.timeRemapping;
-				payload.sourceRange = sourceRange;
-				payload.duration = {
-					mode: "fixed",
-					value: sourceRange.end - sourceRange.start
-				};
-			} else {
-				const rate = finitePositive(input.timeRemapping.rate, "linear speed rate");
-				const duration = Math.round((sourceRange.end - sourceRange.start) / rate);
-				if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Linear speed produces an invalid duration");
-				payload.sourceRange = sourceRange;
-				payload.duration = {
-					mode: "fixed",
-					value: duration
-				};
-				payload.timeRemapping = {
-					kind: "linear",
-					rate,
-					...input.timeRemapping.mode === void 0 ? {} : { mode: input.timeRemapping.mode }
-				};
-			}
-			resizeAbsoluteTarget(payload, markerDuration(payload, sourceRange));
-			replaceEntity(draft, topology.marker.entityId, {
-				...topology.marker,
-				payload
-			});
-			this.resolveOneVoiceoverOverlap(draft);
-		});
-	}
-	trimClip(input) {
-		this.transact((draft) => {
-			this.normalizeMainSequential(draft);
-			const topology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
-			const content = requireSequenceContent(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId));
-			if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip trimming is supported only for Video or Image content");
-			const sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
-			const payload = {
-				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
-				sourceRange
-			};
-			const rate = linearRate(payload.timeRemapping);
-			const duration = Math.round((sourceRange.end - sourceRange.start) / rate);
-			if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Trim produces an invalid duration");
-			payload.duration = {
-				mode: "fixed",
-				value: duration
-			};
-			resizeAbsoluteTarget(payload, duration);
-			replaceEntity(draft, topology.marker.entityId, {
-				...topology.marker,
-				payload
-			});
-			this.resolveOneVoiceoverOverlap(draft);
-		});
-	}
-	replaceSequentialClips(input) {
-		if (input.oldClipEntityIds.length === 0 || input.newClips.length === 0) throw new Error("Replacement requires at least one old and one new Clip");
-		return this.transact((draft) => {
-			this.normalizeMainSequential(draft);
-			const before = resolveEntityTimelineLayout(draft);
-			const oldIds = new Set(input.oldClipEntityIds);
-			if (oldIds.size !== input.oldClipEntityIds.length) throw new Error("Old Clip ids must be unique");
-			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
-			const ordered = before.tracks.find((candidate) => candidate.entityId === track.entityId)?.clips.filter((clip) => clip.mode === "sequential").map((clip) => clip.clipEntityId);
-			if (ordered === void 0) throw new Error("The video_clip Track is not present in the current layout");
-			const indexes = input.oldClipEntityIds.map((id) => ordered.indexOf(id));
-			if (indexes.some((index) => index < 0)) throw new Error("Every replaced Clip must be sequential on video_clip");
-			const sortedIndexes = [...indexes].sort((left, right) => left - right);
-			if (sortedIndexes.some((index, offset) => index !== sortedIndexes[0] + offset)) throw new Error("Replaced Clips must form one contiguous timeline run");
-			if (input.oldClipEntityIds.some((id, index) => id !== ordered[sortedIndexes[0] + index])) throw new Error("Replaced Clip ids must be listed in timeline order");
-			const insertOrder = sortedIndexes[0];
-			const temporaryOrder = ordered.length;
-			const created = [];
-			for (const [offset, replacement] of input.newClips.entries()) {
-				if (replacement.clipEntityId !== void 0 && oldIds.has(replacement.clipEntityId)) throw new Error("A replacement Clip id cannot reuse an Entity being removed");
-				const imported = importMediaAsset(draft, replacement.media, this.idFactory);
-				replaceRows(draft, imported.rows);
-				const sourceRange = requirePositiveRange(replacement.sourceRange, "sourceRange");
-				created.push(this.insertPlacedClipIntoDraft(draft, {
-					trackEntityId: track.entityId,
-					contentEntityId: imported.contentEntityId,
-					sourceRange,
-					duration: {
-						mode: "fixed",
-						value: sourceRange.end - sourceRange.start
-					},
-					placement: {
-						kind: "sequential",
-						order: temporaryOrder + offset
-					},
-					...replacement.clipEntityId === void 0 ? {} : { clipEntityId: replacement.clipEntityId },
-					...replacement.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(replacement.volume) } }
-				}));
-			}
-			for (const [index, oldId] of input.oldClipEntityIds.entries()) {
-				const children = directAnchorChildren(draft, oldId);
-				if (input.onAnchored === "remap" && created[index] !== void 0) for (const childId of children) this.replaceAnchorHost(draft, childId, created[index]);
-				else {
-					const scheduled = /* @__PURE__ */ new Set();
-					for (const childId of children) {
-						scheduled.add(childId);
-						this.removeAnchoredDescendants(draft, childId, scheduled);
-						this.removeClipGraph(draft, childId);
-					}
-				}
-			}
-			for (const oldId of input.oldClipEntityIds) this.removeClipGraph(draft, oldId);
-			[
-				...ordered.slice(0, insertOrder),
-				...created,
-				...ordered.slice(insertOrder + input.oldClipEntityIds.length)
-			].forEach((clipId, order) => setClipOrder(draft, clipId, order));
-			this.resolveOneVoiceoverOverlap(draft);
-			return created;
-		});
-	}
-	deleteClip(input) {
-		this.transact((draft) => {
-			const topology = requireClipTopology(draft, input.clipEntityId);
-			assertOnlyStructuralIncidents(draft, topology.clip.entityId, new Set(["track-clip", "clip-marker"]));
-			assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["clip-marker", "marker-content"]));
-			const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "clip-marker").length === 1;
-			const removedRelationIds = new Set([topology.trackRelation.relationId, topology.clipMarkerRelation.relationId]);
-			if (markerIsExclusive) for (const relation of incidentRelations(draft, topology.marker.entityId)) removedRelationIds.add(relation.relationId);
-			draft.relations = draft.relations.filter((relation) => !removedRelationIds.has(relation.relationId));
-			draft.entities = draft.entities.filter((entity) => entity.entityId !== topology.clip.entityId && (!markerIsExclusive || entity.entityId !== topology.marker.entityId));
-		});
-	}
-	deleteClipTree(input) {
-		if (input.clipEntityIds.length === 0) throw new Error("At least one Clip is required");
-		this.transact((draft) => {
-			const targets = new Set(input.clipEntityIds);
-			if (targets.size !== input.clipEntityIds.length) throw new Error("Clip ids must be unique");
-			for (const target of targets) requireEntityKind(draft, target, "clip");
-			const includesVisual = [...targets].some((target) => clipRole(draft, target) === "video_clip");
-			const original = resolveEntityTimelineLayout(draft);
-			if (includesVisual) this.normalizeMainSequential(draft);
-			if (input.onAnchored === "detach") for (const childId of outgoingAnchorChildren(draft, targets)) {
-				if (targets.has(childId)) continue;
-				const placement = original.clips.get(childId);
-				if (placement === void 0) throw new Error(`Anchored child Clip "${childId}" is not placed`);
-				this.applyClipPlacement(draft, childId, {
-					kind: "absolute",
-					targetRange: {
-						start: placement.start,
-						end: placement.start + placement.duration
-					}
-				});
-			}
-			else for (const target of targets) this.removeAnchoredDescendants(draft, target, targets);
-			for (const target of targets) this.removeClipGraph(draft, target);
-			normalizeSequentialOrders(draft);
-			if (includesVisual) this.resolveOneVoiceoverOverlap(draft);
-		});
-	}
-	updateClip(input) {
-		this.transact((draft) => {
-			const clip = requireEntityKind(draft, input.clipEntityId, "clip");
-			const priorOrder = clip.payload.order;
-			replaceEntity(draft, clip.entityId, {
-				...clip,
-				payload: {
-					...cloneJsonObject(input.payload, "Clip payload"),
-					...priorOrder === void 0 || Object.hasOwn(input.payload, "order") ? {} : { order: priorOrder }
-				}
-			});
-		});
-	}
-	upsertVoiceoverTake(input) {
-		return this.transact((draft) => {
-			this.normalizeMainSequential(draft);
-			finiteNonNegative(input.anchorOffset, "Voiceover anchorOffset");
-			requireVolume(input.volume);
-			requireClipOnRole(draft, input.hostClipEntityId, "video_clip");
-			const imported = importMediaAsset(draft, input.media, this.idFactory);
-			replaceRows(draft, imported.rows);
-			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
-			const script = this.ensureAudioScript(draft, voice.entityId, input.scriptText);
-			const speechTrack = this.ensureRoleTrack(draft, input.timelineEntityId, "speech");
-			const existing = draft.entities.find((row) => row.entityId === input.voiceoverClipEntityId);
-			let voiceoverClipEntityId;
-			if (existing === void 0) voiceoverClipEntityId = this.insertPlacedClipIntoDraft(draft, {
-				clipEntityId: input.voiceoverClipEntityId,
-				trackEntityId: speechTrack.entityId,
-				contentEntityId: voice.entityId,
-				sourceRange: {
-					start: 0,
-					end: input.media.durationMs
-				},
-				duration: {
-					mode: "fixed",
-					value: input.media.durationMs
-				},
-				placement: {
-					kind: "anchored",
-					hostClipEntityId: input.hostClipEntityId,
-					anchorOffset: input.anchorOffset
-				},
-				clipPayload: { volume: input.volume }
-			});
-			else {
-				const topology = requireClipOnRole(draft, input.voiceoverClipEntityId, "speech");
-				voiceoverClipEntityId = topology.clip.entityId;
-				replaceEntity(draft, topology.clip.entityId, {
-					...topology.clip,
-					payload: {
-						...topology.clip.payload,
-						volume: input.volume
-					}
-				});
-				this.relinkRelation(draft, topology.markerContentRelation, {
-					endpoint0EntityId: topology.marker.entityId,
-					endpoint1EntityId: voice.entityId
-				});
-				this.applyClipPlacement(draft, topology.clip.entityId, {
-					kind: "anchored",
-					hostClipEntityId: input.hostClipEntityId,
-					anchorOffset: input.anchorOffset
-				});
-				const placed = requireClipTopology(draft, topology.clip.entityId);
-				replaceEntity(draft, placed.marker.entityId, {
-					...placed.marker,
-					payload: {
-						...placed.marker.payload,
-						sourceRange: {
-							start: 0,
-							end: input.media.durationMs
-						},
-						duration: {
-							mode: "fixed",
-							value: input.media.durationMs
-						}
-					}
-				});
-			}
-			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, script.entityId, input.captions);
-			this.resolveOneVoiceoverOverlap(draft);
-			return {
-				voiceoverClipEntityId,
-				voiceEntityId: voice.entityId,
-				audioScriptEntityId: script.entityId,
-				captionClipEntityIds: input.captions.map((caption) => caption.captionClipEntityId)
-			};
-		});
-	}
-	moveVoiceover(input) {
-		this.transact((draft) => {
-			requireClipOnRole(draft, input.voiceoverClipEntityId, "speech");
-			this.normalizeMainSequential(draft);
-			const layout = resolveEntityTimelineLayout(draft);
-			this.reanchorAtAbsolute(draft, input.voiceoverClipEntityId, finiteNonNegative(input.newStartMs, "newStartMs"), layout);
-			this.resolveOneVoiceoverOverlap(draft);
-		});
-	}
-	deleteVoiceover(input) {
-		this.transact((draft) => {
-			this.normalizeMainSequential(draft);
-			const targets = new Set(input.voiceoverClipEntityIds);
-			if (targets.size !== input.voiceoverClipEntityIds.length) throw new Error("Voiceover Clip ids must be unique");
-			for (const clipId of targets) {
-				requireClipOnRole(draft, clipId, "speech");
-				this.removeAnchoredDescendants(draft, clipId, targets);
-			}
-			for (const clipId of targets) this.removeClipGraph(draft, clipId);
-			this.resolveOneVoiceoverOverlap(draft);
-		});
-	}
-	setBgm(input) {
-		return this.transact((draft) => {
-			const imported = importMediaAsset(draft, input.media, this.idFactory);
-			replaceRows(draft, imported.rows);
-			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "bgm");
-			const existing = clipsOnTrack(draft, track.entityId);
-			for (const clip of existing) this.removeClipGraph(draft, clip.entityId);
-			const clipId = this.insertPlacedClipIntoDraft(draft, {
-				clipEntityId: input.bgmClipEntityId,
-				trackEntityId: track.entityId,
-				contentEntityId: imported.contentEntityId,
-				sourceRange: {
-					start: 0,
-					end: input.media.durationMs
-				},
-				duration: { mode: "from-source" },
-				placement: {
-					kind: "sequential",
-					order: 0
-				},
-				clipPayload: { volume: requireVolume(input.volume) }
-			});
-			const topology = requireClipTopology(draft, clipId);
-			replaceEntity(draft, topology.marker.entityId, {
-				...topology.marker,
-				payload: {
-					...topology.marker.payload,
-					durationPolicy: "timeline"
-				}
-			});
-			return clipId;
-		});
-	}
-	deleteBgm(input) {
-		this.transact((draft) => {
-			const track = findRoleTrack(draft, input.timelineEntityId, "bgm");
-			if (track === void 0) return;
-			for (const clip of clipsOnTrack(draft, track.entityId)) this.removeClipGraph(draft, clip.entityId);
-		});
-	}
-	setCaptionVisibility(input) {
-		this.transact((draft) => {
-			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
-			replaceEntity(draft, track.entityId, {
-				...track,
-				payload: {
-					...track.payload,
-					hidden: input.hidden
-				}
-			});
-		});
-	}
-	patchCaptionStyle(input) {
-		this.transact((draft) => {
-			const track = findRoleTrack(draft, input.timelineEntityId, "caption");
-			if (track === void 0) return;
-			const patch = cloneJsonObject(input.style, "Caption style");
-			for (const clip of clipsOnTrack(draft, track.entityId)) {
-				const topology = requireClipTopology(draft, clip.entityId);
-				const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
-				const prior = caption.payload.style;
-				const style = isJsonObject(prior) ? prior : {};
-				replaceEntity(draft, caption.entityId, {
-					...caption,
-					payload: {
-						...caption.payload,
-						style: {
-							...style,
-							...patch
-						}
-					}
-				});
-			}
-		});
-	}
-	insertPlacedClipIntoDraft(draft, input) {
-		const track = requireEntityKind(draft, input.trackEntityId, "track");
-		requireTrackTimeline(draft, track.entityId);
-		const content = requireSequenceContent(draft, input.contentEntityId);
-		const clipId = input.clipEntityId === void 0 ? this.mintEntityId(draft) : requireAvailableEntityId(draft, input.clipEntityId);
-		const markerId = this.mintEntityId(draft);
-		const clipPayload = { ...cloneJsonObject(input.clipPayload ?? {}, "Clip payload") };
-		delete clipPayload.order;
-		const markerPlacement = applyPlacementPayload(clipPayload, input.placement);
-		const clip = {
-			entityId: clipId,
-			entityKind: "clip",
-			payload: clipPayload
-		};
-		const marker = {
-			entityId: markerId,
-			entityKind: "sequence-marker",
-			payload: markerPayload({
-				sourceRange: input.sourceRange,
-				duration: input.duration,
-				...markerPlacement
-			})
-		};
-		draft.entities.push(clip, marker);
-		draft.relations.push(this.createRelation(draft, "track-clip", track.entityId, clipId), this.createRelation(draft, "clip-marker", clipId, markerId), this.createRelation(draft, "marker-content", markerId, content.entityId));
-		if (input.placement.kind === "anchored") {
-			const host = requireEntityKind(draft, input.placement.hostClipEntityId, "clip");
-			if (host.entityId === clipId) throw new Error("A Clip cannot anchor to itself");
-			draft.relations.push(this.createRelation(draft, "clip-anchor", clipId, host.entityId));
-		}
-		return clipId;
-	}
-	ensureRoleTrack(draft, timelineEntityId, role) {
-		const existing = findRoleTrack(draft, timelineEntityId, role);
-		if (existing !== void 0) {
-			if (existing.payload.order === void 0) {
-				const replacement = {
-					...existing,
-					payload: {
-						...existing.payload,
-						order: roleOrder[role]
-					}
-				};
-				replaceEntity(draft, existing.entityId, replacement);
-				return replacement;
-			}
-			return existing;
-		}
-		const timeline = requireEntityKind(draft, timelineEntityId, "timeline");
-		const track = {
-			entityId: this.mintEntityId(draft),
-			entityKind: "track",
-			payload: {
-				role,
-				order: roleOrder[role]
-			}
-		};
-		draft.entities.push(track);
-		draft.relations.push(this.createRelation(draft, "timeline-track", timeline.entityId, track.entityId));
-		return track;
-	}
-	ensureAudioScript(draft, voiceEntityId, text) {
-		const renders = draft.relations.filter((relation) => relation.relationKind === "audio-script-render" && relation.endpoint0EntityId === voiceEntityId);
-		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple AudioScript relations`);
-		if (renders[0] !== void 0) {
-			const script = requireEntityKind(draft, renders[0].endpoint1EntityId, "audio-script");
-			const replacement = {
-				...script,
-				payload: { segments: [{
-					segmentId: "segment-0",
-					text
-				}] }
-			};
-			replaceEntity(draft, script.entityId, replacement);
-			return replacement;
-		}
-		const script = {
-			entityId: this.mintEntityId(draft),
-			entityKind: "audio-script",
-			payload: { segments: [{
-				segmentId: "segment-0",
-				text
-			}] }
-		};
-		draft.entities.push(script);
-		draft.relations.push(this.createRelation(draft, "audio-script-render", voiceEntityId, script.entityId));
-		return script;
-	}
-	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, scriptEntityId, captions) {
-		const requested = new Set(captions.map((caption) => caption.captionClipEntityId));
-		if (requested.size !== captions.length) throw new Error("Caption Clip ids must be unique within a voiceover take");
-		const existing = directAnchorChildren(draft, voiceoverClipEntityId).filter((clipId) => clipRole(draft, clipId) === "caption");
-		for (const clipId of existing) if (!requested.has(clipId)) this.removeCaptionClipGraph(draft, clipId);
-		const captionTrack = captions.length === 0 ? void 0 : this.ensureRoleTrackForClip(draft, voiceoverClipEntityId, "caption");
-		for (const caption of captions) {
-			const startMs = finiteNonNegative(caption.startMs, "Caption startMs");
-			const durationMs = finitePositive(caption.durationMs, "Caption durationMs");
-			if (draft.entities.find((entity) => entity.entityId === caption.captionClipEntityId) === void 0) {
-				const content = {
-					entityId: this.mintEntityId(draft),
-					entityKind: "caption",
-					payload: {
-						extent: {
-							kind: "bounded",
-							start: 0,
-							end: durationMs
-						},
-						sampling: "native",
-						coordinateSpace: "milliseconds",
-						text: caption.text,
-						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
-					}
-				};
-				const asset = {
-					entityId: this.mintEntityId(draft),
-					entityKind: "asset",
-					payload: { inline: {
-						mediaType: "text/plain",
-						text: caption.text
-					} }
-				};
-				draft.entities.push(content, asset);
-				draft.relations.push(this.createRelation(draft, "physical-asset", content.entityId, asset.entityId), this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
-					start: startMs,
-					end: startMs + durationMs
-				} }), this.createRelation(draft, "caption-provenance", content.entityId, scriptEntityId, { segmentAlignment: [] }));
-				this.insertPlacedClipIntoDraft(draft, {
-					clipEntityId: caption.captionClipEntityId,
-					trackEntityId: captionTrack.entityId,
-					contentEntityId: content.entityId,
-					sourceRange: {
-						start: 0,
-						end: durationMs
-					},
-					duration: {
-						mode: "fixed",
-						value: durationMs
-					},
-					placement: {
-						kind: "anchored",
-						hostClipEntityId: voiceoverClipEntityId,
-						anchorOffset: startMs
-					}
-				});
-				continue;
-			}
-			const topology = requireClipOnRole(draft, caption.captionClipEntityId, "caption");
-			const content = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
-			const priorStyle = isJsonObject(content.payload.style) ? content.payload.style : {};
-			const style = caption.style === void 0 ? priorStyle : {
-				...priorStyle,
-				...cloneJsonObject(caption.style, "Caption style")
-			};
-			replaceEntity(draft, content.entityId, {
-				...content,
-				payload: {
-					...content.payload,
-					extent: {
-						kind: "bounded",
-						start: 0,
-						end: durationMs
-					},
-					text: caption.text,
-					...Object.keys(style).length === 0 ? {} : { style }
-				}
-			});
-			const asset = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, content.entityId, "physical-asset"), content.entityId), "asset");
-			if (asset.payload.inline === void 0) throw new Error(`Caption "${caption.captionClipEntityId}" is not inline`);
-			replaceEntity(draft, asset.entityId, {
-				...asset,
-				payload: {
-					...asset.payload,
-					inline: {
-						mediaType: "text/plain",
-						text: caption.text
-					}
-				}
-			});
-			this.applyClipPlacement(draft, topology.clip.entityId, {
-				kind: "anchored",
-				hostClipEntityId: voiceoverClipEntityId,
-				anchorOffset: startMs
-			});
-			const placed = requireClipTopology(draft, topology.clip.entityId);
-			replaceEntity(draft, placed.marker.entityId, {
-				...placed.marker,
-				payload: {
-					...placed.marker.payload,
-					sourceRange: {
-						start: 0,
-						end: durationMs
-					},
-					duration: {
-						mode: "fixed",
-						value: durationMs
-					}
-				}
-			});
-			this.replaceCaptionSemanticRelations(draft, content.entityId, voiceEntityId, scriptEntityId, startMs, durationMs);
-		}
-	}
-	ensureRoleTrackForClip(draft, clipEntityId, role) {
-		const topology = requireClipTopology(draft, clipEntityId);
-		const track = requireEntityKind(draft, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track");
-		const timeline = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, track.entityId, "timeline-track"), track.entityId), "timeline");
-		return this.ensureRoleTrack(draft, timeline.entityId, role);
-	}
-	replaceCaptionSemanticRelations(draft, captionEntityId, voiceEntityId, scriptEntityId, startMs, durationMs) {
-		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment" || relation.relationKind === "caption-provenance").map((relation) => relation.relationId));
-		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceEntityId, { alignment: {
-			start: startMs,
-			end: startMs + durationMs
-		} }), this.createRelation(draft, "caption-provenance", captionEntityId, scriptEntityId, { segmentAlignment: [] }));
-	}
-	removeCaptionClipGraph(draft, clipEntityId) {
-		const topology = requireClipOnRole(draft, clipEntityId, "caption");
-		const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
-		const asset = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, caption.entityId, "physical-asset"), caption.entityId), "asset");
-		const contentRelations = incidentRelations(draft, caption.entityId);
-		const allowed = new Set([
-			"physical-asset",
-			"caption-alignment",
-			"caption-provenance",
-			"marker-content"
-		]);
-		const unsupported = contentRelations.filter((relation) => !allowed.has(relation.relationKind));
-		if (unsupported.length > 0) throw new Error(`Cannot delete Caption with unsupported Relation ${unsupported[0].relationId}`);
-		this.removeClipGraph(draft, clipEntityId);
-		if (incidentRelations(draft, caption.entityId).some((relation) => relation.relationKind === "marker-content")) return;
-		const removed = new Set(incidentRelations(draft, caption.entityId).map((relation) => relation.relationId));
-		const assetIncidents = incidentRelations(draft, asset.entityId);
-		const deleteAsset = asset.payload.inline !== void 0 && assetIncidents.every((relation) => removed.has(relation.relationId));
-		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		draft.entities = draft.entities.filter((entity) => entity.entityId !== caption.entityId && (!deleteAsset || entity.entityId !== asset.entityId));
-	}
-	replaceAnchorHost(draft, childClipEntityId, hostClipEntityId) {
-		const anchors = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === childClipEntityId);
-		if (anchors.length !== 1) throw new Error(`Clip "${childClipEntityId}" must have exactly one host`);
-		this.relinkRelation(draft, anchors[0], {
-			endpoint0EntityId: createEntityId(childClipEntityId),
-			endpoint1EntityId: createEntityId(hostClipEntityId)
+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;
 	}
-	/** Rebuild the legacy edit baseline from current visual order before a high-level cascade. */
-	normalizeMainSequential(draft) {
-		const videoTrack = resolveEntityTimelineLayout(draft).tracks.find((track) => track.role === "video_clip");
-		if (videoTrack === void 0) return;
-		videoTrack.clips.forEach((clip, order) => {
-			this.applyClipPlacement(draft, clip.clipEntityId, {
-				kind: "sequential",
-				order
-			});
+	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"
+			]
 		});
-	}
-	resolveOneVoiceoverOverlap(draft) {
-		const layout = resolveEntityTimelineLayout(draft);
-		const speechTrack = layout.tracks.find((track) => track.role === "speech");
-		if (speechTrack === void 0) return;
-		const ranges = speechTrack.clips.map((speech) => {
-			const captions = directAnchorChildren(draft, speech.clipEntityId).filter((clipId) => clipRole(draft, clipId) === "caption").map((clipId) => layout.clips.get(clipId)).filter((value) => value !== void 0);
-			return {
-				speech,
-				start: Math.min(speech.start, ...captions.map((caption) => caption.start)),
-				end: Math.max(speech.start + speech.duration, ...captions.map((caption) => caption.start + caption.duration))
-			};
-		}).sort((left, right) => left.start - right.start || left.speech.clipEntityId.localeCompare(right.speech.clipEntityId));
-		for (let index = 1; index < ranges.length; index += 1) {
-			const prior = ranges[index - 1];
-			const current = ranges[index];
-			if (current.start >= prior.end) continue;
-			const hostId = current.speech.anchorClipEntityId;
-			if (hostId === void 0) continue;
-			const videoTrack = layout.tracks.find((track) => track.role === "video_clip");
-			const hostIndex = videoTrack?.clips.findIndex((clip) => clip.clipEntityId === hostId) ?? -1;
-			if (videoTrack === void 0 || hostIndex < 0) continue;
-			const overlapMs = Math.round(prior.end - current.start);
-			for (const [visualIndex, clip] of videoTrack.clips.entries()) this.applyClipPlacement(draft, clip.clipEntityId, {
-				kind: "absolute",
-				targetRange: {
-					start: clip.start + (visualIndex >= hostIndex ? overlapMs : 0),
-					end: clip.start + clip.duration + (visualIndex >= hostIndex ? overlapMs : 0)
-				}
-			});
-			return;
-		}
-	}
-	applyClipPlacement(draft, clipEntityId, placement) {
-		const topology = requireClipTopology(draft, clipEntityId);
-		const clipPayload = { ...cloneJsonObject(topology.clip.payload, "Clip payload") };
-		const markerPayloadValue = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
-		delete clipPayload.order;
-		delete markerPayloadValue.targetRange;
-		delete markerPayloadValue.anchorOffset;
-		const outgoingAnchors = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === topology.clip.entityId);
-		const removed = new Set(outgoingAnchors.map((relation) => relation.relationId));
-		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		if (placement.kind === "sequential") clipPayload.order = finiteNumber(placement.order, "Clip order");
-		else if (placement.kind === "absolute") markerPayloadValue.targetRange = cloneJsonValue(placement.targetRange, "targetRange");
-		else {
-			const host = requireEntityKind(draft, placement.hostClipEntityId, "clip");
-			if (host.entityId === topology.clip.entityId) throw new Error("A Clip cannot anchor to itself");
-			markerPayloadValue.anchorOffset = finiteNonNegative(placement.anchorOffset, "anchorOffset");
-			draft.relations.push(this.createRelation(draft, "clip-anchor", topology.clip.entityId, host.entityId));
-		}
-		replaceEntity(draft, topology.clip.entityId, {
-			...topology.clip,
-			payload: clipPayload
+		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"
+			]
 		});
-		replaceEntity(draft, topology.marker.entityId, {
-			...topology.marker,
-			payload: markerPayloadValue
+		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"
+			]
 		});
-	}
-	reanchorAtAbsolute(draft, childClipEntityId, absoluteStart, layout) {
-		const hosts = layout.tracks.find((track) => track.role === "video_clip")?.clips.filter((clip) => clip.mode === "sequential") ?? [];
-		if (hosts.length === 0) {
-			const child = layout.clips.get(childClipEntityId);
-			if (child === void 0) throw new Error(`Clip "${childClipEntityId}" is not placed`);
-			this.applyClipPlacement(draft, childClipEntityId, {
-				kind: "absolute",
-				targetRange: {
-					start: absoluteStart,
-					end: absoluteStart + child.duration
-				}
-			});
-			return;
-		}
-		const host = hosts.find((candidate) => candidate.start <= absoluteStart && absoluteStart < candidate.start + candidate.duration) ?? (absoluteStart < hosts[0].start ? hosts[0] : hosts.at(-1));
-		this.applyClipPlacement(draft, childClipEntityId, {
-			kind: "anchored",
-			hostClipEntityId: host.clipEntityId,
-			anchorOffset: Math.max(0, Math.round(absoluteStart - host.start))
+		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"
+			]
 		});
 	}
-	removeAnchoredDescendants(draft, hostClipEntityId, scheduled) {
-		const children = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint1EntityId === hostClipEntityId).map((relation) => String(relation.endpoint0EntityId));
-		for (const child of children) {
-			if (scheduled.has(child)) continue;
-			const descendants = new Set(scheduled);
-			descendants.add(child);
-			this.removeAnchoredDescendants(draft, child, descendants);
-			if (clipRole(draft, child) === "caption") this.removeCaptionClipGraph(draft, child);
-			else this.removeClipGraph(draft, child);
-		}
-	}
-	removeClipGraph(draft, clipEntityId) {
-		const topology = requireClipTopology(draft, clipEntityId);
-		assertOnlyStructuralIncidents(draft, topology.clip.entityId, new Set([
-			"track-clip",
-			"clip-marker",
-			"clip-anchor"
-		]));
-		assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["clip-marker", "marker-content"]));
-		const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "clip-marker").length === 1;
-		const removed = new Set(incidentRelations(draft, topology.clip.entityId).map((relation) => relation.relationId));
-		if (markerIsExclusive) for (const relation of incidentRelations(draft, topology.marker.entityId)) removed.add(relation.relationId);
-		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		draft.entities = draft.entities.filter((entity) => entity.entityId !== topology.clip.entityId && (!markerIsExclusive || entity.entityId !== topology.marker.entityId));
-	}
-	transact(edit) {
-		const draft = cloneRows(this.state);
-		const result = edit(draft);
-		validateFinalRows(draft);
-		this.state = draft;
-		return result;
-	}
-	mintEntityId(draft) {
-		const entityId = createEntityId(this.idFactory("entity"));
-		if (draft.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
-		return entityId;
-	}
-	createRelation(draft, relationKind, endpoint0EntityId, endpoint1EntityId, metadata = {}) {
-		return {
-			relationId: this.mintRelationId(draft),
-			relationKind,
-			endpoint0EntityId,
-			endpoint1EntityId,
-			metadata,
-			trace: {}
-		};
-	}
-	relinkRelation(draft, relation, endpoints) {
-		const relationId = this.mintRelationId(draft);
-		const index = draft.relations.findIndex((candidate) => candidate.relationId === relation.relationId);
-		if (index < 0) throw new Error(`Relation id "${relation.relationId}" does not exist`);
-		draft.relations[index] = {
-			...relation,
-			...endpoints,
-			relationId
-		};
-	}
-	mintRelationId(draft) {
-		const relationId = createRelationId(this.idFactory("relation"));
-		if (draft.relations.some((relation) => relation.relationId === relationId)) throw new Error(`Relation id "${relationId}" already exists`);
-		return relationId;
-	}
-};
-function validateFinalRows(rows) {
-	decodeEntityRelationRows(rows, numericMarkerValidation);
-	validateTimelineHierarchy(rows);
-}
-function validateTimelineHierarchy(rows) {
-	for (const entity of rows.entities) {
-		if (entity.entityKind === "track") requireTrackTimeline(rows, entity.entityId);
-		if (entity.entityKind !== "clip") continue;
-		const trackRelations = incidentRelations(rows, entity.entityId).filter((relation) => relation.relationKind === "track-clip");
-		if (trackRelations.length !== 1) throw new Error(`Clip Entity "${entity.entityId}" must belong to exactly one Track`);
-		requireEntityKind(rows, otherEndpoint(trackRelations[0], entity.entityId), "track");
-	}
-}
-function requireTrackTimeline(rows, trackEntityId) {
-	const timelineRelations = incidentRelations(rows, trackEntityId).filter((relation) => relation.relationKind === "timeline-track");
-	if (timelineRelations.filter((relation) => {
-		const otherId = otherEndpoint(relation, trackEntityId);
-		return rows.entities.some((entity) => entity.entityId === otherId && entity.entityKind === "timeline");
-	}).length !== 1 || timelineRelations.length !== 1) throw new Error(`Track Entity "${trackEntityId}" must belong to exactly one Timeline`);
-}
-function requireClipTopology(rows, clipEntityId) {
-	const clip = requireEntityKind(rows, clipEntityId, "clip");
-	const trackRelation = requireOneRelation(rows, clip.entityId, "track-clip");
-	requireEntityKind(rows, otherEndpoint(trackRelation, clip.entityId), "track");
-	const clipMarkerRelation = requireOneRelation(rows, clip.entityId, "clip-marker");
-	const marker = requireEntityKind(rows, otherEndpoint(clipMarkerRelation, clip.entityId), "sequence-marker");
-	const markerContentRelation = requireOneRelation(rows, marker.entityId, "marker-content");
-	requireSequenceContent(rows, otherEndpoint(markerContentRelation, marker.entityId));
-	return {
-		clip,
-		marker,
-		trackRelation,
-		clipMarkerRelation,
-		markerContentRelation
-	};
-}
-function requireOneRelation(rows, entityId, relationKind) {
-	const matches = incidentRelations(rows, entityId).filter((relation) => relation.relationKind === relationKind);
-	if (matches.length !== 1) throw new Error(`Entity "${entityId}" must have exactly one ${relationKind} Relation`);
-	return matches[0];
-}
-function requireEntityKind(rows, entityIdValue, entityKind) {
-	const entityId = createEntityId(entityIdValue);
-	const entity = rows.entities.find((candidate) => candidate.entityId === entityId);
-	if (entity == null) throw new Error(`Entity id "${entityId}" does not exist`);
-	if (entity.entityKind !== entityKind) throw new Error(`Entity "${entityId}" must have kind "${entityKind}", got "${entity.entityKind}"`);
-	return entity;
-}
-function requireSequenceContent(rows, entityIdValue) {
-	if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(entityIdValue)) throw new Error("Timeline content must reference an existing Sequence media Entity id; a URL is not allowed");
-	const entityId = createEntityId(entityIdValue);
-	const row = rows.entities.find((candidate) => candidate.entityId === entityId);
-	if (row == null) throw new Error(`Timeline content must reference an existing Sequence media Entity; "${entityId}" was not found`);
-	if (!hasSequence({
-		...row.payload,
-		entityId: row.entityId,
-		entityKind: row.entityKind
-	})) throw new Error(`Timeline content must reference a Sequence media Entity, but "${entityId}" has kind "${row.entityKind}"`);
-	return row;
-}
-function assertOnlyStructuralIncidents(rows, entityId, allowedKinds) {
-	const unsupported = incidentRelations(rows, entityId).filter((relation) => !allowedKinds.has(relation.relationKind));
-	if (unsupported.length === 0) return;
-	throw new Error(`Cannot delete Clip graph: Entity "${entityId}" has unsupported incident Relation id(s): ${unsupported.map((relation) => relation.relationId).sort().join(", ")}`);
-}
-function incidentRelations(rows, entityId) {
-	return rows.relations.filter((relation) => relation.endpoint0EntityId === entityId || relation.endpoint1EntityId === entityId);
-}
-function hasOutgoingClipAnchor(rows, clipEntityId) {
-	return rows.relations.some((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === clipEntityId);
-}
-function outgoingAnchorChildren(rows, hostIds) {
-	return rows.relations.filter((relation) => relation.relationKind === "clip-anchor" && hostIds.has(relation.endpoint1EntityId)).map((relation) => String(relation.endpoint0EntityId));
-}
-function applyPlacementPayload(clipPayload, placement) {
-	if (placement.kind === "sequential") {
-		clipPayload.order = finiteNumber(placement.order, "Clip order");
-		return {};
-	}
-	if (placement.kind === "absolute") return { targetRange: cloneJsonValue(placement.targetRange, "targetRange") };
-	return { anchorOffset: finiteNonNegative(placement.anchorOffset, "anchorOffset") };
-}
-function requireAvailableEntityId(rows, value) {
-	const entityId = createEntityId(value);
-	if (rows.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
-	return entityId;
-}
-function setClipOrder(rows, clipEntityId, order) {
-	const clip = requireEntityKind(rows, clipEntityId, "clip");
-	replaceEntity(rows, clip.entityId, {
-		...clip,
-		payload: {
-			...clip.payload,
-			order
-		}
-	});
-}
-function normalizeSequentialOrders(rows) {
-	for (const track of rows.entities.filter((entity) => entity.entityKind === "track")) rows.relations.filter((relation) => relation.relationKind === "track-clip" && relation.endpoint0EntityId === track.entityId).map((relation) => rows.entities.find((entity) => entity.entityId === relation.endpoint1EntityId)).filter((entity) => entity?.entityKind === "clip" && typeof entity.payload.order === "number").sort((left, right) => Number(left.payload.order) - Number(right.payload.order)).forEach((clip, order) => setClipOrder(rows, clip.entityId, order));
-}
-function findRoleTrack(rows, timelineEntityId, role) {
-	const timeline = requireEntityKind(rows, timelineEntityId, "timeline");
-	const tracks = incidentRelations(rows, timeline.entityId).filter((relation) => relation.relationKind === "timeline-track").map((relation) => requireEntityKind(rows, otherEndpoint(relation, timeline.entityId), "track")).filter((track) => track.payload.role === role);
-	if (tracks.length > 1) throw new Error(`Timeline "${timelineEntityId}" has multiple ${role} Tracks`);
-	return tracks[0];
-}
-function clipsOnTrack(rows, trackEntityId) {
-	return incidentRelations(rows, trackEntityId).filter((relation) => relation.relationKind === "track-clip").map((relation) => requireEntityKind(rows, otherEndpoint(relation, trackEntityId), "clip"));
-}
-function clipRole(rows, clipEntityId) {
-	const topology = requireClipTopology(rows, clipEntityId);
-	return requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role;
-}
-function directAnchorChildren(rows, hostClipEntityId) {
-	return rows.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint1EntityId === hostClipEntityId).map((relation) => String(relation.endpoint0EntityId));
-}
-function requireSupportedRole(rows, topology) {
-	const role = requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role;
-	if (role !== "video_clip" && role !== "speech" && role !== "caption" && role !== "bgm") throw new Error(`Clip "${topology.clip.entityId}" is not on a supported timeline Track`);
-	return role;
-}
-function requireClipOnRole(rows, clipEntityId, role) {
-	const topology = requireClipTopology(rows, clipEntityId);
-	if (requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role !== role) throw new Error(`Clip "${clipEntityId}" must belong to the ${role} Track`);
-	return topology;
-}
-function finiteNumber(value, label) {
-	if (!Number.isFinite(value)) throw new Error(`${label} must be finite`);
-	return value;
-}
-function finitePositive(value, label) {
-	const result = finiteNumber(value, label);
-	if (result <= 0) throw new Error(`${label} must be positive`);
-	return result;
-}
-function requireVolume(value) {
-	const volume = finiteNumber(value, "Clip volume");
-	if (volume < -60 || volume > 20) throw new Error("Clip volume must be between -60 and 20 dB");
-	return volume;
-}
-function requirePositiveRange(value, label) {
-	if (!isJsonObject(value)) throw new Error(`${label} must be an object`);
-	const start = finiteNonNegative(value.start, `${label}.start`);
-	const end = finitePositive(value.end, `${label}.end`);
-	if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || end <= start) throw new Error(`${label} must be a positive whole-millisecond range`);
-	return {
-		start,
-		end
-	};
-}
-function markerDuration(payload, sourceRange) {
-	const duration = payload.duration;
-	if (!isJsonObject(duration)) throw new Error("Sequence Marker duration must be an object");
-	if (duration.mode === "from-source") return sourceRange.end - sourceRange.start;
-	if (duration.mode !== "fixed") throw new Error("Sequence Marker duration mode is unsupported");
-	return finitePositive(duration.value, "Sequence Marker fixed duration");
-}
-function linearRate(value) {
-	if (value === void 0) return 1;
-	if (!isJsonObject(value) || value.kind !== "linear") throw new Error("Only linear Clip time remapping is supported");
-	return finitePositive(value.rate, "linear speed rate");
-}
-function resizeAbsoluteTarget(payload, duration) {
-	if (payload.targetRange === void 0) return;
-	const target = requirePositiveRange(payload.targetRange, "targetRange");
-	payload.targetRange = {
-		start: target.start,
-		end: target.start + duration
-	};
-}
-function replaceRows(rows, replacement) {
-	rows.entities = structuredClone([...replacement.entities]);
-	rows.relations = structuredClone([...replacement.relations]);
-}
-function finiteNonNegative(value, label) {
-	const result = finiteNumber(value, label);
-	if (result < 0) throw new Error(`${label} must be non-negative`);
-	return result;
-}
-function nextSequentialOrder(rows, trackEntityId) {
-	const orders = rows.relations.filter((relation) => relation.relationKind === "track-clip" && relation.endpoint0EntityId === trackEntityId).map((relation) => rows.entities.find((entity) => entity.entityId === relation.endpoint1EntityId)?.payload.order).filter((order) => typeof order === "number" && Number.isFinite(order));
-	return orders.length === 0 ? 0 : Math.max(...orders) + 1;
-}
-function otherEndpoint(relation, entityId) {
-	if (relation.endpoint0EntityId === entityId) return relation.endpoint1EntityId;
-	if (relation.endpoint1EntityId === entityId) return relation.endpoint0EntityId;
-	throw new Error(`Relation "${relation.relationId}" is not incident to Entity "${entityId}"`);
-}
-function replaceEntity(rows, entityId, replacement) {
-	const index = rows.entities.findIndex((entity) => entity.entityId === entityId);
-	if (index < 0) throw new Error(`Entity id "${entityId}" does not exist`);
-	rows.entities[index] = replacement;
-}
-function markerPayload(value) {
-	return cloneJsonObject(value, "Sequence Marker payload");
-}
-function cloneJsonObject(value, label) {
-	const cloned = structuredClone(value);
-	if (!isJsonObject(cloned)) throw new Error(`${label} must contain only JSON values`);
-	return cloned;
-}
-function cloneJsonValue(value, label) {
-	return cloneJsonObject({ value }, label).value;
-}
-function cloneRows(rows) {
-	return {
-		entities: rows.entities.map((entity) => structuredClone(entity)),
-		relations: rows.relations.map((relation) => structuredClone(relation))
-	};
-}
-const numericMarkerValidation = { compareMarkerPoints: (_marker, _range, left, right) => {
-	if (typeof left !== "number" || !Number.isFinite(left) || typeof right !== "number" || !Number.isFinite(right)) throw new Error("Sequence Marker points must use finite numeric coordinates");
-	return left - right;
-} };
+});
+//#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/entity-editor/legacy-entity-migration.ts
-/** One-time import only. Ordinary editor operations must never reverse-diff a legacy document. */
-function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
-	entities: [],
-	relations: []
-}, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`) {
-	assertSupportedLegacy(legacy);
-	if (initial.entities.some((row) => row.entityKind === "timeline")) fail("Timeline already exists; migration is not an editing operation");
-	if (legacy.meta.schema_version === "video-document/entity-projection-v1") fail("An entity projection cannot be migrated as legacy state");
-	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
-	let entities = structuredClone([...initial.entities]);
-	let relations = structuredClone([...initial.relations]);
-	const addEntity = (kind, payload, existingId) => {
-		const entityId = createEntityId(existingId ?? idFactory("entity"));
-		if (entities.some((row) => row.entityId === entityId)) fail(`Migration entity identity collision: ${entityId}`);
-		entities.push({
-			entityId,
-			entityKind: kind,
-			payload
+//#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"
+			]
 		});
-		return entityId;
-	};
-	const link = (kind, from, to, metadata = {}) => {
-		const relationId = createRelationId(idFactory("relation"));
-		if (relations.some((row) => row.relationId === relationId)) fail(`Migration relation identity collision: ${relationId}`);
-		relations.push({
-			relationId,
-			relationKind: kind,
-			endpoint0EntityId: createEntityId(from),
-			endpoint1EntityId: createEntityId(to),
-			metadata,
-			trace: {}
+		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"
+			]
 		});
-	};
-	const facts = /* @__PURE__ */ new Map();
-	for (const fact of assetFacts) {
-		if (facts.has(fact.assetId)) fail(`Duplicate asset facts for ${fact.assetId}`);
-		facts.set(fact.assetId, fact);
-	}
-	const contentByPartId = /* @__PURE__ */ new Map();
-	const scriptBySpeechClipId = /* @__PURE__ */ new Map();
-	for (const track of legacy.tracks ?? []) for (const item of track.items ?? []) {
-		const part = requirePart(legacy, item.part_id);
-		if (part.video_clip !== void 0) {
-			const assetId = part.video_clip.origin_media_id;
-			const fact = facts.get(assetId);
-			if (fact === void 0) fail(`Missing factual media metadata for ${assetId}`);
-			if (fact.kind !== "image" && fact.kind !== "video") fail(`Legacy video Clip ${item.part_id} requires an image or video fact`);
-			const imported = importMediaAsset({
-				entities,
-				relations
-			}, fact, idFactory);
-			entities = [...imported.rows.entities];
-			relations = [...imported.rows.relations];
-			contentByPartId.set(item.part_id, imported.contentEntityId);
-		} else if (part.speech !== void 0) {
-			const speech = part.speech;
-			const imported = importMediaAsset({
-				entities,
-				relations
-			}, {
-				assetId: speech.origin_speech_id,
-				kind: "voice",
-				durationMs: speech.media_duration_ms,
-				storageKey: speech.audio_storage_key,
-				voice: {
-					system: "voice-library",
-					key: speech.voice.id,
-					...speech.voice.name === void 0 ? {} : { name: speech.voice.name }
-				}
-			}, idFactory);
-			entities = [...imported.rows.entities];
-			relations = [...imported.rows.relations];
-			contentByPartId.set(item.part_id, imported.contentEntityId);
-			scriptBySpeechClipId.set(item.part_id, ensureAudioScript(imported.contentEntityId, speech.audio_script, entities, relations, addEntity, link));
-		} else if (part.bgm !== void 0) {
-			const bgm = part.bgm;
-			const fact = facts.get(bgm.origin_media_id);
-			if (fact === void 0) fail(`Missing factual media metadata for ${bgm.origin_media_id}`);
-			if (fact.kind !== "audio") fail(`Legacy BGM ${item.part_id} requires an audio fact`);
-			if (fact.storageKey !== bgm.audio_storage_key) fail(`Factual storage key conflicts with legacy BGM ${item.part_id}`);
-			const imported = importMediaAsset({
-				entities,
-				relations
-			}, fact, idFactory);
-			entities = [...imported.rows.entities];
-			relations = [...imported.rows.relations];
-			contentByPartId.set(item.part_id, imported.contentEntityId);
-		}
 	}
-	const timeline = addEntity("timeline", legacy.timeline?.unit_time_ms === void 0 ? {} : { unit_time_ms: legacy.timeline.unit_time_ms });
-	const trackIds = /* @__PURE__ */ new Map();
-	for (const [order, oldTrack] of (legacy.tracks ?? []).entries()) {
-		const track = addEntity("track", {
-			role: oldTrack.parts_kind,
-			order,
-			...oldTrack.is_hidden === void 0 ? {} : { hidden: oldTrack.is_hidden }
-		}, oldTrack.id);
-		trackIds.set(oldTrack, track);
-		link("timeline-track", timeline, track);
-	}
-	for (const oldTrack of legacy.tracks ?? []) {
-		const track = trackIds.get(oldTrack);
-		for (const [order, item] of (oldTrack.items ?? []).entries()) {
-			const part = requirePart(legacy, item.part_id);
-			const role = oldTrack.parts_kind;
-			const volume = part.video_clip?.volume ?? part.speech?.volume ?? part.bgm?.volume;
-			const clip = addEntity("clip", {
-				...volume === void 0 ? {} : { volume },
-				...item.time_position.mode === "sequential" && !(role === "video_clip" && normalizedMainRanges !== void 0) || role === "bgm" ? { order: role === "bgm" ? 0 : order } : {}
-			}, item.part_id);
-			let content = contentByPartId.get(item.part_id);
-			let duration;
-			let markerPayload;
-			if (part.video_clip !== void 0) {
-				const video = part.video_clip;
-				duration = effectiveVideoClipDurationMs(video);
-				const fact = facts.get(video.origin_media_id);
-				const rate = speedOf(video.speed_shift);
-				markerPayload = {
-					sourceRange: {
-						start: video.play_in,
-						end: video.play_out
-					},
-					duration: {
-						mode: "fixed",
-						value: duration
-					},
-					...(fact.kind === "image" || fact.kind === "video") && video.speed_shift !== void 0 ? { timeRemapping: {
-						kind: "linear",
-						mode: video.speed_shift?.mode ?? "constant",
-						rate
-					} } : {}
-				};
-			} else if (part.speech !== void 0) {
-				duration = part.speech.media_duration_ms;
-				markerPayload = {
-					sourceRange: {
-						start: 0,
-						end: duration
-					},
-					duration: {
-						mode: "fixed",
-						value: duration
-					}
-				};
-			} else if (part.caption !== void 0) {
-				const caption = part.caption;
-				duration = caption.initial_duration_ms;
-				content = addEntity("caption", {
-					extent: {
-						kind: "bounded",
-						start: 0,
-						end: duration
-					},
-					sampling: "native",
-					coordinateSpace: "milliseconds",
-					text: caption.text,
-					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
-				});
-				const asset = addEntity("asset", { inline: {
-					mediaType: "text/plain",
-					text: caption.text
-				} });
-				link("physical-asset", content, asset);
-				const voice = contentByPartId.get(caption.speech_part_id);
-				const script = scriptBySpeechClipId.get(caption.speech_part_id);
-				link("caption-alignment", content, voice, { alignment: {
-					start: caption.start_ms,
-					end: caption.start_ms + duration
-				} });
-				link("caption-provenance", content, script, { segmentAlignment: [] });
-				markerPayload = {
-					sourceRange: {
-						start: 0,
-						end: duration
-					},
-					duration: {
-						mode: "fixed",
-						value: duration
-					}
-				};
-			} else {
-				const bgm = part.bgm;
-				const fact = facts.get(bgm.origin_media_id);
-				if (fact.kind !== "audio") fail(`Legacy BGM ${item.part_id} requires an audio fact`);
-				duration = fact.durationMs;
-				markerPayload = {
-					sourceRange: {
-						start: 0,
-						end: duration
-					},
-					duration: { mode: "from-source" },
-					durationPolicy: "timeline"
-				};
-			}
-			if (content === void 0) fail(`Migration could not resolve content for ${item.part_id}`);
-			const normalizedMainRange = role === "video_clip" ? normalizedMainRanges?.get(item.part_id) : void 0;
-			if (normalizedMainRange !== void 0) markerPayload = {
-				...markerPayload,
-				targetRange: normalizedMainRange
-			};
-			else if (item.time_position.mode === "absolute" && role !== "bgm") markerPayload = {
-				...markerPayload,
-				targetRange: {
-					start: item.time_position.offsetMs,
-					end: item.time_position.offsetMs + duration
-				}
-			};
-			else if (item.time_position.mode === "anchored") markerPayload = {
-				...markerPayload,
-				anchorOffset: item.time_position.offsetMs
-			};
-			const marker = addEntity("sequence-marker", markerPayload);
-			link("track-clip", track, clip);
-			link("clip-marker", clip, marker);
-			link("marker-content", marker, content);
-			if (item.time_position.mode === "anchored") link("clip-anchor", clip, item.time_position.anchorPartId);
-		}
-	}
-	const rows = {
-		entities,
-		relations
-	};
-	assertEntityProjectionPreservesLegacy(legacy, projectEntityTimeline(rows, legacy.meta), rows);
-	return rows;
-}
-/** Server gate: a cutover may change representation, never the existing render facts. */
-function assertEntityProjectionPreservesLegacy(legacy, projection, rows) {
-	assertSupportedLegacy(legacy);
-	if (projection.meta.schema_version !== "video-document/entity-projection-v1") fail("Expected an entity projection for migration");
-	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
-	const compatibilityFacts = (document) => {
-		const { version: _version, ...view } = fromVideoDocument(document);
-		for (const part of Object.values(view.part_library ?? {})) {
-			const speech = part.speech;
-			if (speech?.phoneme_script === null) delete speech.phoneme_script;
-		}
-		const { schema_version: _schemaVersion, version: _metaVersion, ...meta } = document.meta;
-		return {
-			meta,
-			view
-		};
-	};
-	if (canonical(compatibilityFacts(legacy)) !== canonical(compatibilityFacts(projection))) fail("Entity migration must preserve all existing timeline facts; edit after cutover");
-	const trackOrders = [];
-	for (const oldTrack of legacy.tracks ?? []) {
-		const candidates = rows.entities.filter((row) => row.entityKind === "track" && (oldTrack.id === void 0 ? row.payload.role === oldTrack.parts_kind : row.entityId === oldTrack.id));
-		if (candidates.length !== 1) fail("Migration must preserve every Track identity");
-		const track = candidates[0];
-		if (track.payload.role !== oldTrack.parts_kind || (track.payload.hidden ?? false) !== (oldTrack.is_hidden ?? false)) fail("Migration must preserve Track role and visibility");
-		if (typeof track.payload.order !== "number" || !Number.isFinite(track.payload.order)) fail("Migration must preserve Track order");
-		trackOrders.push(track.payload.order);
-		const sequentialOrders = [];
-		for (const item of oldTrack.items ?? []) {
-			const clip = rows.entities.find((row) => row.entityId === item.part_id && row.entityKind === "clip");
-			const binding = rows.relations.filter((row) => row.relationKind === "clip-marker" && row.endpoint0EntityId === item.part_id && rows.entities.some((entity) => entity.entityId === row.endpoint1EntityId && entity.entityKind === "sequence-marker"));
-			const marker = rows.entities.find((row) => row.entityId === binding[0]?.endpoint1EntityId && row.entityKind === "sequence-marker");
-			if (clip === void 0 || binding.length !== 1 || marker === void 0) fail("Migration must preserve Clip/Marker placement identity");
-			const anchors = rows.relations.filter((row) => row.relationKind === "clip-anchor" && row.endpoint0EntityId === clip.entityId);
-			const normalizedMainRange = oldTrack.parts_kind === "video_clip" ? normalizedMainRanges?.get(item.part_id) : void 0;
-			if (normalizedMainRange !== void 0) {
-				if (clip.payload.order !== void 0 || !isExactRange(marker.payload.targetRange, normalizedMainRange) || marker.payload.anchorOffset !== void 0 || anchors.length !== 0) fail("Migration must preserve the legacy overlap-normalized main Track");
-			} else if (oldTrack.parts_kind === "bgm") {
-				if (clip.payload.order !== 0 || marker.payload.targetRange !== void 0 || marker.payload.anchorOffset !== void 0 || marker.payload.durationPolicy !== "timeline" || anchors.length !== 0) fail("Migration must preserve timeline-filling BGM semantics");
-			} else if (item.time_position.mode === "sequential") {
-				if (marker.payload.targetRange !== void 0 || marker.payload.anchorOffset !== void 0 || typeof clip.payload.order !== "number" || !Number.isFinite(clip.payload.order) || anchors.length !== 0) fail("Migration must preserve sequential placement semantics");
-				sequentialOrders.push(clip.payload.order);
-			} else if (item.time_position.mode === "absolute") {
-				const target = marker.payload.targetRange;
-				if (clip.payload.order !== void 0 || !isRangeStartingAt(target, item.time_position.offsetMs) || marker.payload.anchorOffset !== void 0 || anchors.length !== 0) fail("Migration must preserve absolute placement semantics");
-			} else if (clip.payload.order !== void 0 || marker.payload.targetRange !== void 0 || marker.payload.anchorOffset !== item.time_position.offsetMs || anchors.length !== 1 || anchors[0].endpoint1EntityId !== item.time_position.anchorPartId) fail("Migration must preserve anchored placement semantics");
-		}
-		if (sequentialOrders.some((order, index) => index > 0 && order <= sequentialOrders[index - 1])) fail("Migration must preserve sequential Clip order");
-	}
-	if (trackOrders.some((order, index) => index > 0 && order <= trackOrders[index - 1])) fail("Migration must preserve Track stacking order");
-}
-function assertSupportedLegacy(document) {
-	assertValidVideoDocument(document);
-	const tracks = document.tracks ?? [];
-	assertKnownFields(document.timeline ?? {}, ["unit_time_ms"], "Timeline");
-	if (document.timeline?.unit_time_ms !== void 0 && (typeof document.timeline.unit_time_ms !== "number" || !Number.isFinite(document.timeline.unit_time_ms) || document.timeline.unit_time_ms <= 0)) fail("Migration requires a positive finite unit_time_ms");
-	const seenRoles = /* @__PURE__ */ new Set();
-	const placed = /* @__PURE__ */ new Map();
-	for (const track of tracks) {
-		const role = track.parts_kind;
-		if (role === void 0 || ![
-			"video_clip",
-			"speech",
-			"caption",
-			"bgm"
-		].includes(role)) fail("Every legacy Track requires a supported role");
-		if (seenRoles.has(role)) fail(`The compatibility editor supports only one ${role} Track`);
-		seenRoles.add(role);
-		if (track.id !== void 0 && (track.id.trim() === "" || track.id.trim() !== track.id)) fail("Migration requires trimmed Track identities");
-		for (const item of track.items ?? []) {
-			if (item.part_id.trim() === "" || item.part_id.trim() !== item.part_id) fail("Migration requires trimmed Clip identities");
-			if (placed.has(item.part_id)) fail(`Legacy part ${item.part_id} is placed more than once`);
-			placed.set(item.part_id, {
-				track,
-				item
-			});
-			assertKnownFields(item.time_position, item.time_position.mode === "sequential" ? ["mode"] : [
-				"mode",
-				"anchorPartId",
-				"offsetMs"
-			], "placement");
-			if (item.time_position.mode === "absolute") requireMilliseconds(item.time_position.offsetMs, "absolute offset");
-			if (item.time_position.mode === "anchored") {
-				if (item.time_position.anchorPartId.trim() === "" || item.time_position.anchorPartId.trim() !== item.time_position.anchorPartId) fail("Migration requires a trimmed anchor identity");
-				requireMilliseconds(item.time_position.offsetMs, "anchor offset");
-			}
-			if (item.fallback_abs_ms !== void 0) requireMilliseconds(item.fallback_abs_ms, "anchor fallback");
-			assertKnownFields(item, [
-				"part_id",
-				"time_position",
-				"fallback_abs_ms"
-			], "TrackItem");
-		}
-		assertKnownFields(track, [
-			"id",
-			"parts_kind",
-			"is_hidden",
-			"items"
-		], "Track");
-	}
-	for (const [id, part] of Object.entries(document.part_library ?? {})) {
-		const placement = placed.get(id);
-		if (placement === void 0) fail(`Cannot discard unplaced legacy part ${id}`);
-		assertPartSupported(id, part, placement.track.parts_kind);
-	}
-	for (const id of placed.keys()) if (document.part_library?.[id] === void 0) fail(`Placed Clip ${id} has no part payload`);
-	assertLegacyRelations(document, placed);
-}
-function assertPartSupported(id, part, role) {
-	assertKnownFields(part, [
-		"video_clip",
-		"speech",
-		"caption",
-		"bgm"
-	], "Part");
-	const present = [
-		"video_clip",
-		"speech",
-		"caption",
-		"bgm"
-	].filter((kind) => part[kind] !== void 0);
-	if (present.length !== 1 || present[0] !== role) fail(`Legacy part ${id} must match its ${role} Track`);
-	if (part.video_clip !== void 0) {
-		const clip = part.video_clip;
-		if (clip.id !== id || clip.kind !== "video_clip" || !trimmed(clip.origin_media_id) || clip.play_in === void 0 || clip.play_out === void 0) fail("Migration requires complete Clip identity, media and trim facts");
-		requireMilliseconds(clip.play_in, "Clip play_in");
-		requireMilliseconds(clip.play_out, "Clip play_out");
-		if (clip.play_out <= clip.play_in) fail("Migration requires a non-empty Clip trim window");
-		requireFinite(clip.volume, "Clip volume");
-		const speed = clip.speed_shift;
-		if (speed !== void 0 && (speed.category !== "linear" || speed.config?.linear === void 0 || speed.mode !== void 0 && typeof speed.mode !== "string")) fail("Nonlinear speed requires an entity remapping adapter");
-		if (speed !== void 0) {
-			const rate = speed.config?.linear?.speed;
-			if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0) fail("Migration requires a positive finite speed");
-			assertKnownFields(speed, [
-				"category",
-				"mode",
-				"config"
-			], "speed_shift");
-			assertKnownFields(speed.config, ["linear"], "speed config");
-			assertKnownFields(speed.config.linear, ["speed"], "linear speed");
-		}
-		assertKnownFields(clip, [
-			"id",
-			"kind",
-			"origin_media_id",
-			"play_in",
-			"play_out",
-			"volume",
-			"speed_shift"
-		], "Clip");
-	} else if (part.speech !== void 0) {
-		const speech = part.speech;
-		const phonemeScript = speech.phoneme_script;
-		if (speech.id !== id || speech.kind !== "speech" || !trimmed(speech.origin_speech_id) || !trimmed(speech.audio_storage_key) || typeof speech.audio_script !== "string") fail("Migration requires complete Speech identity and physical take facts");
-		requirePositiveMilliseconds(speech.media_duration_ms, "Speech duration");
-		requireFinite(speech.volume, "Speech volume");
-		if (!trimmed(speech.voice?.id)) fail("Migration requires an explicit voice-library identity");
-		if (speech.voice?.name !== void 0 && typeof speech.voice.name !== "string") fail("Migration requires a string voice name when present");
-		if (!Array.isArray(speech.caption_ids) || speech.caption_ids.some((captionId) => !trimmed(captionId))) fail("Migration requires explicit Speech caption identities");
-		if (new Set(speech.caption_ids).size !== speech.caption_ids.length) fail("Migration requires unique Speech caption identities");
-		if (phonemeScript !== void 0 && phonemeScript !== null) fail("Non-null phoneme_script requires a phonetic-script migration adapter");
-		assertKnownFields(speech.voice, ["id", "name"], "voice");
-		assertKnownFields(speech, [
-			"id",
-			"kind",
-			"media_duration_ms",
-			"audio_script",
-			"volume",
-			"audio_storage_key",
-			"origin_speech_id",
-			"voice",
-			"caption_ids",
-			"phoneme_script"
-		], "Speech");
-	} else if (part.caption !== void 0) {
-		const caption = part.caption;
-		if (caption.id !== id || caption.kind !== "caption" || !trimmed(caption.speech_part_id) || typeof caption.text !== "string") fail("Migration requires complete Caption identity, Speech provenance and text");
-		requireMilliseconds(caption.start_ms, "Caption source offset");
-		requirePositiveMilliseconds(caption.initial_duration_ms, "Caption duration");
-		if (caption.style !== void 0) assertCaptionStyle(caption.style);
-		assertKnownFields(caption, [
-			"id",
-			"kind",
-			"initial_duration_ms",
-			"speech_part_id",
-			"text",
-			"start_ms",
-			"style"
-		], "Caption");
-	} else if (part.bgm !== void 0) {
-		const bgm = part.bgm;
-		if (bgm.id !== id || bgm.kind !== "bgm" || !trimmed(bgm.origin_media_id) || !trimmed(bgm.audio_storage_key)) fail("Migration requires complete BGM identity and physical media facts");
-		requireFinite(bgm.volume, "BGM volume");
-		assertKnownFields(bgm, [
-			"id",
-			"kind",
-			"audio_storage_key",
-			"volume",
-			"origin_media_id"
-		], "BGM");
-	}
-}
-function assertLegacyRelations(document, placed) {
-	const captionIdsBySpeech = /* @__PURE__ */ new Map();
-	for (const track of document.tracks ?? []) {
-		if (track.parts_kind === "bgm" && (track.items?.length ?? 0) > 1) fail("The compatibility editor supports only one BGM Clip");
-		for (const item of track.items ?? []) {
-			const part = requirePart(document, item.part_id);
-			const position = item.time_position;
-			if (track.parts_kind === "video_clip" && position.mode === "anchored") fail("Anchored video Clips require an overlay adapter");
-			if (track.parts_kind === "bgm") {
-				if (position.mode !== "absolute" || position.offsetMs !== 0) fail("Legacy BGM must start at the Timeline origin");
-			} else if (position.mode === "anchored") {
-				const host = placed.get(position.anchorPartId);
-				if (host === void 0) fail(`Legacy anchor ${position.anchorPartId} is not placed`);
-				if (track.parts_kind === "speech" && host.track.parts_kind !== "video_clip") fail("Speech may only anchor to a video Clip");
-				if (track.parts_kind === "caption") {
-					if (host.track.parts_kind !== "speech") fail("Caption may only anchor to a Speech Clip");
-					const caption = part.caption;
-					if (position.anchorPartId !== caption.speech_part_id || position.offsetMs !== caption.start_ms) fail("Caption placement must agree with its Speech provenance and source offset");
-				}
-			} else if (track.parts_kind === "caption") fail("Caption placement requires an explicit Speech anchor");
-			if (part.caption !== void 0) {
-				const ids = captionIdsBySpeech.get(part.caption.speech_part_id) ?? [];
-				ids.push(item.part_id);
-				captionIdsBySpeech.set(part.caption.speech_part_id, ids);
-			}
-		}
-	}
-	for (const [id, placement] of placed) {
-		const speech = requirePart(document, id).speech;
-		if (speech === void 0) continue;
-		const expected = captionIdsBySpeech.get(id) ?? [];
-		if (canonical(speech.caption_ids) !== canonical(expected)) fail(`Speech ${id} caption_ids must agree with the Caption Track order`);
-		if (placement.item.time_position.mode === "anchored") continue;
-		if (placement.item.time_position.mode !== "absolute") fail("Speech placement must be anchored or absolute");
-	}
-	const intervals = (fromVideoDocument(document).main_track?.items ?? []).map((item) => {
-		const clip = document.part_library?.[item.part_id]?.video_clip;
-		if (clip === void 0) fail("Projection must preserve every video Clip");
-		return {
-			start: item.abs_time_position ?? 0,
-			end: (item.abs_time_position ?? 0) + effectiveVideoClipDurationMs(clip)
-		};
-	}).sort((left, right) => left.start - right.start);
-	if (intervals.some((interval, index) => index > 0 && interval.start < intervals[index - 1].end)) fail("Overlapping video Clips require an overlay adapter");
-}
+});
+//#endregion
+//#region src/editor/schemas/set-bgm.ts
 /**
-* Legacy reads perform one speech-overlap pass after laying the visual lane out
-* sequentially. Entity reads deliberately do not run that hidden cascade. When
-* the pass moved any visual Clip, cutover therefore records the complete solved
-* visual lane as explicit target ranges. Mixing absolute and sequential Clips
-* would create two unrelated placement chains and could reorder the lane.
+* 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.
 */
-function overlapNormalizedMainRanges(document) {
-	const track = document.tracks?.find((candidate) => candidate.parts_kind === "video_clip");
-	if (track === void 0 || (track.items?.length ?? 0) === 0) return void 0;
-	const solved = fromVideoDocument(document).main_track?.items ?? [];
-	const starts = new Map(solved.map((item) => [item.part_id, requireMilliseconds(item.abs_time_position, `Solved position for ${item.part_id ?? "unknown Clip"}`)]));
-	let cursor = 0;
-	let moved = false;
-	const ranges = /* @__PURE__ */ new Map();
-	for (const item of track.items ?? []) {
-		const part = requirePart(document, item.part_id).video_clip;
-		if (part === void 0) fail(`Projection must preserve video Clip ${item.part_id}`);
-		const duration = effectiveVideoClipDurationMs(part);
-		const start = starts.get(item.part_id);
-		if (start === void 0) fail(`Projection must preserve video Clip ${item.part_id}`);
-		if (start !== cursor) moved = true;
-		const end = start + duration;
-		requireMilliseconds(end, `Solved end for ${item.part_id}`);
-		ranges.set(item.part_id, {
-			start,
-			end
-		});
-		cursor += duration;
-	}
-	return moved ? ranges : void 0;
-}
-function requirePart(document, partId) {
-	const part = document.part_library?.[partId];
-	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
-	return part;
-}
-function ensureAudioScript(voiceEntityId, text, entities, relations, addEntity, link) {
-	const renders = relations.filter((relation) => relation.relationKind === "audio-script-render" && relation.endpoint0EntityId === voiceEntityId);
-	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous AudioScript provenance`);
-	if (renders.length === 1) {
-		const script = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "audio-script");
-		if (script === void 0 || scriptText(script) !== text) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
-		return script.entityId;
-	}
-	const script = addEntity("audio-script", { segments: [{
-		segmentId: "segment-0",
-		text
-	}] });
-	link("audio-script-render", voiceEntityId, script);
-	return script;
-}
-function scriptText(script) {
-	const segments = script.payload.segments;
-	if (!Array.isArray(segments)) fail("AudioScript requires segments");
-	return segments.map((segment) => {
-		if (segment === null || typeof segment !== "object" || Array.isArray(segment) || typeof segment.text !== "string") fail("AudioScript segment requires text");
-		return segment.text;
-	}).join("");
-}
-function toEntityCaptionStyle(style) {
-	return {
-		...style.font_id === void 0 ? {} : { font: {
-			system: "font-library",
-			key: style.font_id
-		} },
-		...style.font_size === void 0 ? {} : { fontSize: style.font_size },
-		...style.font_color === void 0 ? {} : { fontColor: style.font_color },
-		...style.font_weight === void 0 ? {} : { fontWeight: style.font_weight },
-		...style.entrance_animation === void 0 ? {} : { entranceAnimation: style.entrance_animation },
-		...style.entrance_animation_duration_ms === void 0 ? {} : { entranceAnimationDurationMs: style.entrance_animation_duration_ms },
-		...style.stroke_color === void 0 ? {} : { strokeColor: style.stroke_color },
-		...style.stroke_width === void 0 ? {} : { strokeWidth: style.stroke_width },
-		...style.position_x === void 0 ? {} : { positionX: style.position_x },
-		...style.position_y === void 0 ? {} : { positionY: style.position_y }
-	};
-}
-function assertCaptionStyle(style) {
-	if (style.font_id !== void 0 && !trimmed(style.font_id)) fail("Caption font_id must be a trimmed identity");
-	for (const value of [
-		style.font_size,
-		style.font_weight,
-		style.entrance_animation_duration_ms,
-		style.stroke_width,
-		style.position_x,
-		style.position_y
-	]) if (value !== void 0) requireFinite(value, "Caption style number");
-	for (const value of [
-		style.font_color,
-		style.entrance_animation,
-		style.stroke_color
-	]) if (value !== void 0 && typeof value !== "string") fail("Caption style text must be a string");
-	assertKnownFields(style, [
-		"font_id",
-		"font_size",
-		"font_color",
-		"font_weight",
-		"entrance_animation",
-		"entrance_animation_duration_ms",
-		"stroke_color",
-		"stroke_width",
-		"position_x",
-		"position_y"
-	], "Caption style");
-}
-function isRangeStartingAt(value, expectedStart) {
-	return value !== null && typeof value === "object" && !Array.isArray(value) && value.start === expectedStart;
-}
-function isExactRange(value, expected) {
-	return value !== null && typeof value === "object" && !Array.isArray(value) && value.start === expected.start && value.end === expected.end;
-}
-function requireFinite(value, label) {
-	if (typeof value !== "number" || !Number.isFinite(value)) fail(`${label} must be finite`);
-	return value;
-}
-function requireMilliseconds(value, label) {
-	const result = requireFinite(value, label);
-	if (!Number.isSafeInteger(result) || result < 0) fail(`${label} must be non-negative whole milliseconds`);
-	return result;
-}
-function requirePositiveMilliseconds(value, label) {
-	const result = requireMilliseconds(value, label);
-	if (result <= 0) fail(`${label} must be positive`);
-	return result;
-}
-function trimmed(value) {
-	return typeof value === "string" && value.trim() !== "" && value.trim() === value;
-}
-function assertKnownFields(value, fields, label) {
-	if (Object.entries(value).some(([key, field]) => field !== void 0 && !fields.includes(key))) fail(`Unknown legacy ${label} fields require an explicit migration adapter`);
-}
-function canonical(value) {
-	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, field]) => field !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, field]) => `${JSON.stringify(key)}:${canonical(field)}`).join(",")}}`;
-	return JSON.stringify(value) ?? "undefined";
-}
-function fail(message) {
-	throw new EntityTimelineProjectionError(message);
-}
+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) {
@@ -2729,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);
@@ -2813,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",
@@ -2860,7 +1255,7 @@ var SemanticEditor = class {
 			const newItems = [];
 			const newClipIds = [];
 			for (const clip of input.new_clips) {
-				const partId = this.idFactory("clip");
+				const partId = generatePartId("clip");
 				setPart(draft, partId, { video_clip: {
 					id: partId,
 					kind: "video_clip",
@@ -3480,111 +1875,6 @@ function deleteAnchoredSubtree(draft, clipId) {
 	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 `[]`.
-*/
-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");
-	}
-}
-/** 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 "MoveVideoClipsByAnchor":
-			await editor.moveVideoClipsByAnchor(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 "ReplaceVideoClipSequence":
-			await editor.replaceVideoClipSequence(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)}`);
-		}
-	}
-}
-//#endregion
 //#region src/editor/types.ts
 /** Runtime list of the frozen, implemented kinds (for guards / introspection). */
 const IMPLEMENTED_SEMANTIC_OP_KINDS = [
@@ -3779,18 +2069,6 @@ var ManualSyncDoc = class ManualSyncDoc {
 		return fromVideoDocument(this.adapter.snapshot());
 	}
 	/**
-	* Replay a deterministic sandbox journal into this document.
-	*
-	* The adapter stays private so callers cannot bypass the manual-sync
-	* lifecycle; journal replay is the one host-side operation that needs the
-	* adapter's transaction boundary and recorded id queue. Durability is still
-	* explicit: call {@link push} after replay and report success only from its
-	* verdict.
-	*/
-	async replayJournal(journal) {
-		await replayJournal(this.adapter, journal);
-	}
-	/**
 	* Mark the document state the caller has just observed, for a later
 	* {@link hasChangedSince}.
 	*
@@ -3882,6 +2160,7 @@ var ManualSyncDoc = class ManualSyncDoc {
 			if (serverVV != null) this.watermark = serverVV;
 			return {
 				kind: response.kind,
+				mengineUpdateSeq: response.version?.update_seq ?? response.update_seq ?? void 0,
 				updateSeq: response.update_seq ?? void 0,
 				collaborated: serverVV != null && !covers(localVersion, serverVV)
 			};
@@ -4000,6 +2279,7 @@ var SseConnection = class {
 						for (const update of event.updates) this.onUpdate(update);
 					}
 				});
+				if (!signal.aborted) this.setStatus("connecting", /* @__PURE__ */ new Error("SSE stream closed"));
 			} catch (error) {
 				if (signal.aborted) break;
 				this.setStatus("connecting", error instanceof Error ? error : new Error(String(error)));
@@ -4052,6 +2332,7 @@ var MedeoHttpDocStorage = class {
 	async getDoc(docId) {
 		this.assertDocId(docId);
 		const snapshot = await this.client.fetchSnapshot();
+		this.reportServerVersion(snapshot.version?.server_vv);
 		const now = /* @__PURE__ */ new Date();
 		return {
 			docId,
@@ -4063,6 +2344,7 @@ var MedeoHttpDocStorage = class {
 	async getDocDiff(docId, knownVersion) {
 		this.assertDocId(docId);
 		const response = await this.client.sync(knownVersion);
+		this.reportServerVersion(response.server_vv);
 		return {
 			docId,
 			missing: base64ToBytes(response.update),
@@ -4093,7 +2375,7 @@ var MedeoHttpDocStorage = class {
 		if (update.data.byteLength === 0) return {};
 		try {
 			const response = await this.client.pushUpdate(update.data);
-			const serverVV = decodeServerVV(response.version?.server_vv);
+			const serverVV = this.reportServerVersion(response.version?.server_vv);
 			this.events.emit("pushOutcome", {
 				kind: response.kind,
 				updateSeq: response.update_seq ?? void 0,
@@ -4121,6 +2403,15 @@ var MedeoHttpDocStorage = class {
 	subscribePushOutcome(callback) {
 		return this.events.on("pushOutcome", callback);
 	}
+	/** Authoritative HTTP reads and accepted pushes, never inferred from SSE bytes. */
+	subscribeServerVersion(callback) {
+		return this.events.on("serverVersion", callback);
+	}
+	reportServerVersion(encoded) {
+		const version = decodeServerVV(encoded);
+		if (version != null) this.events.emit("serverVersion", version);
+		return version;
+	}
 	async deleteDoc(_docId) {
 		throw new Error("MedeoHttpDocStorage does not support deleteDoc");
 	}
@@ -4302,8 +2593,14 @@ var MengineDocSession = class {
 	adapterValue = null;
 	editorValue = null;
 	started = false;
+	destroyed = false;
+	lifetime = null;
+	hasConnected = false;
+	initialVersionValue = null;
+	localVersionValue = null;
+	pushErrorValue = null;
 	/**
-	* Latest server oplog version seen on a push outcome. Lets `waitForServerAck`
+	* Latest server oplog version seen on an authoritative HTTP response. 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).
 	*/
@@ -4315,8 +2612,7 @@ var MengineDocSession = class {
 		this.server = new MedeoHttpDocStorage({
 			docId: options.docId,
 			client: options.client,
-			sseReconnectDelayMs: options.sseReconnectDelayMs,
-			readonlyMode: options.readonlyMode
+			sseReconnectDelayMs: options.sseReconnectDelayMs
 		});
 		this.synchronizer = new ClientServerSynchronizer(this.local, this.server);
 		this.manager = new DocManager(this.local, this.synchronizer);
@@ -4332,14 +2628,14 @@ var MengineDocSession = class {
 		return this.server.subscribePushOutcome(callback);
 	}
 	/**
-	* Resolve once the server has durably accepted the local document state as of
+	* Resolve once the server has durably accepted the local commits 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.
+	* latest local commit's version (or the loaded baseline before any edit) and
+	* resolves when an authoritative server version covers it. Remote-only
+	* imports do not extend this target, matching the displayed confirmation state.
 	*
 	* 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
@@ -4354,31 +2650,39 @@ var MengineDocSession = class {
 	* @throws {MengineAckFailedError} on timeout, rejection, or transport failure.
 	*/
 	async waitForServerAck(options = {}) {
-		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
+		if (this.adapterValue == null || this.lifetime == null) throw new Error("mengine doc session is not started");
 		const timeoutMs = options.timeoutMs ?? 15e3;
-		const target = this.manager.connectDoc(this.docId).version();
+		const target = this.confirmationTarget() ?? this.manager.connectDoc(this.docId).version();
+		const signal = this.lifetime.signal;
 		if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) return;
 		await new Promise((resolve, reject) => {
-			let off = () => {};
+			const cleanup = [];
 			let done = false;
 			const settle = (error) => {
 				if (done) return;
 				done = true;
 				clearTimeout(timer);
-				off();
+				cleanup.forEach((off) => off());
 				if (error == null) resolve();
 				else reject(error);
 			};
 			const timer = setTimeout(() => {
 				settle(new MengineAckFailedError("timeout", void 0, void 0, `mengine did not acknowledge the update within ${timeoutMs}ms`));
 			}, timeoutMs);
-			off = this.server.subscribePushOutcome((outcome) => {
+			const onAbort = () => settle(new MengineAckFailedError("failed", void 0, void 0, "mengine doc session destroyed"));
+			signal.addEventListener("abort", onAbort, { once: true });
+			cleanup.push(() => signal.removeEventListener("abort", onAbort));
+			cleanup.push(this.events.on("syncState", () => {
+				if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) settle(void 0);
+			}));
+			cleanup.push(this.server.subscribePushOutcome((outcome) => {
 				if (outcome.kind === "rejected" || outcome.kind === "failed") {
 					settle(new MengineAckFailedError(outcome.kind, outcome.code, outcome.error, outcome.error?.message ?? `mengine push ${outcome.kind}`));
 					return;
 				}
-				if (outcome.serverVV != null && serverCovers(outcome.serverVV, target)) settle(void 0);
-			});
+			}));
+			if (signal.aborted) onAbort();
+			else this.synchronizer.requestSync(this.docId);
 		});
 	}
 	/**
@@ -4391,24 +2695,6 @@ var MengineDocSession = class {
 		if (this.editorValue == null) throw new Error("mengine doc session is not started");
 		return this.editorValue;
 	}
-	/**
-	* 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.
-	*/
-	version() {
-		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
-		return bytesToBase64(this.adapterValue.doc.oplogVersion().encode());
-	}
-	/**
-	* 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.
-	*/
-	get documentAdapter() {
-		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
-		return this.adapterValue;
-	}
 	/** Current document snapshot (read model). */
 	snapshot() {
 		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
@@ -4422,8 +2708,23 @@ var MengineDocSession = class {
 	* surfaces through `subscribe`.
 	*/
 	async start() {
+		if (this.destroyed) throw new Error("mengine doc session destroyed");
 		if (this.started) return this.snapshot();
 		this.started = true;
+		this.lifetime = new AbortController();
+		this.disposables.add(this.server.subscribeServerVersion((version) => {
+			this.serverVVValue = version;
+			if (this.getSyncState().confirmation === "confirmed") this.pushErrorValue = null;
+			this.emitSyncState();
+		}));
+		this.disposables.add(this.server.subscribePushOutcome((outcome) => {
+			this.pushErrorValue = outcome.kind === "failed" || outcome.kind === "rejected" ? outcome.error ?? /* @__PURE__ */ new Error(`mengine push ${outcome.kind}`) : null;
+			this.emitSyncState();
+		}));
+		this.disposables.add(this.server.connection.onStatusChanged((status) => {
+			if (status === "connected") this.hasConnected = true;
+			this.emitSyncState();
+		}));
 		this.local.connection.connect();
 		this.server.connection.connect();
 		this.disposables.add(() => this.local.connection.disconnect());
@@ -4439,19 +2740,46 @@ var MengineDocSession = class {
 		this.disposables.add(() => this.manager.disconnectDoc(this.docId));
 		const unsubscribe = doc.subscribe((event) => {
 			if (this.adapterValue == null) return;
+			if (this.initialVersionValue == null && this.hasContent()) this.initialVersionValue = doc.version();
+			if (event.by === "local") this.localVersionValue = doc.version();
+			this.emitSyncState();
 			this.events.emit("update", {
 				source: event.by === "local" ? "local" : "remote",
 				snapshot: this.adapterValue.snapshot()
 			});
 		});
 		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;
+		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => {
+			this.events.emit("state", state);
+			this.emitSyncState();
 		}));
 		await this.waitForContent();
+		this.initialVersionValue ??= doc.version();
+		this.emitSyncState();
 		return this.snapshot();
 	}
+	getSyncState() {
+		const state = this.getState();
+		const target = this.confirmationTarget();
+		const confirmation = this.serverVVValue == null || target == null ? this.localVersionValue == null ? "unknown" : "pending" : serverCovers(this.serverVVValue, target) ? "confirmed" : "pending";
+		const connection = !this.started ? "disconnected" : this.server.connection.status === "connected" ? "connected" : this.hasConnected || this.server.connection.error != null ? "disconnected" : "connecting";
+		return {
+			confirmation,
+			phase: connection === "disconnected" ? "offline" : this.pushErrorValue != null || state.error != null ? "failed" : connection === "connecting" ? "connecting" : state.syncing ? "syncing" : "idle"
+		};
+	}
+	confirmationTarget() {
+		return this.localVersionValue ?? this.initialVersionValue;
+	}
+	/** Immediately supplies current state; unsubscribe when the host changes docs. */
+	subscribeSyncState(cb) {
+		const off = this.events.on("syncState", cb);
+		cb(this.getSyncState());
+		return off;
+	}
+	emitSyncState() {
+		this.events.emit("syncState", this.getSyncState());
+	}
 	subscribe(cb) {
 		return this.events.on("update", cb);
 	}
@@ -4462,7 +2790,12 @@ var MengineDocSession = class {
 		return this.manager.getDocState(this.docId);
 	}
 	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.started = false;
+		this.lifetime?.abort();
 		this.disposables.dispose();
+		this.emitSyncState();
 		this.events.clearAll();
 		this.adapterValue = null;
 		this.editorValue = null;
@@ -4479,13 +2812,21 @@ var MengineDocSession = class {
 	*/
 	async waitForContent() {
 		if (this.hasContent()) return;
-		await new Promise((resolve) => {
+		const signal = this.lifetime.signal;
+		await new Promise((resolve, reject) => {
+			const onAbort = () => {
+				off();
+				reject(/* @__PURE__ */ new Error("mengine doc session destroyed"));
+			};
 			const off = this.events.on("update", () => {
 				if (this.hasContent()) {
 					off();
+					signal.removeEventListener("abort", onAbort);
 					resolve();
 				}
 			});
+			signal.addEventListener("abort", onAbort, { once: true });
+			if (signal.aborted) onAbort();
 		});
 	}
 	hasContent() {
@@ -4519,4 +2860,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assertEntityProjectionPreservesLegacy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+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 };