@mengine/medeo-tool 1.2.1-alpha.7 → 1.2.1-alpha.8

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { i as renderCompactProjection, n as collectAffectedPartIds, r as renderPreview, t as EditSandboxSession } from "./script-session-BF44uKv_.mjs";
-import { ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, replayJournal, toVideoDocument } from "@mengine/medeo-client";
+import { a as collectAffectedPartIds, o as renderPreview, s as renderCompactProjection, t as EditSandboxSession } from "./script-session-CHyIUBkO.mjs";
+import { EntityGraphHttpClient, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, migrateLegacyTimelineToEntities, replayJournal, toVideoDocument } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
 import { randomUUID } from "node:crypto";
 //#region src/sandbox/node-host.ts
@@ -35,7 +35,8 @@ function runEditScript(options) {
 				script: options.script,
 				inputs: options.inputs,
 				entityState: options.entityState,
-				idLabel: options.idLabel
+				idLabel: options.idLabel,
+				entityOnly: options.entityOnly
 			},
 			execArgv: resolveRegisterUrl.pathname.endsWith(".ts") ? [
 				"--experimental-transform-types",
@@ -124,6 +125,8 @@ function runEditScript(options) {
 						entity_base_revision: message.entityBaseRevision,
 						entity_commands: entityCommands.slice(),
 						...message.entityRows !== void 0 ? { entity_rows: message.entityRows } : {},
+						deleted_entity_ids: message.deletedEntityIds,
+						deleted_relation_ids: message.deletedRelationIds,
 						preview: message.preview,
 						logs: logs.slice()
 					},
@@ -204,7 +207,9 @@ const KNOWN_RELATION_KINDS = [
 	"generated",
 	"phonetic-script-provenance",
 	"caption-provenance",
-	"caption-alignment"
+	"caption-alignment",
+	"clip-anchor",
+	"audio-script-render"
 ];
 //#endregion
 //#region src/entity/entity-http-client.ts
@@ -232,7 +237,7 @@ var EntityHttpClient = class {
 	async fetchState() {
 		return toSnapshot(await this.requestJson({ method: "GET" }), this.options.docId);
 	}
-	async commit(expectedRevision, state) {
+	async commit(expectedRevision, state, deletions = {}) {
 		return toSnapshot(await this.requestJson({
 			method: "POST",
 			body: JSON.stringify({
@@ -240,7 +245,9 @@ var EntityHttpClient = class {
 				rows: {
 					entities: state.entities,
 					relations: state.relations
-				}
+				},
+				deleted_entity_ids: [...deletions.deleted_entity_ids ?? []],
+				deleted_relation_ids: [...deletions.deleted_relation_ids ?? []]
 			})
 		}), this.options.docId);
 	}
@@ -320,736 +327,278 @@ async function safeReadJson(response) {
 	}
 }
 //#endregion
-//#region src/sandbox/generated/edit-sandbox-model-context.ts
-/**
-* @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY
-*
-* Runtime copy of the sandbox TypeScript disclosure. The model prompt imports
-* this value so its interface and the checked-in declaration cannot drift.
-*/
-const EDIT_SANDBOX_API_DTS = [
-	"/**",
-	" * @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY",
-	" *",
-	" * Schema version: video-document/v0",
-	" * Semantic ops: 20",
-	" *",
-	" * Boundary: zod `superRefine` / custom refine rules are NOT introspectable and",
-	" * do not appear here. Business mutual-exclusion rules surface via runtime",
-	" * validation errors (L3 feedback channel).",
-	" *",
-	" * @example 读取→计算→批量写",
-	" * ```ts",
-	" * const clips = timeline.clipsInRange(0, 10_000);",
-	" * await edit.setVideoClipSpeedShift({",
-	" *   clips: clips.map((c) => ({ clip_id: c.id, speed_shift: { category: 'linear', mode: 'constant', config: { linear: { speed: 1.5 } } } })),",
-	" * });",
-	" * ```",
-	" *",
-	" * @example anchored 删除",
-	" * ```ts",
-	" * await edit.deleteVideoClips({ clip_ids: ['clip_a'], on_anchored: 'detach' });",
-	" * ```",
-	" */",
-	"",
-	"/**",
-	" * A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.",
-	" */",
-	"export interface SpeedShift {",
-	"  category: 'linear' | 'curve';",
-	"  mode: string;",
-	"  config:",
-	"    | {",
-	"        linear: {",
-	"          /**",
-	"           * @constraint positive",
-	"           */",
-	"          speed: number;",
-	"        };",
-	"      }",
-	"    | {",
-	"        curve: {",
-	"          /**",
-	"           * @constraint minLength(2)",
-	"           */",
-	"          keyframes: {",
-	"            /**",
-	"             * @constraint min(0)",
-	"             * @constraint max(1)",
-	"             */",
-	"            position: number;",
-	"            /**",
-	"             * @constraint min(0)",
-	"             */",
-	"            rate: number;",
-	"            /**",
-	"             * Bezier tangent handle (x, y)",
-	"             */",
-	"            in_tangent?: { x: number; y: number };",
-	"            /**",
-	"             * Bezier tangent handle (x, y)",
-	"             */",
-	"            out_tangent?: { x: number; y: number };",
-	"          }[];",
-	"        };",
-	"      };",
-	"}",
-	"",
-	"/**",
-	" * TTS voice summary attached to a speech",
-	" */",
-	"export interface Voice {",
-	"  /**",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  id: string;",
-	"  name: string;",
-	"}",
-	"",
-	"/**",
-	" * A materialized speech-subtree write (speeches + their captions).",
-	" */",
-	"export interface SpeechAssets {",
-	"  /**",
-	"   * Materialized speech parts to write",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  speeches: {",
-	"    /**",
-	"     * The speech part ID (= side-effect speech_parts[].id)",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    speech_id: string;",
-	"    /**",
-	"     * Host video clip part ID the speech anchors to (RFC 02 §4)",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    anchor_part_id: string;",
-	"    /**",
-	"     * Offset within the host clip (speech.abs = host.abs + offset_ms)",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    offset_ms: number;",
-	"    /**",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    audio_storage_key: string;",
-	"    /**",
-	"     * Duration in milliseconds (> 0)",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    duration_ms: number;",
-	"    audio_script: string;",
-	"    /**",
-	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)",
-	"     * @constraint min(-60)",
-	"     * @constraint max(20)",
-	"     */",
-	"    volume: number;",
-	"    /**",
-	"     * TTS voice summary attached to a speech",
-	"     */",
-	"    voice: {",
-	"      /**",
-	"       * @constraint minLength(1)",
-	"       */",
-	"      id: string;",
-	"      name: string;",
-	"    };",
-	"    /**",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    origin_speech_id: string;",
-	"    /**",
-	"     * Caption part IDs owned by this speech",
-	"     */",
-	"    caption_ids: string[];",
-	"  }[];",
-	"  /**",
-	"   * Materialized caption parts owned by the speeches",
-	"   */",
-	"  captions: {",
-	"    /**",
-	"     * The caption part ID (= side-effect created_caption_parts[].id)",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    caption_id: string;",
-	"    /**",
-	"     * The owning speech part ID",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    speech_part_id: string;",
-	"    text: string;",
-	"    /**",
-	"     * Offset within the host speech (caption.abs = speech.abs + start_ms)",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    start_ms: number;",
-	"    /**",
-	"     * Duration in milliseconds (> 0)",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    duration_ms: number;",
-	"  }[];",
+//#region src/migration-input.ts
+/** Validate host-recalled facts without accepting a caller-controlled snapshot or VV. */
+function parseMigrationAssetFacts(value) {
+	if (!Array.isArray(value)) throw new Error("asset_facts is required for migrate-legacy and must be an array");
+	return value.map((item) => {
+		if (!record(item)) throw new Error("Each asset_facts entry must be an object");
+		const { assetId, kind, durationMs, storageKey, voice } = item;
+		if (!nonempty(assetId)) throw new Error("asset_facts.assetId must be a non-empty trimmed string");
+		if (kind !== "image" && kind !== "video" && kind !== "audio" && kind !== "voice") throw new Error("asset_facts.kind must be image, video, audio, or voice");
+		if (Object.keys(item).some((key) => ![
+			"assetId",
+			"kind",
+			"durationMs",
+			"storageKey",
+			"voice"
+		].includes(key))) throw new Error("Unknown asset_facts field");
+		if (storageKey !== void 0 && !nonempty(storageKey)) throw new Error("asset_facts.storageKey must be non-empty");
+		if (kind === "image") {
+			if (durationMs !== void 0 || voice !== void 0) throw new Error("Image facts cannot declare duration or voice");
+			return {
+				assetId,
+				kind,
+				...storageKey === void 0 ? {} : { storageKey }
+			};
+		}
+		if (typeof durationMs !== "number" || !Number.isSafeInteger(durationMs) || durationMs <= 0) throw new Error("asset_facts.durationMs must be factual positive whole milliseconds");
+		if (kind === "video") {
+			if (voice !== void 0) throw new Error("Video facts cannot declare voice");
+			return {
+				assetId,
+				kind,
+				durationMs,
+				...storageKey === void 0 ? {} : { storageKey }
+			};
+		}
+		if (!nonempty(storageKey)) throw new Error("Audio and Voice facts require their physical storageKey");
+		if (kind === "audio") {
+			if (voice !== void 0) throw new Error("Audio facts cannot declare a Voice descriptor");
+			return {
+				assetId,
+				kind,
+				durationMs,
+				storageKey
+			};
+		}
+		if (!record(voice) || voice.system !== "voice-library" || !nonempty(voice.key) || voice.name !== void 0 && typeof voice.name !== "string" || Object.keys(voice).some((key) => ![
+			"system",
+			"key",
+			"name"
+		].includes(key))) throw new Error("Voice facts require an explicit voice-library descriptor");
+		return {
+			assetId,
+			kind,
+			durationMs,
+			storageKey,
+			voice: {
+				system: "voice-library",
+				key: voice.key,
+				...voice.name === void 0 ? {} : { name: voice.name }
+			}
+		};
+	});
+}
+function record(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonempty(value) {
+	return typeof value === "string" && value.length > 0 && value.trim() === value;
+}
+//#endregion
+//#region src/sandbox/generated/entity-edit-sandbox-model-context.ts
+/** @generated by gen:sandbox-dts. DO NOT EDIT. */
+const ENTITY_EDIT_SANDBOX_API_DTS = [
+	"/** @generated by gen:sandbox-dts. Entity-native editor contract; DO NOT EDIT. */",
+	"export interface AudioMediaAssetFact {",
+	"  readonly assetId: string;",
+	"  readonly kind: 'audio';",
+	"  readonly durationMs: number;",
+	"  readonly storageKey: string;",
 	"}",
-	"",
-	"export interface MoveVideoClipsInput {",
-	"  /**",
-	"   * List of video clips to move to new positions",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  clips: {",
-	"    /**",
-	"     * The video clip part ID to move",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    clip_id: string;",
-	"    /**",
-	"     * New absolute start time in milliseconds on the timeline",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    new_start_ms: number;",
-	"    /**",
-	"     * Target track ID to move the clip to (optional)",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    new_track_id?: string;",
-	"  }[];",
+	"export interface BoundedDerivedSequencePayload extends JsonObject {",
+	"  extent: {",
+	"    kind: 'bounded';",
+	"    start: number;",
+	"    end: number;",
+	"  };",
+	"  sampling: 'derived';",
+	"  coordinateSpace: JsonValue;",
 	"}",
-	"",
-	"/**",
-	" * Reorder a set of main-track clips relative to a reference clip.",
-	" */",
-	"export interface MoveVideoClipsByAnchorInput {",
-	"  /**",
-	"   * Clips to move as one block, keeping their relative order. Need not be contiguous on the track.",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  clip_ids: string[];",
-	"  /**",
-	"   * Where the moved block lands: before/after a reference clip, or at the head of the track",
-	"   */",
-	"  anchor:",
-	"    | {",
-	"        position: 'before';",
-	"        /**",
-	"         * The moved block lands immediately before this clip",
-	"         * @constraint minLength(1)",
-	"         */",
-	"        clip_id: string;",
-	"      }",
-	"    | {",
-	"        position: 'after';",
-	"        /**",
-	"         * The moved block lands immediately after this clip",
-	"         * @constraint minLength(1)",
-	"         */",
-	"        clip_id: string;",
-	"      }",
-	"    | { position: 'track_start' };",
-	"  /**",
-	"   * What happens to speeches anchored to the moved clips (required — see the policy doc)",
-	"   */",
-	"  on_anchored: 'follow' | 'keep_absolute';",
+	"export interface BoundedNativeSequencePayload extends JsonObject {",
+	"  /** Factual coordinates from recalled media metadata; never invent an end/duration. */",
+	"  extent: {",
+	"    kind: 'bounded';",
+	"    start: number;",
+	"    end: number;",
+	"  };",
+	"  sampling: 'native';",
+	"  coordinateSpace: JsonValue;",
 	"}",
-	"",
-	"export interface DeleteVideoClipsInput {",
-	"  /**",
-	"   * List of video clip part IDs to delete from the main track",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  clip_ids: string[];",
-	"  /**",
-	"   * How to treat anchored children (default cascade)",
-	"   */",
-	"  on_anchored?: 'cascade' | 'detach';",
+	"export interface CaptionFontDescriptor {",
+	"  readonly system: 'font-library';",
+	"  readonly key: string;",
 	"}",
-	"",
-	"/**",
-	" * Add video clips to a track.",
-	" */",
-	"export interface AddVideoClipsInput {",
-	"  /**",
-	"   * List of video clips to create",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  clips: {",
-	"    /**",
-	"     * The media asset ID for the video clip",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    media_id: string;",
-	"    /**",
-	"     * Absolute start time in milliseconds on the timeline",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    start_ms?: number;",
-	"    /**",
-	"     * The source media's intrinsic full length in ms",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    media_duration_ms: number;",
-	"    /**",
-	"     * Trim window start in the media (default 0)",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    play_in?: number;",
-	"    /**",
-	"     * Trim window end in the media (default media_duration_ms)",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    play_out?: number;",
-	"    /**",
-	"     * Target track ID (optional, defaults to main track)",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    track_id?: string;",
-	"  }[];",
-	"  /**",
-	"   * Insert new clips before this clip ID",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  before_clip_id?: string;",
-	"  /**",
-	"   * Insert new clips after this clip ID",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  after_clip_id?: string;",
+	"export interface CaptionStyleFields {",
+	"  readonly font?: CaptionFontDescriptor;",
+	"  readonly fontSize?: number;",
+	"  readonly fontColor?: string;",
+	"  readonly fontWeight?: number;",
+	"  readonly entranceAnimation?: string;",
+	"  readonly entranceAnimationDurationMs?: number;",
+	"  readonly strokeColor?: string;",
+	"  readonly strokeWidth?: number;",
+	"  readonly positionX?: number;",
+	"  readonly positionY?: number;",
 	"}",
-	"",
-	"export interface AdjustVideoClipVolumeInput {",
-	"  /**",
-	"   * List of video clips with their new volume settings",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  clips: {",
-	"    /**",
-	"     * The video clip part ID to adjust volume for",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    clip_id: string;",
-	"    /**",
-	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original)",
-	"     * @constraint min(-60)",
-	"     * @constraint max(20)",
-	"     */",
-	"    volume: number;",
-	"  }[];",
+	"export type ClipEntityId = EntityId;",
+	"export type ClipPlacement =",
+	"  | {",
+	"      readonly kind: 'sequential';",
+	"      readonly order: number;",
+	"    }",
+	"  | {",
+	"      readonly kind: 'absolute';",
+	"      readonly targetRange: SequenceRange<number>;",
+	"    }",
+	"  | {",
+	"      readonly kind: 'anchored';",
+	"      readonly hostClipEntityId: string;",
+	"      readonly anchorOffset: number;",
+	"    };",
+	"export type CreateEntityInput = {",
+	"  [K in KnownEntityKind]: {",
+	"    entity_id?: string;",
+	"    entity_kind: K;",
+	"    payload: EntityPayloadByKind[K];",
+	"  };",
+	"}[KnownEntityKind];",
+	"export interface DeleteBgmInput {",
+	"  readonly timelineEntityId: string;",
 	"}",
-	"",
-	"/**",
-	" * Set the playback speed of existing video clips.",
-	" */",
-	"export interface SetVideoClipSpeedShiftInput {",
-	"  /**",
-	"   * Video clips with their new speed settings",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  clips: {",
-	"    /**",
-	"     * The video clip part ID to set speed for",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    clip_id: string;",
-	"    /**",
-	"     * The new speed setting, or null to reset to 1×",
-	"     */",
-	"    speed_shift: {",
-	"      category: 'linear' | 'curve';",
-	"      mode: string;",
-	"      config:",
-	"        | {",
-	"            linear: {",
-	"              /**",
-	"               * @constraint positive",
-	"               */",
-	"              speed: number;",
-	"            };",
-	"          }",
-	"        | {",
-	"            curve: {",
-	"              /**",
-	"               * @constraint minLength(2)",
-	"               */",
-	"              keyframes: {",
-	"                /**",
-	"                 * @constraint min(0)",
-	"                 * @constraint max(1)",
-	"                 */",
-	"                position: number;",
-	"                /**",
-	"                 * @constraint min(0)",
-	"                 */",
-	"                rate: number;",
-	"                /**",
-	"                 * Bezier tangent handle (x, y)",
-	"                 */",
-	"                in_tangent?: { x: number; y: number };",
-	"                /**",
-	"                 * Bezier tangent handle (x, y)",
-	"                 */",
-	"                out_tangent?: { x: number; y: number };",
-	"              }[];",
-	"            };",
-	"          };",
-	"    } | null;",
-	"  }[];",
+	"export interface DeleteClipInput {",
+	"  readonly clipEntityId: string;",
 	"}",
-	"",
-	"/**",
-	" * Replace the media backing existing video clips.",
-	" */",
-	"export interface ReplaceVideoClipContentInput {",
-	"  /**",
-	"   * Video clips whose media is being replaced",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  clips: {",
-	"    /**",
-	"     * Existing video clip part ID to re-point",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    clip_id: string;",
-	"    /**",
-	"     * The new media asset ID",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    origin_media_id: string;",
-	"    /**",
-	"     * The new media's intrinsic full length",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    media_duration_ms: number;",
-	"    /**",
-	"     * Trim window start in the new media (usually 0)",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    play_in: number;",
-	"    /**",
-	"     * Trim window end in the new media (usually = media_duration_ms)",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    play_out: number;",
-	"    /**",
-	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)",
-	"     * @constraint min(-60)",
-	"     * @constraint max(20)",
-	"     */",
-	"    volume: number;",
-	"  }[];",
+	"export interface DeleteClipTreeInput {",
+	"  readonly clipEntityIds: readonly string[];",
+	"  readonly onAnchored: 'cascade' | 'detach';",
 	"}",
-	"",
-	"/**",
-	" * Replace a contiguous run of main-track clips with a new run.",
-	" */",
-	"export interface ReplaceVideoClipSequenceInput {",
-	"  /**",
-	"   * The clips being replaced: a contiguous main-track run, listed in timeline order",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  old_clip_ids: string[];",
-	"  /**",
-	"   * The replacement clips, in the order they take on the track",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  new_clips: {",
-	"    /**",
-	"     * The replacement media asset ID. Omit to create an empty placeholder clip.",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    media_id?: string;",
-	"    /**",
-	"     * The source media's intrinsic full length in ms",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    media_duration_ms: number;",
-	"    /**",
-	"     * Trim window start in the media (default 0)",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    play_in?: number;",
-	"    /**",
-	"     * Trim window end in the media (default media_duration_ms)",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    play_out?: number;",
-	"  }[];",
-	"  /**",
-	"   * What happens to speeches anchored to the replaced clips (required — see the policy doc)",
-	"   */",
-	"  on_anchored: 'remap' | 'cascade';",
+	"export interface DeleteEntityInput {",
+	"  entity_id: string;",
 	"}",
-	"",
-	"/**",
-	" * Re-trim existing video clips (the user-facing \"adjust duration\" gesture is a trim of the source window).",
-	" */",
-	"export interface AdjustVideoClipDurationInput {",
-	"  /**",
-	"   * Video clips with their new trim windows",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  clips: {",
-	"    /**",
-	"     * The video clip part ID to re-trim",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    clip_id: string;",
-	"    /**",
-	"     * New trim window start in the source media",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    play_in: number;",
-	"    /**",
-	"     * New trim window end in the source media",
-	"     * @constraint int",
-	"     * @constraint positive",
-	"     */",
-	"    play_out: number;",
-	"  }[];",
+	"export interface DeleteVoiceoverInput {",
+	"  readonly voiceoverClipEntityIds: readonly string[];",
 	"}",
-	"",
-	"/**",
-	" * Add speeches (and their captions).",
-	" */",
-	"export interface AddSpeechesInput extends SpeechAssets {}",
-	"",
-	"/**",
-	" * Delete speeches with their captions.",
-	" */",
-	"export interface DeleteSpeechesInput {",
-	"  /**",
-	"   * Speech part IDs to delete (their captions cascade-delete)",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  speech_ids: string[];",
+	"export type EmptyRelationKind =",
+	"  | 'timeline-track'",
+	"  | 'track-clip'",
+	"  | 'clip-marker'",
+	"  | 'marker-content'",
+	"  | 'axvideo-marker'",
+	"  | 'marker-timeline';",
+	"export interface EntityFacade {",
+	"  list(): SandboxEntity[];",
+	"  get(entityId: string): SandboxEntity | null;",
+	"  /** Return every explicitly imported Asset entity for a Memota asset id. */",
+	"  findByAssetId(assetId: string): SandboxEntity<'asset'>[];",
+	"  create(input: CreateEntityInput): string;",
+	"  /** Replace one Entity's owned payload without changing its identity or kind. */",
+	"  update(input: UpdateEntityInput): void;",
+	"  /** Delete an Entity only after all of its incident Relations have been explicitly unlinked. */",
+	"  delete(input: DeleteEntityInput): void;",
+	"  /** Import one physical asset without implying a one-to-one media Entity mapping. */",
+	"  importAsset(input: ImportAssetInput): string;",
 	"}",
-	"",
-	"/**",
-	" * Move speeches in time.",
-	" */",
-	"export interface MoveSpeechesInput {",
-	"  /**",
-	"   * Speeches to move to new positions",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  speeches: {",
-	"    /**",
-	"     * The speech part ID to move",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    speech_id: string;",
-	"    /**",
-	"     * New absolute start time on the timeline",
-	"     * @constraint int",
-	"     * @constraint min(0)",
-	"     */",
-	"    new_start_ms: number;",
-	"  }[];",
+	"export type EntityId = string;",
+	"export interface EntityPayloadByKind {",
+	"  axvideo: BoundedDerivedSequencePayload;",
+	"  timeline: JsonObject;",
+	"  track: JsonObject & {",
+	"    hidden?: boolean;",
+	"    role?: string;",
+	"  };",
+	"  clip: JsonObject;",
+	"  /** Asset-owned metadata. Peer media associations belong in physical-asset Relations. */",
+	"  asset: JsonObject;",
+	"  video: BoundedNativeSequencePayload;",
+	"  audio: BoundedNativeSequencePayload;",
+	"  voice: BoundedNativeSequencePayload;",
+	"  image: UnboundedConstantSequencePayload;",
+	"  'sequence-marker': JsonObject & {",
+	"    sourceRange: {",
+	"      start: number;",
+	"      end: number;",
+	"    };",
+	"    targetRange?: {",
+	"      start: number;",
+	"      end: number;",
+	"    };",
+	"    duration:",
+	"      | {",
+	"          mode: 'from-source';",
+	"        }",
+	"      | {",
+	"          mode: 'fixed';",
+	"          value: number;",
+	"        };",
+	"    timeRemapping?: JsonValue;",
+	"    anchorOffset?: number;",
+	"    durationPolicy?: 'timeline';",
+	"  };",
+	"  viewport: JsonObject;",
+	"  'audio-script': JsonObject & {",
+	"    segments: ScriptTextSegment[];",
+	"  };",
+	"  'phonetic-script': JsonObject & {",
+	"    segments: ScriptTextSegment[];",
+	"  };",
+	"  caption: BoundedNativeSequencePayload;",
 	"}",
-	"",
-	"/**",
-	" * Change a speech's script or voice.",
-	" */",
-	"export interface ChangeSpeechScriptInput extends SpeechAssets {}",
-	"",
-	"export interface ChangeSpeechVoiceInput extends SpeechAssets {}",
-	"",
-	"export interface AdjustSpeechVolumeInput {",
-	"  /**",
-	"   * List of speeches with their new volume settings",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  speeches: {",
-	"    /**",
-	"     * The speech part ID to adjust volume for",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    speech_id: string;",
-	"    /**",
-	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original)",
-	"     * @constraint min(-60)",
-	"     * @constraint max(20)",
-	"     */",
-	"    volume: number;",
-	"  }[];",
+	"export interface EntityStoreSnapshot {",
+	"  revision: number;",
+	"  entities: SandboxEntity[];",
+	"  relations: SandboxRelation[];",
 	"}",
-	"",
-	"/**",
-	" * Toggle caption visibility (the caption track's `is_hidden` flag).",
-	" */",
-	"export interface SetCaptionVisibilityInput {",
-	"  /**",
-	"   * Whether the caption track is hidden",
-	"   */",
-	"  is_hidden: boolean;",
+	"export interface ImageMediaAssetFact {",
+	"  readonly assetId: string;",
+	"  readonly kind: 'image';",
+	"  readonly storageKey?: string;",
 	"}",
-	"",
-	"/**",
-	" * Set the caption visual style.",
-	" */",
-	"export interface SetCaptionStyleInput {",
-	"  /**",
-	"   * Font ID referencing a font from the font library",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  font_id?: string;",
-	"  /**",
-	"   * Font size in points",
-	"   * @constraint positive",
-	"   */",
-	"  font_size?: number;",
-	"  /**",
-	"   * Font color as hex string, e.g. \"#FFFFFF\"",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  font_color?: string;",
-	"  /**",
-	"   * Numeric font weight, e.g. 400 or 700",
-	"   * @constraint int",
-	"   */",
-	"  font_weight?: number;",
-	"  /**",
-	"   * Entrance animation preset ID, e.g. \"fade\" or \"none\"",
-	"   */",
-	"  entrance_animation?: string;",
-	"  /**",
-	"   * Entrance animation duration in ms",
-	"   * @constraint min(0)",
-	"   */",
-	"  entrance_animation_duration_ms?: number;",
-	"  /**",
-	"   * Outline/stroke color as hex string, e.g. \"#000000\"",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  stroke_color?: string;",
-	"  /**",
-	"   * Outline/stroke width in pixels",
-	"   * @constraint min(0)",
-	"   */",
-	"  stroke_width?: number;",
-	"  /**",
-	"   * Caption center X as a fraction (0.0 to 1.0)",
-	"   */",
-	"  position_x?: number;",
-	"  /**",
-	"   * Caption center Y as a fraction (0.0 to 1.0)",
-	"   */",
-	"  position_y?: number;",
+	"export interface ImportAssetInput {",
+	"  asset_id: string;",
+	"  entity_id?: string;",
+	"  payload?: JsonObject;",
 	"}",
-	"",
-	"/**",
-	" * Set the document BGM.",
-	" */",
-	"export interface SetBgmInput {",
-	"  /**",
-	"   * The bgm part ID to write",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  bgm_id: string;",
-	"  /**",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  audio_storage_key: string;",
-	"  /**",
-	"   * The media asset ID",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  origin_media_id: string;",
-	"  /**",
-	"   * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)",
-	"   * @constraint min(-60)",
-	"   * @constraint max(20)",
-	"   */",
-	"  volume: number;",
+	"export interface InsertClipInput {",
+	"  readonly trackEntityId: string;",
+	"  /** Existing Sequence media Entity id. Asset ids and URLs are not content ids. */",
+	"  readonly contentEntityId: string;",
+	"  readonly sourceRange: SequenceRange<number>;",
+	"  readonly duration: SequenceDuration<number>;",
+	"  readonly targetRange?: SequenceRange<number>;",
+	"  readonly clipPayload?: JsonObject;",
 	"}",
-	"",
-	"/**",
-	" * Remove the document BGM.",
-	" */",
-	"export interface DeleteBgmInput {",
-	"  [key: string]: never;",
+	"export interface InsertMediaClipInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly clipEntityId?: string;",
+	"  readonly media: VisualMediaAssetFact;",
+	"  /** Source/display window in whole milliseconds. Images use this as their finite display span. */",
+	"  readonly sourceRange: SequenceRange<number>;",
+	"  readonly placement: ClipPlacement;",
+	"  readonly volume?: number;",
 	"}",
-	"",
-	"export interface AdjustBgmVolumeInput {",
-	"  /**",
-	"   * List of bgm parts with their new volume settings",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  bgm: {",
-	"    /**",
-	"     * The bgm part ID to adjust volume for",
-	"     * @constraint minLength(1)",
-	"     */",
-	"    bgm_id: string;",
-	"    /**",
-	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original)",
-	"     * @constraint min(-60)",
-	"     * @constraint max(20)",
-	"     */",
-	"    volume: number;",
-	"  }[];",
+	"export interface InsertMediaClipsInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly clips: readonly ReplacementMediaClipInput[];",
+	"  /** One placement decision for the whole input-ordered block. */",
+	"  readonly insertion: MediaClipInsertion;",
 	"}",
-	"",
-	"/** Agent write surface — one method per SemanticOp kind. */",
-	"export interface EditApi {",
-	"  moveVideoClips(input: MoveVideoClipsInput): Promise<void>;",
-	"  /** Reorder a set of main-track clips relative to a reference clip. */",
-	"  moveVideoClipsByAnchor(input: MoveVideoClipsByAnchorInput): Promise<void>;",
-	"  deleteVideoClips(input: DeleteVideoClipsInput): Promise<void>;",
-	"  /** Add video clips to a track. */",
-	"  addVideoClips(input: AddVideoClipsInput): Promise<void>;",
-	"  adjustVideoClipVolume(input: AdjustVideoClipVolumeInput): Promise<void>;",
-	"  /** Set the playback speed of existing video clips. */",
-	"  setVideoClipSpeedShift(input: SetVideoClipSpeedShiftInput): Promise<void>;",
-	"  /** Replace the media backing existing video clips. */",
-	"  replaceVideoClipContent(input: ReplaceVideoClipContentInput): Promise<void>;",
-	"  /** Replace a contiguous run of main-track clips with a new run. */",
-	"  replaceVideoClipSequence(input: ReplaceVideoClipSequenceInput): Promise<void>;",
-	"  /** Re-trim existing video clips (the user-facing \"adjust duration\" gesture is a trim of the source window). */",
-	"  adjustVideoClipDuration(input: AdjustVideoClipDurationInput): Promise<void>;",
-	"  /** Add speeches (and their captions). */",
-	"  addSpeeches(input: AddSpeechesInput): Promise<void>;",
-	"  /** Delete speeches with their captions. */",
-	"  deleteSpeeches(input: DeleteSpeechesInput): Promise<void>;",
-	"  /** Move speeches in time. */",
-	"  moveSpeeches(input: MoveSpeechesInput): Promise<void>;",
-	"  /** Change a speech's script or voice. */",
-	"  changeSpeechScript(input: ChangeSpeechScriptInput): Promise<void>;",
-	"  changeSpeechVoice(input: ChangeSpeechVoiceInput): Promise<void>;",
-	"  adjustSpeechVolume(input: AdjustSpeechVolumeInput): Promise<void>;",
-	"  /** Toggle caption visibility (the caption track's `is_hidden` flag). */",
-	"  setCaptionVisibility(input: SetCaptionVisibilityInput): Promise<void>;",
-	"  /** Set the caption visual style. */",
-	"  setCaptionStyle(input: SetCaptionStyleInput): Promise<void>;",
-	"  /** Set the document BGM. */",
-	"  setBgm(input: SetBgmInput): Promise<void>;",
-	"  /** Remove the document BGM. */",
-	"  deleteBgm(input: DeleteBgmInput): Promise<void>;",
-	"  adjustBgmVolume(input: AdjustBgmVolumeInput): Promise<void>;",
+	"export interface InsertPlacedClipInput {",
+	"  readonly trackEntityId: string;",
+	"  readonly contentEntityId: string;",
+	"  readonly sourceRange: SequenceRange<number>;",
+	"  readonly duration: SequenceDuration<number>;",
+	"  readonly placement: ClipPlacement;",
+	"  readonly clipPayload?: JsonObject;",
+	"  /** Stable caller-owned placement identity, when one already exists outside the graph. */",
+	"  readonly clipEntityId?: string;",
 	"}",
-	"",
-	"export type JsonPrimitive = string | number | boolean | null;",
-	"export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];",
 	"export interface JsonObject {",
 	"  [key: string]: JsonValue;",
 	"}",
-	"",
+	"export type JsonPrimitive = string | number | boolean | null;",
+	"export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];",
 	"export type KnownEntityKind =",
 	"  | 'axvideo'",
 	"  | 'timeline'",
@@ -1065,7 +614,6 @@ const EDIT_SANDBOX_API_DTS = [
 	"  | 'audio-script'",
 	"  | 'phonetic-script'",
 	"  | 'caption';",
-	"",
 	"export type KnownRelationKind =",
 	"  | 'timeline-track'",
 	"  | 'track-clip'",
@@ -1077,72 +625,146 @@ const EDIT_SANDBOX_API_DTS = [
 	"  | 'generated'",
 	"  | 'phonetic-script-provenance'",
 	"  | 'caption-provenance'",
-	"  | 'caption-alignment';",
-	"",
-	"export interface BoundedNativeSequencePayload extends JsonObject {",
-	"  /** Use factual recalled coordinates; never invent an end or duration. */",
-	"  extent: { kind: 'bounded'; start: number; end: number };",
-	"  sampling: 'native';",
-	"  coordinateSpace: JsonValue;",
+	"  | 'caption-alignment'",
+	"  | 'clip-anchor'",
+	"  | 'audio-script-render';",
+	"export interface LinearClipSpeed {",
+	"  readonly kind: 'linear';",
+	"  readonly rate: number;",
+	"  readonly mode?: string;",
 	"}",
-	"export interface UnboundedConstantSequencePayload extends JsonObject {",
-	"  extent: { kind: 'unbounded'; start: number };",
-	"  sampling: 'constant';",
-	"  coordinateSpace: JsonValue;",
+	"export interface LinkAudioScriptRenderRelationInput {",
+	"  relation_id?: string;",
+	"  output_entity_id: string;",
+	"  script_entity_id: string;",
+	"  trace?: JsonObject;",
 	"}",
-	"export interface BoundedDerivedSequencePayload extends JsonObject {",
-	"  extent: { kind: 'bounded'; start: number; end: number };",
-	"  sampling: 'derived';",
-	"  coordinateSpace: JsonValue;",
+	"export interface LinkClipAnchorRelationInput {",
+	"  relation_id?: string;",
+	"  child_clip_entity_id: string;",
+	"  host_clip_entity_id: string;",
+	"  trace?: JsonObject;",
 	"}",
-	"export type ScriptTextSegment = JsonObject & {",
-	"  segmentId: string;",
-	"  text: string;",
-	"  language?: string;",
-	"};",
-	"",
-	"export interface EntityPayloadByKind {",
-	"  axvideo: BoundedDerivedSequencePayload;",
-	"  timeline: JsonObject;",
-	"  track: JsonObject & { hidden?: boolean; role?: string };",
-	"  clip: JsonObject;",
-	"  asset: JsonObject;",
-	"  video: BoundedNativeSequencePayload;",
-	"  audio: BoundedNativeSequencePayload;",
-	"  voice: BoundedNativeSequencePayload;",
-	"  image: UnboundedConstantSequencePayload;",
-	"  'sequence-marker': JsonObject & {",
-	"    sourceRange: { start: number; end: number };",
-	"    targetRange?: { start: number; end: number };",
-	"    duration: { mode: 'from-source' } | { mode: 'fixed'; value: number };",
-	"    timeRemapping?: JsonValue;",
-	"  };",
-	"  viewport: JsonObject;",
-	"  'audio-script': JsonObject & { segments: ScriptTextSegment[] };",
-	"  'phonetic-script': JsonObject & { segments: ScriptTextSegment[] };",
-	"  caption: BoundedNativeSequencePayload;",
+	"export interface LinkGeneratedRelationInput {",
+	"  relation_id?: string;",
+	"  output_entity_id: string;",
+	"  input_entity_id: string;",
+	"  trace?: JsonObject;",
 	"}",
-	"",
-	"export type CreateEntityInput = {",
-	"  [K in KnownEntityKind]: {",
-	"    entity_id?: string;",
-	"    entity_kind: K;",
-	"    payload: EntityPayloadByKind[K];",
-	"  };",
-	"}[KnownEntityKind];",
-	"",
-	"export interface ImportAssetInput {",
-	"  asset_id: string;",
-	"  entity_id?: string;",
-	"  payload?: JsonObject;",
+	"interface LinkRelationBase {",
+	"  relation_id?: string;",
+	"  endpoint_0_entity_id: string;",
+	"  endpoint_1_entity_id: string;",
+	"  trace?: JsonObject;",
+	"}",
+	"export type LinkRelationInput =",
+	"  | (LinkRelationBase & {",
+	"      relation_kind: EmptyRelationKind;",
+	"      metadata?: {",
+	"        [key: string]: never;",
+	"      };",
+	"    })",
+	"  | (LinkRelationBase & {",
+	"      relation_kind: 'physical-asset';",
+	"      metadata?: JsonObject;",
+	"    })",
+	"  | (LinkRelationBase & {",
+	"      relation_kind: 'phonetic-script-provenance' | 'caption-provenance';",
+	"      metadata: JsonObject & {",
+	"        segmentAlignment: JsonValue;",
+	"      };",
+	"    })",
+	"  | (LinkRelationBase & {",
+	"      relation_kind: 'caption-alignment';",
+	"      metadata: JsonObject & {",
+	"        alignment: JsonValue;",
+	"      };",
+	"    });",
+	"export type MediaClipInsertion =",
+	"  | {",
+	"      readonly kind: 'before';",
+	"      readonly clipEntityId: string;",
+	"    }",
+	"  | {",
+	"      readonly kind: 'after';",
+	"      readonly clipEntityId: string;",
+	"    }",
+	"  | {",
+	"      readonly kind: 'firstStart';",
+	"      readonly startMs: number;",
+	"    };",
+	"export interface MoveClipInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly trackEntityId: string;",
+	"}",
+	"export interface MoveClipsToStartsInput {",
+	"  readonly moves: readonly {",
+	"    readonly clipEntityId: string;",
+	"    readonly newStartMs: number;",
+	"  }[];",
+	"  /** Absolute-time drags preserve every voiceover's current visible landing. */",
+	"  readonly onAnchored: 'keepAbsolute';",
+	"}",
+	"export interface MoveSequentialClipsInput {",
+	"  readonly clipEntityIds: readonly string[];",
+	"  readonly anchor: SequentialClipAnchor;",
+	"  readonly onAnchored: 'follow' | 'keepAbsolute';",
+	"}",
+	"export interface MoveVoiceoverInput {",
+	"  readonly voiceoverClipEntityId: string;",
+	"  /** Absolute requested timeline start; MEngine resolves and persists the host relation. */",
+	"  readonly newStartMs: number;",
+	"}",
+	"export interface PatchCaptionStyleInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly style: CaptionStyleFields;",
+	"}",
+	"export interface RelationFacade {",
+	"  list(): SandboxRelation[];",
+	"  /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */",
+	"  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];",
+	"  /** For physical-asset use sequence media as endpoint 0 and Asset as endpoint 1. */",
+	"  link(input: LinkRelationInput): string;",
+	"  /** Author ordered generated(output,input); generic link() deliberately rejects this kind. */",
+	"  linkGenerated(input: LinkGeneratedRelationInput): string;",
+	"  /** Author ordered clip-anchor(child,host) without positional endpoint ambiguity. */",
+	"  linkClipAnchor(input: LinkClipAnchorRelationInput): string;",
+	"  /** Author ordered audio-script-render(output,script) without positional endpoint ambiguity. */",
+	"  linkAudioScriptRender(input: LinkAudioScriptRenderRelationInput): string;",
+	"  /** Remove a Relation by identity; endpoint replacement is an explicit unlink plus link. */",
+	"  unlink(input: UnlinkRelationInput): void;",
+	"}",
+	"export interface ReplaceClipContentInput {",
+	"  readonly clipEntityId: string;",
+	"  /** Existing Sequence media Entity id. Asset ids and URLs are not content ids. */",
+	"  readonly contentEntityId: string;",
+	"  readonly sourceRange: SequenceRange<number>;",
+	"  readonly duration: SequenceDuration<number>;",
+	"  readonly targetRange?: SequenceRange<number>;",
+	"  readonly timeRemapping?: JsonValue;",
+	"}",
+	"export interface ReplaceMediaClipInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly media: VisualMediaAssetFact;",
+	"  readonly sourceRange: SequenceRange<number>;",
+	"}",
+	"export interface ReplaceSequentialClipsInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly oldClipEntityIds: readonly string[];",
+	"  readonly newClips: readonly ReplacementMediaClipInput[];",
+	"  readonly onAnchored: 'remap' | 'cascade';",
+	"}",
+	"export interface ReplacementMediaClipInput {",
+	"  readonly clipEntityId?: string;",
+	"  readonly media: VisualMediaAssetFact;",
+	"  readonly sourceRange: SequenceRange<number>;",
+	"  readonly volume?: number;",
 	"}",
-	"",
 	"export interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {",
 	"  entity_id: string;",
 	"  entity_kind: K;",
 	"  payload: EntityPayloadByKind[K];",
 	"}",
-	"",
 	"export interface SandboxRelation {",
 	"  relation_id: string;",
 	"  relation_kind: KnownRelationKind;",
@@ -1151,155 +773,201 @@ const EDIT_SANDBOX_API_DTS = [
 	"  metadata: JsonObject;",
 	"  trace: JsonObject;",
 	"}",
-	"",
-	"export type EmptyRelationKind =",
-	"  | 'timeline-track'",
-	"  | 'track-clip'",
-	"  | 'clip-marker'",
-	"  | 'marker-content'",
-	"  | 'axvideo-marker'",
-	"  | 'marker-timeline';",
-	"export type LinkRelationInput =",
+	"export type ScriptTextSegment = JsonObject & {",
+	"  segmentId: string;",
+	"  text: string;",
+	"  language?: string;",
+	"};",
+	"export type SequenceDuration<Span = unknown> =",
 	"  | {",
-	"      relation_id?: string;",
-	"      relation_kind: EmptyRelationKind;",
-	"      endpoint_0_entity_id: string;",
-	"      endpoint_1_entity_id: string;",
-	"      metadata?: { [key: string]: never };",
-	"      trace?: JsonObject;",
+	"      readonly mode: 'from-source';",
 	"    }",
 	"  | {",
-	"      relation_id?: string;",
-	"      relation_kind: 'physical-asset';",
-	"      /** Canonical endpoint 0 is sequence media; endpoint 1 is Asset. */",
-	"      endpoint_0_entity_id: string;",
-	"      endpoint_1_entity_id: string;",
-	"      metadata?: JsonObject;",
-	"      trace?: JsonObject;",
-	"    }",
+	"      readonly mode: 'fixed';",
+	"      readonly value: Span;",
+	"    };",
+	"export interface SequenceRange<Point = unknown> {",
+	"  readonly start: Point;",
+	"  readonly end: Point;",
+	"}",
+	"export type SequentialClipAnchor =",
 	"  | {",
-	"      relation_id?: string;",
-	"      relation_kind: 'phonetic-script-provenance' | 'caption-provenance';",
-	"      endpoint_0_entity_id: string;",
-	"      endpoint_1_entity_id: string;",
-	"      metadata: JsonObject & { segmentAlignment: JsonValue };",
-	"      trace?: JsonObject;",
+	"      readonly position: 'before' | 'after';",
+	"      readonly clipEntityId: string;",
 	"    }",
 	"  | {",
-	"      relation_id?: string;",
-	"      relation_kind: 'caption-alignment';",
-	"      endpoint_0_entity_id: string;",
-	"      endpoint_1_entity_id: string;",
-	"      metadata: JsonObject & { alignment: JsonValue };",
-	"      trace?: JsonObject;",
+	"      readonly position: 'trackStart';",
 	"    };",
-	"",
-	"export interface LinkGeneratedRelationInput {",
-	"  relation_id?: string;",
-	"  /** Generated output media Entity; persisted as endpoint 0. */",
-	"  output_entity_id: string;",
-	"  /** Input media Entity used to generate the output; persisted as endpoint 1. */",
-	"  input_entity_id: string;",
-	"  trace?: JsonObject;",
+	"export interface SetBgmInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly bgmClipEntityId: string;",
+	"  readonly media: AudioMediaAssetFact;",
+	"  readonly volume: number;",
 	"}",
-	"",
-	"/** Explicit Entity authoring. Assets and media Entities are not one-to-one. */",
-	"export interface EntityApi {",
-	"  list(): SandboxEntity[];",
-	"  get(entityId: string): SandboxEntity | null;",
-	"  /** Call before importAsset; inspect every match and decide whether to reuse one. */",
-	"  findByAssetId(assetId: string): SandboxEntity<'asset'>[];",
-	"  create(input: CreateEntityInput): string;",
-	"  /** Create only an Asset Entity when no existing match should be reused; this does not infer media. */",
-	"  importAsset(input: ImportAssetInput): string;",
+	"export interface SetCaptionVisibilityInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly hidden: boolean;",
 	"}",
-	"",
-	"/** Incident reads ignore endpoint position; relation semantics preserve it. */",
-	"export interface RelationApi {",
-	"  list(): SandboxRelation[];",
-	"  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];",
-	"  link(input: LinkRelationInput): string;",
-	"  /** Author ordered generated(output,input). */",
-	"  linkGenerated(input: LinkGeneratedRelationInput): string;",
+	"export interface SetClipPlacementInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly placement: ClipPlacement;",
 	"}",
-	"",
-	"/** Clip hit from `clipsInRange`. */",
-	"export interface TimelineClipDescriptor {",
-	"  id: string;",
-	"  start_ms: number;",
-	"  end_ms: number;",
-	"  duration_ms: number;",
-	"  speed_shift: unknown;",
-	"  volume: number | undefined;",
-	"  media_id: string | undefined;",
+	"export interface SetClipSpeedInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly timeRemapping: LinearClipSpeed | null;",
 	"}",
-	"",
-	"/** Part descriptor from `part(id)`. */",
-	"export interface TimelinePartDescriptor {",
-	"  id: string;",
-	"  kind: string;",
-	"  lane: string;",
-	"  start_ms: number;",
-	"  end_ms: number;",
-	"  duration_ms: number;",
-	"  part: unknown;",
+	"export interface SetClipVolumeInput {",
+	"  readonly clipEntityId: string;",
+	"  /** Playback gain in decibels. */",
+	"  readonly volume: number;",
+	"}",
+	"export interface TrimClipInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly sourceRange: SequenceRange<number>;",
+	"}",
+	"export interface UnboundedConstantSequencePayload extends JsonObject {",
+	"  extent: {",
+	"    kind: 'unbounded';",
+	"    start: number;",
+	"  };",
+	"  sampling: 'constant';",
+	"  coordinateSpace: JsonValue;",
+	"}",
+	"export interface UnlinkRelationInput {",
+	"  relation_id: string;",
+	"}",
+	"export interface UpdateClipInput {",
+	"  readonly clipEntityId: string;",
+	"  /** Complete replacement for the Clip-owned payload. */",
+	"  readonly payload: JsonObject;",
+	"}",
+	"export interface UpdateClipMarkerInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly sourceRange?: SequenceRange<number>;",
+	"  /** Passing `undefined` explicitly removes the optional target range. */",
+	"  readonly targetRange?: SequenceRange<number> | undefined;",
+	"  readonly duration?: SequenceDuration<number>;",
+	"  /** Passing `undefined` explicitly removes the optional remapping value. */",
+	"  readonly timeRemapping?: JsonValue | undefined;",
+	"}",
+	"export interface UpdateEntityInput {",
+	"  entity_id: string;",
+	"  payload: JsonObject;",
+	"}",
+	"export interface VideoMediaAssetFact {",
+	"  readonly assetId: string;",
+	"  readonly kind: 'video';",
+	"  readonly durationMs: number;",
+	"  readonly storageKey?: string;",
+	"}",
+	"export type VisualMediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact;",
+	"export interface VoiceDescriptor {",
+	"  readonly system: 'voice-library';",
+	"  readonly key: string;",
+	"  readonly name?: string;",
+	"}",
+	"export interface VoiceMediaAssetFact {",
+	"  /** Stable external speech result id, independent of the placed Clip id. */",
+	"  readonly assetId: string;",
+	"  readonly kind: 'voice';",
+	"  readonly durationMs: number;",
+	"  readonly storageKey: string;",
+	"  readonly voice: VoiceDescriptor;",
+	"}",
+	"export interface VoiceoverCaptionFact {",
+	"  /** Stable placed caption identity supplied by the materialized side effect. */",
+	"  readonly captionClipEntityId: string;",
+	"  readonly text: string;",
+	"  readonly startMs: number;",
+	"  readonly durationMs: number;",
+	"  readonly style?: CaptionStyleFields;",
+	"}",
+	"export interface VoiceoverTakeInput {",
+	"  readonly timelineEntityId: string;",
+	"  /** Stable placed speech identity, distinct from media.assetId. */",
+	"  readonly voiceoverClipEntityId: string;",
+	"  readonly hostClipEntityId: string;",
+	"  readonly anchorOffset: number;",
+	"  readonly media: VoiceMediaAssetFact;",
+	"  /** Complete spoken text; the editor owns the deterministic local script segment identity. */",
+	"  readonly scriptText: string;",
+	"  readonly volume: number;",
+	"  readonly captions: readonly VoiceoverCaptionFact[];",
+	"}",
+	"export interface VoiceoverTakeResult {",
+	"  readonly voiceoverClipEntityId: string;",
+	"  readonly voiceEntityId: string;",
+	"  readonly audioScriptEntityId: string;",
+	"  readonly captionClipEntityIds: readonly string[];",
+	"}",
+	"/** Timeline writes accept existing media Entity ids, never Memota asset ids or URLs. */",
+	"export interface EditApi {",
+	"  insertClip(input: InsertClipInput): ClipEntityId;",
+	"  insertPlacedClip(input: InsertPlacedClipInput): ClipEntityId;",
+	"  updateClipMarker(input: UpdateClipMarkerInput): void;",
+	"  setClipPlacement(input: SetClipPlacementInput): void;",
+	"  moveSequentialClips(input: MoveSequentialClipsInput): void;",
+	"  moveClip(input: MoveClipInput): void;",
+	"  replaceClipContent(input: ReplaceClipContentInput): void;",
+	"  insertMediaClip(input: InsertMediaClipInput): ClipEntityId;",
+	"  insertMediaClips(input: InsertMediaClipsInput): readonly ClipEntityId[];",
+	"  replaceMediaClip(input: ReplaceMediaClipInput): void;",
+	"  setClipVolume(input: SetClipVolumeInput): void;",
+	"  setClipSpeed(input: SetClipSpeedInput): void;",
+	"  trimClip(input: TrimClipInput): void;",
+	"  replaceSequentialClips(input: ReplaceSequentialClipsInput): readonly ClipEntityId[];",
+	"  deleteClip(input: DeleteClipInput): void;",
+	"  deleteClipTree(input: DeleteClipTreeInput): void;",
+	"  updateClip(input: UpdateClipInput): void;",
+	"  upsertVoiceoverTake(input: VoiceoverTakeInput): VoiceoverTakeResult;",
+	"  moveVoiceover(input: MoveVoiceoverInput): void;",
+	"  moveClipsToStarts(input: MoveClipsToStartsInput): void;",
+	"  deleteVoiceover(input: DeleteVoiceoverInput): void;",
+	"  setBgm(input: SetBgmInput): ClipEntityId;",
+	"  deleteBgm(input: DeleteBgmInput): void;",
+	"  setCaptionVisibility(input: SetCaptionVisibilityInput): void;",
+	"  patchCaptionStyle(input: PatchCaptionStyleInput): void;",
 	"}",
-	"",
-	"/** Opaque VideoDraft projection (full IDL lives in host document types). */",
-	"export type VideoDraftProjection = {",
-	"  readonly timeline?: { readonly duration_ms?: number };",
-	"  readonly [key: string]: unknown;",
-	"};",
-	"",
-	"/** Agent read surface over the forked document. */",
 	"export interface TimelineApi {",
-	"  /** Snapshot the current VideoDraft projection. */",
-	"  snapshot(): VideoDraftProjection;",
-	"  /** Clips whose midpoint falls in `[startMs, endMs)`. */",
-	"  clipsInRange(startMs: number, endMs: number): TimelineClipDescriptor[];",
-	"  /** Look up a part by id, or null if missing. */",
-	"  part(id: string): TimelinePartDescriptor | null;",
+	"  snapshot(): EntityStoreSnapshot;",
 	"}",
-	"",
-	"/** Opaque checkpoint handle for rollback. */",
 	"export interface SandboxCheckpoint {",
 	"  readonly index: number;",
 	"}",
-	"",
 	"export declare const edit: EditApi;",
 	"export declare const timeline: TimelineApi;",
-	"export declare const entities: EntityApi;",
-	"export declare const relations: RelationApi;",
-	"",
-	"/** Capture a rollback point. */",
+	"export declare const entities: EntityFacade;",
+	"export declare const relations: RelationFacade;",
 	"export declare function checkpoint(): SandboxCheckpoint;",
-	"/** Roll the sandbox document back to a prior checkpoint. */",
 	"export declare function rollbackTo(cp: SandboxCheckpoint): void;",
-	"/** Host-injected, pre-materialized facts. Validate each field before use. */",
 	"export declare const inputs: Readonly<Record<string, unknown>>;",
 	""
 ].join("\n");
 //#endregion
 //#region src/prompt.ts
 const MEDEO_TOOL_DESCRIPTION = `
-Edit a Medeo video document and its explicit Entity/Relation state through a deterministic, side-effect-free JavaScript sandbox.
+Edit the authoritative Medeo Entity/Relation graph through a deterministic, side-effect-free JavaScript sandbox. Timeline objects and edit targets are Entities, not Memota assets or legacy parts.
 
 Operations:
-- snapshot: return the compact timeline projection and opaque base version.
-- run-edit-script: execute JavaScript against forked timeline and Entity/Relation snapshots. Inspect timeline.*, entities.*, and relations.*; call edit.* for timeline mutations or the explicit entity APIs for domain mutations. The sandbox has no network, storage, clock, or generation access. Pass recalled generation/asset facts through inputs. A successful run returns preview, logs, plan_kind, base versions, and plan_id — not the full journals.
-- commit-plan: commit a cached plan_id. Timeline plans replay into ManualSyncDoc and push one causally complete update; Entity plans replace the authoritative row set through revision CAS. validation=preflight is timeline-only. A failed transport is unconfirmed, never committed; retry the same plan_id.
+- snapshot: return the Entity/Relation state summary and opaque base version.
+- migrate-legacy: explicitly migrate an existing legacy timeline using recalled asset_facts. MEngine reads the canonical document and version, verifies that editing facts are preserved, and commits migration alone. Then take a fresh snapshot before any edit; never pass a caller-created legacy snapshot or version.
+- run-edit-script: inspect timeline.snapshot(), entities.*, and relations.*; edit.* operates existing Entity ids and creates the required Clip/SequenceMarker structural graph. Asset import, media Entity creation, generated Relations and timeline edits belong in ONE plan. The sandbox has no network, storage or generation access. Pass recalled generation/asset facts through inputs. A successful run returns preview, logs, base revision and plan_id.
+- commit-plan: commit the complete Entity/Relation plan through revision CAS. The server derives the read-only timeline projection in the same transaction. There is no separate writable timeline plan and no preflight replay into a legacy editor. A failed transport is unconfirmed, never committed; retry the same plan_id.
 
 Default flow: snapshot → run-edit-script with auto_commit=false → inspect preview → commit-plan. Use auto_commit=true only for low-risk edits when the host does not need user confirmation. On version mismatch, rerun snapshot and the script; never try to patch a rejected journal by hand.
 
-One plan must mutate exactly one store: timeline or Entity/Relation state. If both are needed, author and commit two separate plans. There is no automatic Asset→Entity projection: select the relevant recalled fact, explicitly import an Asset if useful, explicitly create only known typed Entities, and author relations. Asset and media Entity identity are not one-to-one. relations.linkGenerated({ output_entity_id, input_entity_id }) means generated(output,input); incident lookup with relations.of(entityId) is endpoint-agnostic.
+Generating an Asset alone does not require an Entity. Using that resource in the editor DOES: recall the Asset facts, reuse or create the appropriate media Entity and physical-asset Relation, then pass the media Entity id to edit.insertClip. A raw asset id or URL is not valid contentEntityId. Asset and media Entity identity are not one-to-one. Recall generation history and author known generated(output,input) relations in the same plan; do not invent an input for text-only generation. relations.of(entityId) is endpoint-agnostic.
 `.trim();
 const MEDEO_TOOL_EXECUTION_RULES = `
 The host supplies the current document. Do not ask for, invent, or pass a document id.
-Use timeline.snapshot() for the whole draft projection. Its duration is timeline.snapshot().timeline?.duration_ms; there is no top-level duration_ms.
+timeline.snapshot() returns the Entity/Relation graph with its revision, not a legacy VideoDraft. Inspect Timeline, Track, Clip, SequenceMarker and their relations to plan edits.
 Generation lineage and Memota asset facts are host-provided through inputs. Never invent an asset id, Entity kind, or peer Entity id.
 Before importing an Asset, call entities.findByAssetId(assetId), inspect every match, and decide whether an existing Entity represents the intended logical asset. Multiple matches are valid; do not assume Asset↔media is one-to-one.
 For recalled video/audio/voice, create a bounded/native payload whose extent end comes from factual media duration/coordinates in inputs; never fabricate a duration. Image uses unbounded/constant semantics and has no invented end. If required facts are absent, do not create the media Entity yet.
 For physical-asset authoring, use sequence media as endpoint_0_entity_id and Asset as endpoint_1_entity_id. For generated lineage, use linkGenerated so endpoint 0 is output and endpoint 1 is input. relations.of remains endpoint-agnostic for lookup.
+The compatibility reader supports the existing four Track roles: video_clip (Image/Video), speech (Voice), caption (Caption), and bgm (Audio), one of each. Clip.volume is decibels (-60 to 20, 0 = original). Marker.sourceRange is the selected source interval; Marker.duration is effective display/playback duration. Coordinates and duration are whole milliseconds for this reader, not a global DSL restriction. Placement is exactly one of Clip.order, Marker.targetRange, or clip-anchor(child,host) plus Marker.anchorOffset. Use the native move/delete/voiceover helpers so placement and cascade decisions are in the same entity plan. Reading the graph never rebinds anchors or invents empty clips. Linear timeRemapping is {kind:'linear',rate:2,mode:'constant'} and agrees with rounded source span divided by rate. Image remains unbounded/constant; an explicit linear rate scales its display window, not an invented media extent. Nonlinear speed and multiple visual overlay tracks are unsupported.
+Voice links to AudioScript through audio-script-render(output,script). Caption owns text/style and is placed through a Clip anchored to the Voice Clip; caption alignment/provenance agree with that Voice/AudioScript. BGM Audio keeps factual source duration and its Marker declares durationPolicy:'timeline'. External Asset identity and storageKey are distinct from the placed Clip identity. Never introduce a speech entity kind.
+Create only the known entity kinds. On an empty document, explicitly create Timeline and Track(role='video_clip') and connect timeline-track before inserting a Clip. If snapshot reports legacy migration is required, recall the listed asset facts and call migrate-legacy first. Missing facts, unsupported layouts, and version conflicts fail closed; never fall back to an old timeline method or raw update endpoint.
 Use only the globals and methods declared by the following TypeScript interface. Values not declared here are unavailable.
 `.trim();
 /** Render the complete MEngine-owned context injected before one model call. */
@@ -1318,15 +986,51 @@ When updated_since_previous_model_call is true, the document changed after the p
 
 Sandbox TypeScript interface:
 \`\`\`ts
-${EDIT_SANDBOX_API_DTS}
+${ENTITY_EDIT_SANDBOX_API_DTS}
 \`\`\`
 `.trim();
 }
 //#endregion
 //#region src/schema.ts
 const MEDEO_TOOL_NAME = "medeo";
+const assetFactProperties = {
+	assetId: {
+		type: "string",
+		minLength: 1
+	},
+	kind: {
+		type: "string",
+		enum: [
+			"image",
+			"video",
+			"audio",
+			"voice"
+		]
+	},
+	durationMs: {
+		type: "integer",
+		minimum: 1
+	},
+	storageKey: {
+		type: "string",
+		minLength: 1
+	},
+	voice: {
+		type: "object",
+		additionalProperties: false,
+		required: ["system", "key"],
+		properties: {
+			system: { const: "voice-library" },
+			key: {
+				type: "string",
+				minLength: 1
+			},
+			name: { type: "string" }
+		}
+	}
+};
 /**
-* JSON Schema for the host-facing three-op `medeo` tool surface.
+* JSON Schema for the host-facing `medeo` tool surface.
 *
 * The schema intentionally does not return or accept the full op journal:
 * journals stay in the tool process and are referenced by `plan_id`. This keeps
@@ -1342,6 +1046,7 @@ const MEDEO_TOOL_PARAMETERS = {
 			type: "string",
 			enum: [
 				"snapshot",
+				"migrate-legacy",
 				"run-edit-script",
 				"commit-plan"
 			],
@@ -1355,12 +1060,74 @@ const MEDEO_TOOL_PARAMETERS = {
 		script: {
 			type: "string",
 			minLength: 1,
-			description: "JavaScript body for run-edit-script. It receives edit, timeline, entities, relations, checkpoint, rollbackTo, inputs, and console. A plan may mutate the timeline or Entity/Relation state, never both."
+			description: "JavaScript body for run-edit-script. Use edit, timeline, entities, relations, checkpoint, rollbackTo, inputs, and console. Asset import, media relations, and timeline entity edits share one entity plan."
 		},
 		inputs: {
 			type: "object",
 			description: "Pre-materialized, side-effect-free values passed into the script, including recalled generation lineage and asset facts. Generation and network IO must happen in the host before this call."
 		},
+		asset_facts: {
+			type: "array",
+			description: "Factual asset metadata recalled by the host for migrate-legacy only. The package reads the canonical legacy snapshot and version itself; never supply a clip trim window as media duration.",
+			items: { oneOf: [
+				{
+					type: "object",
+					additionalProperties: false,
+					required: ["assetId", "kind"],
+					properties: {
+						assetId: assetFactProperties.assetId,
+						kind: { const: "image" },
+						storageKey: assetFactProperties.storageKey
+					}
+				},
+				{
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"assetId",
+						"kind",
+						"durationMs"
+					],
+					properties: {
+						assetId: assetFactProperties.assetId,
+						kind: { const: "video" },
+						durationMs: assetFactProperties.durationMs,
+						storageKey: assetFactProperties.storageKey
+					}
+				},
+				{
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"assetId",
+						"kind",
+						"durationMs",
+						"storageKey"
+					],
+					properties: {
+						assetId: assetFactProperties.assetId,
+						kind: { const: "audio" },
+						durationMs: assetFactProperties.durationMs,
+						storageKey: assetFactProperties.storageKey
+					}
+				},
+				{
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"assetId",
+						"kind",
+						"durationMs",
+						"storageKey",
+						"voice"
+					],
+					properties: {
+						...assetFactProperties,
+						kind: { const: "voice" }
+					}
+				}
+			] }
+		},
 		timeout_ms: {
 			type: "integer",
 			minimum: 1,
@@ -1382,11 +1149,24 @@ const MEDEO_TOOL_PARAMETERS = {
 		},
 		validation: {
 			type: "string",
-			enum: ["version", "preflight"],
-			description: "Timeline commit mode: version rejects any concurrent change; preflight revalidates each op. Entity plans always use revision CAS and reject preflight."
+			enum: ["version"],
+			description: "Commit with Entity revision CAS; reject concurrent changes."
 		}
 	},
 	oneOf: [
+		{
+			required: [
+				"op",
+				"doc_id",
+				"asset_facts"
+			],
+			properties: {
+				op: { const: "migrate-legacy" },
+				doc_id: { $ref: "#/properties/doc_id" },
+				asset_facts: { $ref: "#/properties/asset_facts" }
+			},
+			additionalProperties: false
+		},
 		{
 			required: ["op", "doc_id"],
 			properties: {
@@ -1538,11 +1318,31 @@ function requiredContext(value, docId, field) {
 	if (resolved == null || resolved.length === 0) throw new Error(`${field} must resolve to a non-empty string for doc ${docId}`);
 	return resolved;
 }
+function renderEntitySnapshot(state) {
+	const rows = [...state.entities.map((entity) => JSON.stringify(entity)), ...state.relations.map((relation) => JSON.stringify(relation))];
+	const shown = rows.slice(0, 200);
+	return [
+		`Entity revision=${state.revision} entities=${state.entities.length} relations=${state.relations.length}`,
+		...shown,
+		...shown.length < rows.length ? ["[truncated; inspect entities/relations in the sandbox]"] : []
+	].join("\n");
+}
+function migrationNotice(document, state) {
+	if (state.entities.some((row) => row.entity_kind === "timeline") || Object.keys(document.part_library ?? {}).length === 0) return "";
+	const assetIds = new Set(Object.values(document.part_library ?? {}).flatMap((part) => {
+		const id = part.video_clip?.origin_media_id ?? part.bgm?.origin_media_id;
+		return typeof id === "string" && id !== "" ? [id] : [];
+	}));
+	return `\nLegacy timeline migration required. Recall factual media metadata for ${JSON.stringify([...assetIds])}, then call migrate-legacy with asset_facts. Speech facts are read from the canonical legacy document. Take a fresh snapshot after migration before editing.`;
+}
 async function commitEntityPlan(client, plan) {
 	const rows = plan.entity_rows;
 	if (rows === void 0) throw new Error("entity plan is missing its authoritative rows");
 	try {
-		const committed = await client.commit(plan.entity_base_revision, rows);
+		const committed = await client.commit(plan.entity_base_revision, rows, {
+			deleted_entity_ids: plan.deleted_entity_ids ?? [],
+			deleted_relation_ids: plan.deleted_relation_ids ?? []
+		});
 		return {
 			kind: "committed",
 			ops_applied: plan.entity_commands.length,
@@ -1551,7 +1351,7 @@ async function commitEntityPlan(client, plan) {
 		};
 	} catch (error) {
 		if (error instanceof MengineEntityHttpRequestError) {
-			if (error.status === 409) {
+			if (error.status === 409 && isRevisionConflictPayload(error.payload)) {
 				const actualFromPayload = revisionConflictActual(error.payload);
 				try {
 					const current = await client.fetchState();
@@ -1602,6 +1402,9 @@ function revisionConflictActual(payload) {
 	const actual = payload.actual_revision;
 	return typeof actual === "number" && Number.isSafeInteger(actual) && actual >= 0 ? actual : void 0;
 }
+function isRevisionConflictPayload(payload) {
+	return isRecord(payload) && payload.code === "revision_conflict";
+}
 function entityHttpErrorMessage(payload) {
 	if (isRecord(payload) && typeof payload.message === "string" && payload.message.length > 0) return payload.message;
 	return typeof payload === "string" && payload.length > 0 ? payload : "mengine rejected the entity-state plan";
@@ -1631,6 +1434,18 @@ function parseInput(value) {
 		op,
 		doc_id: docId
 	};
+	if (op === "migrate-legacy") {
+		if (Object.keys(value).some((key) => ![
+			"op",
+			"doc_id",
+			"asset_facts"
+		].includes(key))) throw new Error("migrate-legacy accepts asset_facts only; the package reads the canonical document and version");
+		return {
+			op,
+			doc_id: docId,
+			asset_facts: parseMigrationAssetFacts(value.asset_facts)
+		};
+	}
 	if (op === "run-edit-script") {
 		if (typeof value.script !== "string" || value.script.length === 0) throw new Error("script must be a non-empty string");
 		if (value.inputs !== void 0 && !isRecord(value.inputs)) throw new Error("inputs must be an object");
@@ -1791,20 +1606,11 @@ function createMedeoTool(options) {
 		if (plan.plan_kind === "timeline" && result.kind === "rejected" && result.reason === "push_rejected") documents.delete(docId);
 	}
 	async function fetchEntityStateForSandbox(docId) {
-		try {
-			return await getEntityClient(docId).fetchState();
-		} catch (error) {
-			if (error instanceof MengineEntityHttpRequestError && error.status === 404) return {
-				revision: 0,
-				entities: [],
-				relations: []
-			};
-			throw error;
-		}
+		return await getEntityClient(docId).fetchState();
 	}
-	async function commitCachedPlan(docId, doc, plan, validation) {
-		if (plan.plan_kind === "timeline") return await commitPlan(doc, plan, validation === void 0 ? void 0 : { validation });
-		if (validation === "preflight") throw new Error("validation=preflight applies only to timeline plans; entity plans use revision CAS");
+	async function commitCachedPlan(docId, _doc, plan, validation) {
+		if (plan.plan_kind === "timeline") throw new Error("Legacy timeline plans are not editable; use an Entity/Relation plan");
+		if (validation === "preflight") throw new Error("Entity plans use revision CAS; validation=preflight is not supported");
 		if (plan.entity_rows === void 0) throw new Error("entity plan is missing its authoritative rows");
 		return await commitEntityPlan(getEntityClient(docId), plan);
 	}
@@ -1829,8 +1635,8 @@ function createMedeoTool(options) {
 		if (docId.length === 0) throw new Error("doc_id must be a non-empty string");
 		if (contextId.length === 0) throw new Error("context_id must be a non-empty string");
 		return await runExclusive(docId, async (doc) => {
-			await observePull(doc);
-			const documentVersion = encodeDocVersionMark(doc.versionMark());
+			const [, entityState] = await Promise.all([observePull(doc), fetchEntityStateForSandbox(docId)]);
+			const documentVersion = `${encodeDocVersionMark(doc.versionMark())}:entities:${entityState.revision}`;
 			const baselineKey = `${contextId}\u0000${docId}`;
 			const previousVersion = modelContextVersions.get(baselineKey);
 			const updatedSincePreviousModelCall = previousVersion == null ? null : previousVersion !== documentVersion;
@@ -1854,18 +1660,60 @@ function createMedeoTool(options) {
 	async function snapshot(input) {
 		return runExclusive(input.doc_id, async (doc) => {
 			assertNoPendingPush(input.doc_id);
-			const pull = await observePull(doc);
+			const [pull, entityState] = await Promise.all([observePull(doc), fetchEntityStateForSandbox(input.doc_id)]);
 			return {
 				ok: true,
 				op: "snapshot",
 				doc_id: input.doc_id,
-				version: encodeDocVersionMark(doc.versionMark()),
-				preview: renderCompactProjection(doc.snapshot()),
+				version: `${encodeDocVersionMark(doc.versionMark())}:entities:${entityState.revision}`,
+				preview: renderEntitySnapshot(entityState) + migrationNotice(doc.snapshot(), entityState),
 				collaborated: pull.collaborated,
 				...pull.warnings !== void 0 ? { warnings: pull.warnings } : {}
 			};
 		});
 	}
+	async function migrate(input) {
+		return runExclusive(input.doc_id, async (doc) => {
+			assertNoPendingPush(input.doc_id);
+			const client = new EntityGraphHttpClient({
+				docId: input.doc_id,
+				httpOrigin: requiredContext(options.httpOrigin, input.doc_id, "httpOrigin"),
+				...options.authToken === void 0 ? {} : { authToken: () => optionalContext(options.authToken, input.doc_id) },
+				...options.userId === void 0 ? {} : { userId: () => optionalContext(options.userId, input.doc_id) },
+				...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl }
+			});
+			const base = await client.fetchState();
+			if (base.rows.entities.some((row) => row.entityKind === "timeline")) return {
+				ok: true,
+				op: "migrate-legacy",
+				doc_id: input.doc_id,
+				migration_status: "already_entity",
+				entity_revision: base.revision,
+				next_action: "snapshot"
+			};
+			const pull = await doc.pull();
+			if (!pull.ok) throw new Error(`Migration requires a fresh canonical snapshot: ${pull.error.message}`);
+			const migrationBaseVv = encodeDocVersionMark(doc.versionMark());
+			const nextRows = migrateLegacyTimelineToEntities(doc.snapshot(), input.asset_facts, base.rows);
+			let revision;
+			try {
+				revision = (await client.commit(base, nextRows, { migrationBaseVv })).revision;
+			} catch (error) {
+				if (error instanceof MengineHttpRequestError) throw new Error(`Migration rejected (HTTP ${error.status}): ${entityHttpErrorMessage(error.payload)}; take a fresh snapshot before retrying`);
+				throw new Error("Migration submission is unconfirmed; take a fresh snapshot and retry migrate-legacy to inspect whether the Entity timeline already exists");
+			}
+			documents.delete(input.doc_id);
+			for (const [id, cached] of plans) if (cached.docId === input.doc_id) plans.delete(id);
+			return {
+				ok: true,
+				op: "migrate-legacy",
+				doc_id: input.doc_id,
+				migration_status: "committed",
+				entity_revision: revision,
+				next_action: "snapshot"
+			};
+		});
+	}
 	async function run(input) {
 		return runExclusive(input.doc_id, async (doc) => {
 			assertNoPendingPush(input.doc_id);
@@ -1876,6 +1724,7 @@ function createMedeoTool(options) {
 				document,
 				baseVersion,
 				entityState,
+				entityOnly: true,
 				script: input.script,
 				...input.inputs !== void 0 ? { inputs: input.inputs } : {},
 				timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs,
@@ -1973,6 +1822,7 @@ function createMedeoTool(options) {
 			try {
 				const parsed = parseInput(input);
 				if (parsed.op === "snapshot") return await snapshot(parsed);
+				if (parsed.op === "migrate-legacy") return await migrate(parsed);
 				if (parsed.op === "run-edit-script") return await run(parsed);
 				return await commit(parsed);
 			} catch (error) {