@mengine/medeo-tool 1.2.1-alpha.0 → 1.2.1-alpha.10

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { i as renderCompactProjection, n as collectAffectedPartIds, r as renderPreview, t as EditSandboxSession } from "./script-session-DdPA4tTf.mjs";
-import { MengineDocSession, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, replayJournal, toVideoDocument } from "@mengine/medeo-client";
+import { c as renderPreview, l as renderCompactProjection, n as EntitySandbox, o as isMediaAssetVariantKind, r as toDslRows, s as collectAffectedPartIds, t as EditSandboxSession } from "./script-session-B4fLNe-p.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
@@ -23,6 +23,7 @@ function runEditScript(options) {
 	const workerEntryUrl = options.workerEntryUrl ?? sourceSibling("worker-entry");
 	const resolveRegisterUrl = sourceSibling("node-esm-resolve-register");
 	const ops = [];
+	const entityCommands = [];
 	const logs = [];
 	return new Promise((resolve) => {
 		let settled = false;
@@ -33,7 +34,9 @@ function runEditScript(options) {
 				document: options.document,
 				script: options.script,
 				inputs: options.inputs,
-				idLabel: options.idLabel
+				entityState: options.entityState,
+				idLabel: options.idLabel,
+				entityOnly: options.entityOnly
 			},
 			execArgv: resolveRegisterUrl.pathname.endsWith(".ts") ? [
 				"--experimental-transform-types",
@@ -54,6 +57,7 @@ function runEditScript(options) {
 					error: { message: `edit script exceeded timeout of ${timeoutMs}ms` },
 					partial: {
 						ops: ops.slice(),
+						entityCommands: entityCommands.slice(),
 						logs: logs.slice()
 					}
 				});
@@ -81,6 +85,10 @@ function runEditScript(options) {
 				ops.push(message.entry);
 				return;
 			}
+			if (message.t === "entity-entry") {
+				entityCommands.push(message.command);
+				return;
+			}
 			if (message.t === "log") {
 				logs.push(message.line);
 				return;
@@ -89,14 +97,19 @@ function runEditScript(options) {
 				ops.length = Math.max(0, Math.min(message.index, ops.length));
 				return;
 			}
+			if (message.t === "entity-truncate") {
+				entityCommands.length = Math.max(0, Math.min(message.index, entityCommands.length));
+				return;
+			}
 			if (message.t === "done") {
-				if (message.opsCount !== ops.length) {
+				if (message.opsCount !== ops.length || message.entityCommandsCount !== entityCommands.length) {
 					finish({
 						ok: false,
 						phase: "runtime",
-						error: { message: `opsCount mismatch: worker reported ${message.opsCount}, host collected ${ops.length}` },
+						error: { message: `journal count mismatch: worker reported timeline=${message.opsCount}, entities=${message.entityCommandsCount}; host collected timeline=${ops.length}, entities=${entityCommands.length}` },
 						partial: {
 							ops: ops.slice(),
+							entityCommands: entityCommands.slice(),
 							logs: logs.slice()
 						}
 					});
@@ -105,9 +118,15 @@ function runEditScript(options) {
 				finish({
 					ok: true,
 					plan: {
+						plan_kind: message.planKind,
 						doc_id: options.document.meta.draft_id ?? "",
 						base_version: options.baseVersion,
 						ops: ops.slice(),
+						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()
 					},
@@ -121,6 +140,7 @@ function runEditScript(options) {
 				error: message.error,
 				partial: {
 					ops: ops.slice(),
+					entityCommands: entityCommands.slice(),
 					logs: logs.slice()
 				}
 			});
@@ -137,6 +157,7 @@ function runEditScript(options) {
 				},
 				partial: {
 					ops: ops.slice(),
+					entityCommands: entityCommands.slice(),
 					logs: logs.slice()
 				}
 			});
@@ -150,6 +171,7 @@ function runEditScript(options) {
 				error: { message: `worker exited with code ${code ?? "null"} before completion` },
 				partial: {
 					ops: ops.slice(),
+					entityCommands: entityCommands.slice(),
 					logs: logs.slice()
 				}
 			});
@@ -157,791 +179,984 @@ function runEditScript(options) {
 	});
 }
 //#endregion
-//#region src/sandbox/generated/edit-sandbox-model-context.ts
+//#region src/entity/entity-contract.ts
+const KNOWN_ENTITY_KINDS = [
+	"axvideo",
+	"timeline",
+	"track",
+	"clip",
+	"asset",
+	"video",
+	"audio",
+	"voice",
+	"image",
+	"sequence-marker",
+	"viewport",
+	"audio-script",
+	"phonetic-script",
+	"caption"
+];
+const KNOWN_RELATION_KINDS = [
+	"timeline-track",
+	"track-clip",
+	"clip-marker",
+	"marker-content",
+	"axvideo-marker",
+	"marker-timeline",
+	"physical-asset",
+	"generated",
+	"phonetic-script-provenance",
+	"caption-provenance",
+	"caption-alignment",
+	"clip-anchor",
+	"audio-script-render"
+];
+//#endregion
+//#region src/entity/entity-http-client.ts
+const API_PREFIX = "/api/mengine/v1";
+const entityKinds = new Set(KNOWN_ENTITY_KINDS);
+const relationKinds = new Set(KNOWN_RELATION_KINDS);
+var MengineEntityHttpRequestError = class extends Error {
+	status;
+	payload;
+	constructor(status, payload) {
+		super(`mengine entity-state request failed: ${status}`);
+		this.status = status;
+		this.payload = payload;
+		this.name = "MengineEntityHttpRequestError";
+	}
+};
+/** Narrow authenticated client for the entity-store CAS endpoint. */
+var EntityHttpClient = class {
+	options;
+	fetchImpl;
+	constructor(options) {
+		this.options = options;
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+	}
+	async fetchState() {
+		return toSnapshot(await this.requestJson({ method: "GET" }), this.options.docId);
+	}
+	async commit(expectedRevision, state, deletions = {}) {
+		return toSnapshot(await this.requestJson({
+			method: "POST",
+			body: JSON.stringify({
+				expected_revision: expectedRevision,
+				rows: {
+					entities: state.entities,
+					relations: state.relations
+				},
+				deleted_entity_ids: [...deletions.deleted_entity_ids ?? []],
+				deleted_relation_ids: [...deletions.deleted_relation_ids ?? []]
+			})
+		}), this.options.docId);
+	}
+	async requestJson(init) {
+		const response = await this.fetchImpl(this.endpoint(), {
+			...init,
+			headers: this.headers()
+		});
+		const payload = await safeReadJson(response);
+		if (!response.ok) throw new MengineEntityHttpRequestError(response.status, payload);
+		return payload;
+	}
+	headers() {
+		const headers = new Headers({
+			accept: "application/json",
+			"content-type": "application/json"
+		});
+		const authToken = typeof this.options.authToken === "function" ? this.options.authToken() : this.options.authToken;
+		if (authToken != null && authToken !== "") headers.set("authorization", `Bearer ${authToken}`);
+		const userId = typeof this.options.userId === "function" ? this.options.userId() : this.options.userId;
+		if (userId != null && userId !== "") headers.set("medeo-user-id", userId);
+		return headers;
+	}
+	endpoint() {
+		return `${this.options.httpOrigin.replace(/\/$/, "")}${API_PREFIX}/docs/${encodeURIComponent(this.options.docId)}/entity-state`;
+	}
+};
+function toSnapshot(value, expectedDocId) {
+	if (!isRecord$2(value) || typeof value.doc_id !== "string" || !isNonNegativeInteger(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}"`);
+	if (!isRecord$2(value.rows) || !Array.isArray(value.rows.entities) || !Array.isArray(value.rows.relations)) throw new Error("invalid entity-state response rows");
+	const response = value;
+	return {
+		revision: response.revision,
+		entities: response.rows.entities.map(parseEntity),
+		relations: response.rows.relations.map(parseRelation)
+	};
+}
+function parseEntity(value) {
+	if (!isRecord$2(value) || !isTrimmed(value.entity_id) || typeof value.entity_kind !== "string" || !entityKinds.has(value.entity_kind) || !isJsonObject(value.payload)) throw new Error("invalid Entity row in entity-state response");
+	return structuredClone(value);
+}
+function parseRelation(value) {
+	if (!isRecord$2(value) || !isTrimmed(value.relation_id) || typeof value.relation_kind !== "string" || !relationKinds.has(value.relation_kind) || !isTrimmed(value.endpoint_0_entity_id) || !isTrimmed(value.endpoint_1_entity_id) || !isJsonObject(value.metadata) || !isJsonObject(value.trace)) throw new Error("invalid Relation row in entity-state response");
+	return structuredClone(value);
+}
+function isJsonObject(value) {
+	return isJsonValue(value, /* @__PURE__ */ new Set()) && isRecord$2(value);
+}
+function isJsonValue(value, ancestors) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value !== "object" || ancestors.has(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) return false;
+	ancestors.add(value);
+	const valid = Array.isArray(value) ? value.every((item) => isJsonValue(item, ancestors)) : Object.values(value).every((item) => isJsonValue(item, ancestors));
+	ancestors.delete(value);
+	return valid;
+}
+function isRecord$2(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isTrimmed(value) {
+	return typeof value === "string" && value.length > 0 && value.trim() === value;
+}
+function isNonNegativeInteger(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;
+	}
+}
+//#endregion
+//#region src/entity/generation-sync.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.
+* External systems whose asset entities carry a factual Memota identity.
+* Voice results use the speech system; every other medium uses `memota`.
 */
-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 };",
-	"          }[];",
+const ASSET_SYSTEMS = new Set(["memota", "memota-speech"]);
+/** Bounded CAS retry budget for the sync commit after a concurrent winner. */
+const MAX_COMMIT_ATTEMPTS = 3;
+/** Validate host-supplied facts; a malformed record fails the whole query. */
+function parseGenerationFacts(value) {
+	if (!Array.isArray(value)) throw new Error("generation facts must be an array");
+	return value.map((item) => {
+		if (!isRecord$1(item)) throw new Error("each generation fact must be an object");
+		const { outputAssetId, inputAssetIds } = item;
+		if (typeof outputAssetId !== "string" || outputAssetId.length === 0 || outputAssetId.trim() !== outputAssetId) throw new Error("generation fact outputAssetId must be a non-empty trimmed string");
+		if (!Array.isArray(inputAssetIds)) throw new Error("generation fact inputAssetIds must be an array (explicit [] means text-only)");
+		const inputs = inputAssetIds;
+		for (const input of inputs) if (typeof input !== "string" || input.length === 0 || input.trim() !== input) throw new Error("generation fact inputAssetIds entries must be non-empty trimmed strings");
+		return {
+			outputAssetId,
+			inputAssetIds: [...inputs]
+		};
+	});
+}
+function planGenerationScope(base, commands, state) {
+	const touchedIds = /* @__PURE__ */ new Set();
+	for (const command of commands) if (command.kind === "create-entity" && isMediaAssetVariantKind(command.entity.entity_kind)) touchedIds.add(command.entity.entity_id);
+	const beforeByKey = resolveMediaByAssetKey(base);
+	const scoped = /* @__PURE__ */ new Set();
+	const queryKeys = /* @__PURE__ */ new Set();
+	for (const [key, mediaIds] of resolveMediaByAssetKey(state)) {
+		const previousIds = new Set(beforeByKey.get(key) ?? []);
+		for (const id of mediaIds) {
+			if (!touchedIds.has(id) || previousIds.has(id)) continue;
+			scoped.add(id);
+			queryKeys.add(key);
+		}
+	}
+	return {
+		scopedMediaIds: scoped,
+		queryAssetKeys: [...queryKeys].sort()
+	};
+}
+/**
+* Ordered generated(output,input) Relations missing from `state` for the given
+* factual records. Both endpoints must already exist and match their own Asset
+* identities, and the pair must involve a media Entity the plan
+* newly fact-exposed (`scopedMediaIds`): lineage scopes to the commit's diff,
+* so a pair the user deleted between untouched entities stays deleted. A pair
+* the facts already resolved against the plan's base state is likewise skipped.
+* One-sided facts, text-only records, self pairs, and already-linked pairs are
+* skipped. Duplicate records collapse to one Relation.
+*/
+function planGeneratedRelations(input) {
+	const { state, facts } = input;
+	const scoped = input.scopedMediaIds;
+	const factKeys = new Set(facts.flatMap((fact) => [fact.outputAssetId, ...fact.inputAssetIds]));
+	const mediaByAssetKey = resolveMediaByAssetKey(state, factKeys);
+	const baseResolvable = new Set(resolvablePairs(resolveMediaByAssetKey(input.baseState, factKeys), facts));
+	const linkedPairs = new Set(state.relations.filter((relation) => relation.relation_kind === "generated").map((relation) => pairKey(relation.endpoint_0_entity_id, relation.endpoint_1_entity_id)));
+	const relations = [];
+	for (const fact of facts) for (const outputId of mediaByAssetKey.get(fact.outputAssetId) ?? []) for (const inputAssetId of fact.inputAssetIds) for (const inputId of mediaByAssetKey.get(inputAssetId) ?? []) {
+		if (outputId === inputId) continue;
+		if (!scoped.has(outputId) && !scoped.has(inputId)) continue;
+		const pair = pairKey(outputId, inputId);
+		if (linkedPairs.has(pair) || baseResolvable.has(pair)) continue;
+		linkedPairs.add(pair);
+		relations.push({
+			relation_id: input.newRelationId(),
+			relation_kind: "generated",
+			endpoint_0_entity_id: outputId,
+			endpoint_1_entity_id: inputId,
+			metadata: {},
+			trace: { synced_by: "generation-sync" }
+		});
+	}
+	return relations;
+}
+/**
+* Sync generation lineage after a confirmed entity commit. Any failure is
+* returned as a `failed` outcome instead of thrown, so the already-durable
+* commit result is never masked; a successful query that finds nothing is
+* `current`. Asset identities are immutable, so facts are queried once. A
+* revision conflict re-reads current entities and relations, re-plans, and
+* retries within `MAX_COMMIT_ATTEMPTS`; deleted endpoints are never recreated.
+*/
+async function syncGeneratedRelations(input) {
+	const { client, docId, baseState, entityCommands, loadFacts } = input;
+	try {
+		let state = await client.fetchState();
+		let scope = planGenerationScope(baseState, entityCommands, state);
+		if (scope.queryAssetKeys.length === 0) return { status: "current" };
+		const facts = parseGenerationFacts(await loadFacts(docId, scope.queryAssetKeys));
+		for (let attempt = 1; attempt <= MAX_COMMIT_ATTEMPTS; attempt++) {
+			if (scope.queryAssetKeys.length === 0) return { status: "current" };
+			const relations = planGeneratedRelations({
+				baseState,
+				state,
+				scopedMediaIds: scope.scopedMediaIds,
+				facts,
+				newRelationId: mintRelationId
+			});
+			if (relations.length === 0) return { status: "current" };
+			try {
+				await client.commit(state.revision, {
+					...state,
+					relations: [...state.relations, ...relations]
+				});
+				return {
+					status: "applied",
+					created_relation_ids: relations.map((relation) => relation.relation_id)
+				};
+			} catch (error) {
+				if (!(error instanceof MengineEntityHttpRequestError && error.status === 409) || attempt === MAX_COMMIT_ATTEMPTS) return {
+					status: "failed",
+					message: `generation lineage sync commit failed: ${errorMessage(error)}`
+				};
+				state = await client.fetchState();
+				scope = planGenerationScope(baseState, entityCommands, state);
+			}
+		}
+		return {
+			status: "failed",
+			message: "generation lineage sync exhausted its retry budget"
+		};
+	} catch (error) {
+		return {
+			status: "failed",
+			message: `generation lineage query failed: ${errorMessage(error)}`
+		};
+	}
+}
+function assetKeyOf(entity) {
+	if (!isMediaAssetVariantKind(entity.entity_kind)) return void 0;
+	const external = entity.payload?.external;
+	if (external == null || typeof external !== "object" || Array.isArray(external)) return void 0;
+	const { system, key } = external;
+	if (typeof system !== "string" || !ASSET_SYSTEMS.has(system)) return void 0;
+	if (typeof key !== "string" || key.length === 0 || key.trim() !== key) return void 0;
+	return key;
+}
+/** Media variants own their Asset locator; generation lookup never follows Relations. */
+function resolveMediaByAssetKey(state, factKeys) {
+	const systemByKey = /* @__PURE__ */ new Map();
+	for (const entity of state.entities) {
+		const key = assetKeyOf(entity);
+		if (key === void 0 || !factKeys?.has(key)) continue;
+		const system = entity.payload.external.system;
+		if (systemByKey.has(key) && systemByKey.get(key) !== system) throw new Error(`Ambiguous generation asset id ${key} across media and speech namespaces`);
+		systemByKey.set(key, system);
+	}
+	const resolved = /* @__PURE__ */ new Map();
+	for (const entity of state.entities) {
+		if (!isMediaAssetVariantKind(entity.entity_kind)) continue;
+		const key = assetKeyOf(entity);
+		if (key === void 0) continue;
+		const matches = resolved.get(key) ?? [];
+		matches.push(entity.entity_id);
+		resolved.set(key, matches);
+	}
+	return resolved;
+}
+function pairKey(endpoint0, endpoint1) {
+	return `${endpoint0}\u0000${endpoint1}`;
+}
+/** Pair keys the facts already resolve to under the given base bindings. */
+function resolvablePairs(mediaByAssetKey, facts) {
+	const pairs = [];
+	for (const fact of facts) for (const outputId of mediaByAssetKey.get(fact.outputAssetId) ?? []) for (const inputAssetId of fact.inputAssetIds) for (const inputId of mediaByAssetKey.get(inputAssetId) ?? []) if (outputId !== inputId) pairs.push(pairKey(outputId, inputId));
+	return pairs;
+}
+function mintRelationId() {
+	return `relation_${randomUUID()}`;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isRecord$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+//#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 BoundedDerivedSequencePayload extends JsonObject {",
+	"  extent: {",
+	"    kind: 'bounded';",
+	"    start: number;",
+	"    end: number;",
+	"  };",
+	"  sampling: 'derived';",
+	"  coordinateSpace: JsonValue;",
+	"}",
+	"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 CaptionFontDescriptor {",
+	"  readonly system: 'font-library';",
+	"  readonly key: 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 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;",
+	"}",
+	"export interface DeleteClipInput {",
+	"  readonly clipEntityId: string;",
+	"}",
+	"export interface DeleteClipTreeInput {",
+	"  readonly clipEntityIds: readonly string[];",
+	"  readonly onAnchored: 'cascade' | 'detach';",
+	"}",
+	"export interface DeleteEntityInput {",
+	"  entity_id: string;",
+	"}",
+	"export interface DeleteVoiceoverInput {",
+	"  readonly voiceoverClipEntityIds: readonly 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;",
+	"  /** Find document resources by external Memota asset id, including directly composed media variants. */",
+	"  findByAssetId(assetId: string): SandboxEntity<ResourceEntityKind>[];",
+	"  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;",
+	"  /** Get or create one typed Asset by factual external id and return its single content identity. Never creates a Clip. */",
+	"  ensureMedia(fact: MediaAssetFact): {",
+	"    contentEntityId: string;",
+	"  };",
+	"}",
+	"export type EntityId = string;",
+	"export interface EntityPayloadByKind {",
+	"  axvideo: BoundedDerivedSequencePayload;",
+	"  timeline: JsonObject;",
+	"  track: JsonObject & {",
+	"    hidden?: boolean;",
+	"    role?: string;",
+	"  };",
+	"  clip: JsonObject;",
+	"  /** Inline caption text; external media uses a typed Asset variant. */",
+	"  asset: JsonObject;",
+	"  video: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  audio: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  voice: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  image: UnboundedConstantSequencePayload & MediaAssetPayload;",
+	"  '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;",
+	"}",
+	"export interface EntityStoreSnapshot {",
+	"  revision: number;",
+	"  entities: SandboxEntity[];",
+	"  relations: SandboxRelation[];",
+	"}",
+	"export interface ImageMediaAssetFact {",
+	"  readonly assetId: string;",
+	"  readonly kind: 'image';",
+	"  readonly storageKey?: string;",
+	"}",
+	"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;",
+	"}",
+	"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;",
 	"}",
-	"",
-	"/**",
-	" * TTS voice summary attached to a speech",
-	" */",
-	"export interface Voice {",
-	"  /**",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  id: string;",
-	"  name: string;",
+	"export interface InsertMediaClipsInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly clips: readonly ReplacementMediaClipInput[];",
+	"  /** One placement decision for the whole input-ordered block. */",
+	"  readonly insertion: MediaClipInsertion;",
 	"}",
-	"",
-	"/**",
-	" * 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;",
+	"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 interface JsonObject {",
+	"  [key: string]: JsonValue;",
+	"}",
+	"export type JsonPrimitive = string | number | boolean | null;",
+	"export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];",
+	"export type KnownEntityKind =",
+	"  | 'axvideo'",
+	"  | 'timeline'",
+	"  | 'track'",
+	"  | 'clip'",
+	"  | 'asset'",
+	"  | 'video'",
+	"  | 'audio'",
+	"  | 'voice'",
+	"  | 'image'",
+	"  | 'sequence-marker'",
+	"  | 'viewport'",
+	"  | 'audio-script'",
+	"  | 'phonetic-script'",
+	"  | 'caption';",
+	"export type KnownRelationKind =",
+	"  | 'timeline-track'",
+	"  | 'track-clip'",
+	"  | 'clip-marker'",
+	"  | 'marker-content'",
+	"  | 'axvideo-marker'",
+	"  | 'marker-timeline'",
+	"  | 'physical-asset'",
+	"  | 'generated'",
+	"  | 'phonetic-script-provenance'",
+	"  | 'caption-provenance'",
+	"  | 'caption-alignment'",
+	"  | 'clip-anchor'",
+	"  | 'audio-script-render';",
+	"export interface LinearClipSpeed {",
+	"  readonly kind: 'linear';",
+	"  readonly rate: number;",
+	"  readonly mode?: string;",
+	"}",
+	"export interface LinkAudioScriptRenderRelationInput {",
+	"  relation_id?: string;",
+	"  output_entity_id: string;",
+	"  script_entity_id: string;",
+	"  trace?: JsonObject;",
+	"}",
+	"export interface LinkClipAnchorRelationInput {",
+	"  relation_id?: string;",
+	"  child_clip_entity_id: string;",
+	"  host_clip_entity_id: string;",
+	"  trace?: JsonObject;",
+	"}",
+	"export interface LinkGeneratedRelationInput {",
+	"  relation_id?: string;",
+	"  output_entity_id: string;",
+	"  input_entity_id: string;",
+	"  trace?: 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;",
+	"      };",
+	"    });",
+	"/** Facts resolved from media storage. A trim window never substitutes for intrinsic duration. */",
+	"export type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceMediaAssetFact;",
+	"export type MediaAssetPayload = JsonObject & {",
+	"  external: {",
+	"    system: 'memota' | 'memota-speech';",
+	"    key: string;",
+	"  };",
+	"  storageKey?: string;",
+	"};",
+	"export type MediaClipInsertion =",
+	"  | {",
+	"      readonly kind: 'before';",
+	"      readonly clipEntityId: string;",
+	"    }",
+	"  | {",
+	"      readonly kind: 'after';",
+	"      readonly clipEntityId: string;",
+	"    }",
+	"  | {",
+	"      readonly kind: 'firstStart';",
+	"      readonly startMs: number;",
 	"    };",
-	"    /**",
-	"     * @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;",
-	"  }[];",
+	"export interface MoveClipInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly trackEntityId: 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 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 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 MoveSequentialClipsInput {",
+	"  readonly clipEntityIds: readonly string[];",
+	"  readonly anchor: SequentialClipAnchor;",
+	"  readonly onAnchored: 'follow' | 'keepAbsolute';",
 	"}",
-	"",
-	"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 MoveVoiceoverInput {",
+	"  readonly voiceoverClipEntityId: string;",
+	"  /** Absolute requested timeline start; MEngine resolves and persists the host relation. */",
+	"  readonly newStartMs: number;",
 	"}",
-	"",
-	"/**",
-	" * 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 PatchCaptionStyleInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly style: CaptionStyleFields;",
 	"}",
-	"",
-	"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 interface RelationFacade {",
+	"  list(): SandboxRelation[];",
+	"  /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */",
+	"  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];",
+	"  /** physical-asset binds inline Caption text, never external media. */",
+	"  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;",
 	"}",
-	"",
-	"/**",
-	" * 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 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;",
 	"}",
-	"",
-	"/**",
-	" * 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 ReplaceMediaClipInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly media: VisualMediaAssetFact;",
+	"  readonly sourceRange: SequenceRange<number>;",
 	"}",
-	"",
-	"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 ReplaceSequentialClipsInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly oldClipEntityIds: readonly string[];",
+	"  readonly newClips: readonly ReplacementMediaClipInput[];",
+	"  readonly onAnchored: 'remap' | 'cascade';",
 	"}",
-	"",
-	"/**",
-	" * 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 ReplacementMediaClipInput {",
+	"  readonly clipEntityId?: string;",
+	"  readonly media: VisualMediaAssetFact;",
+	"  readonly sourceRange: SequenceRange<number>;",
+	"  readonly volume?: number;",
 	"}",
-	"",
-	"/**",
-	" * 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[];",
+	"/** Asset identity, either an old physical-only row or a directly composed media variant. */",
+	"export type ResourceEntityKind = 'image' | 'video' | 'audio' | 'voice';",
+	"export interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {",
+	"  entity_id: string;",
+	"  entity_kind: K;",
+	"  payload: EntityPayloadByKind[K];",
 	"}",
-	"",
-	"/**",
-	" * 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 interface SandboxRelation {",
+	"  relation_id: string;",
+	"  relation_kind: KnownRelationKind;",
+	"  endpoint_0_entity_id: string;",
+	"  endpoint_1_entity_id: string;",
+	"  metadata: JsonObject;",
+	"  trace: JsonObject;",
 	"}",
-	"",
-	"/**",
-	" * 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 type ScriptTextSegment = JsonObject & {",
+	"  segmentId: string;",
+	"  text: string;",
+	"  language?: string;",
+	"};",
+	"export type SequenceDuration<Span = unknown> =",
+	"  | {",
+	"      readonly mode: 'from-source';",
+	"    }",
+	"  | {",
+	"      readonly mode: 'fixed';",
+	"      readonly value: Span;",
+	"    };",
+	"export interface SequenceRange<Point = unknown> {",
+	"  readonly start: Point;",
+	"  readonly end: Point;",
+	"}",
+	"export type SequentialClipAnchor =",
+	"  | {",
+	"      readonly position: 'before' | 'after';",
+	"      readonly clipEntityId: string;",
+	"    }",
+	"  | {",
+	"      readonly position: 'trackStart';",
+	"    };",
+	"export interface SetBgmInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly bgmClipEntityId: string;",
+	"  readonly media: AudioMediaAssetFact;",
+	"  readonly volume: number;",
 	"}",
-	"",
-	"/**",
-	" * Toggle caption visibility (the caption track's `is_hidden` flag).",
-	" */",
 	"export interface SetCaptionVisibilityInput {",
-	"  /**",
-	"   * Whether the caption track is hidden",
-	"   */",
-	"  is_hidden: boolean;",
+	"  readonly timelineEntityId: string;",
+	"  readonly hidden: boolean;",
 	"}",
-	"",
-	"/**",
-	" * 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 SetClipPlacementInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly placement: ClipPlacement;",
 	"}",
-	"",
-	"/**",
-	" * 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 SetClipSpeedInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly timeRemapping: LinearClipSpeed | null;",
 	"}",
-	"",
-	"/**",
-	" * Remove the document BGM.",
-	" */",
-	"export interface DeleteBgmInput {",
-	"  [key: string]: never;",
+	"export interface SetClipVolumeInput {",
+	"  readonly clipEntityId: string;",
+	"  /** Playback gain in decibels. */",
+	"  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 TrimClipInput {",
+	"  readonly clipEntityId: string;",
+	"  readonly sourceRange: SequenceRange<number>;",
 	"}",
-	"",
-	"/** Agent write surface — one method per SemanticOp kind. */",
-	"export interface EditApi {",
-	"  moveVideoClips(input: MoveVideoClipsInput): Promise<void>;",
-	"  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>;",
-	"  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 UnboundedConstantSequencePayload extends JsonObject {",
+	"  extent: {",
+	"    kind: 'unbounded';",
+	"    start: number;",
+	"  };",
+	"  sampling: 'constant';",
+	"  coordinateSpace: JsonValue;",
 	"}",
-	"",
-	"/** 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 UnlinkRelationInput {",
+	"  relation_id: string;",
 	"}",
-	"",
-	"/** 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 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;",
-	"",
-	"/** 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 script arguments (opaque). */",
-	"export declare const inputs: unknown;",
+	"export declare const inputs: Readonly<Record<string, unknown>>;",
 	""
 ].join("\n");
 //#endregion
 //#region src/prompt.ts
 const MEDEO_TOOL_DESCRIPTION = `
-Edit a Medeo video document 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 a forked snapshot. Inspect timeline.*, compute coordinates, and call edit.* methods in one script. The sandbox has no network, storage, clock, or generation access. Pass materialized asset/speech facts through inputs. A successful run returns preview, logs, base_version, and plan_id — not the full op journal.
-- commit-plan: replay a cached plan_id into the live MengineDocSession through SemanticEditor. Use validation=version for all-or-nothing commit, or preflight to localize an op conflict after concurrent edits.
+- snapshot: initialize missing fixed editor structure, then return the Entity/Relation state summary and opaque base version. Initialization is idempotent and may advance the entity revision once; unchanged snapshots do not write.
+- 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 and timeline edits belong in ONE plan. The sandbox has no network, storage or generation access. Pass recalled asset facts through inputs; generation history is not a script input — the host program queries it itself after each commit. 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.
+
+Generating an Asset alone does not require an Entity. Using that resource in the editor DOES: recall the Asset facts, call entities.ensureMedia(fact), then pass its contentEntityId to edit.insertClip. A raw external asset id or URL is not valid contentEntityId. Image/Video/Audio/Voice are logical variants of Asset: a resource has ONE identity and ONE typed row owning both media fields and external {system,key}/storageKey, with no separate Asset row or physical-asset relation. ensureMedia returns contentEntityId and reuses that single identity by external asset id. Each placement still gets its own Clip and SequenceMarker. Generation lineage is program-synced: after each successful commit the tool connects existing typed Assets from host-recalled generation facts (endpoint 0 output, endpoint 1 input) that the host queries itself — do not pass generation history through inputs. Do not author generated Relations yourself, and never create an Entity merely to backfill or represent lineage; media variants the edit itself legitimately needs are still created normally. Text-only generation has no input and no lineage edge. 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 is not a model input: the host program queries it via loadGenerationFacts and syncs generated Relations after each successful commit. Memota asset facts are host-provided through inputs. Never invent an asset id, Entity kind, or peer Entity id.
+Use entities.ensureMedia(fact) to get or create the canonical typed Asset. Native media placement helpers use the same resolver. findByAssetId includes directly composed media variants, including Voice. Every Image/Video/Audio/Voice must own its external identity; separate Asset+media graphs are invalid. A typed Asset's external identity cannot be removed or rewritten: to replace its source, ensureMedia for the new Asset and replace the Clip's content. Conflicting facts fail closed. Asset generation itself still creates no editor Entities.
+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.
+physical-asset represents inline Caption text only; Image/Video/Audio/Voice cannot use this relation. Generated lineage Relations are not model-authored: the tool derives them from host generation facts after a successful commit, so do not call relations.linkGenerated to record provenance. 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. The host initializes one Timeline and four fixed Tracks before editing; inspect and reuse their IDs from timeline.snapshot(), never create another Timeline or Track for each operation. 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. */
@@ -960,15 +1175,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
@@ -984,6 +1235,7 @@ const MEDEO_TOOL_PARAMETERS = {
 			type: "string",
 			enum: [
 				"snapshot",
+				"migrate-legacy",
 				"run-edit-script",
 				"commit-plan"
 			],
@@ -997,11 +1249,73 @@ const MEDEO_TOOL_PARAMETERS = {
 		script: {
 			type: "string",
 			minLength: 1,
-			description: "JavaScript body for run-edit-script. It receives edit, timeline, checkpoint, rollbackTo, inputs, and console; perform all calculations in the script."
+			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. Generation and network IO must happen in the host before this call."
+			description: "Pre-materialized, side-effect-free values passed into the script, including recalled asset facts. Generation history is never an input: the host queries lineage itself and syncs generated Relations after each commit. 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",
@@ -1024,11 +1338,24 @@ const MEDEO_TOOL_PARAMETERS = {
 		},
 		validation: {
 			type: "string",
-			enum: ["version", "preflight"],
-			description: "commit-plan mode: version rejects any concurrent change; preflight revalidates each op against the current snapshot."
+			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: {
@@ -1073,39 +1400,37 @@ const MEDEO_TOOL_PARAMETERS = {
 //#endregion
 //#region src/session/commit-plan.ts
 /**
-* Replay a sandbox journal into a live session through its document adapter
-* (SemanticEditor → Loro → mengine-server).
+* Replay a sandbox journal into a manually-synchronized document and push the
+* whole plan as one causally complete update.
 *
-* - Default / `{ validation: 'version' }`: if `session.version()` ≠
-*   `plan.base_version`, reject with zero writes.
+* - Default / `{ validation: 'version' }`: if the current document mark differs
+*   from `plan.base_version`, reject with zero writes.
 * - `{ validation: 'preflight' }`: skip the version gate; revalidate each op
 *   against a PlainMemoryAdapter seeded from the current live snapshot, then
 *   replay for real. A SchemaValidator failure becomes `op_conflict` with the
 *   failing entry's index. Journal integrity errors (unrecorded/unconsumed
 *   ids) still propagate as throws in both modes.
 */
-async function commitPlan(session, plan, options) {
-	if (options?.validation === "preflight") return commitPlanPreflight(session, plan);
-	const actual = session.version();
-	if (actual !== plan.base_version) return {
+async function commitPlan(doc, plan, options) {
+	if (options?.validation === "preflight") return commitPlanPreflight(doc, plan);
+	const actual = encodeDocVersionMark(doc.versionMark());
+	const expected = decodeDocVersionMark(plan.base_version);
+	if (expected == null || doc.hasChangedSince(expected)) return {
 		kind: "rejected",
 		reason: "version_mismatch",
 		expected: plan.base_version,
 		actual
 	};
-	await replayJournal(session.documentAdapter, plan.ops);
-	return {
-		kind: "committed",
-		ops_applied: plan.ops.length
-	};
+	await doc.replayJournal(plan.ops);
+	return retryPlanPush(doc, plan.ops.length);
 }
 /**
 * Phase-2 path: scratch revalidation then real replay. Each entry is driven
 * through `replayJournal` alone so a ValidationError maps to a stable index;
 * integrity throws are not wrapped.
 */
-async function commitPlanPreflight(session, plan) {
-	const scratch = createPlainMemoryAdapter(session.snapshot());
+async function commitPlanPreflight(doc, plan) {
+	const scratch = createPlainMemoryAdapter(doc.snapshot());
 	for (let index = 0; index < plan.ops.length; index++) {
 		const entry = plan.ops[index];
 		if (entry == null) continue;
@@ -1120,15 +1445,41 @@ async function commitPlanPreflight(session, plan) {
 		const entry = plan.ops[index];
 		if (entry == null) continue;
 		try {
-			await replayJournal(session.documentAdapter, [entry]);
+			await doc.replayJournal([entry]);
 		} catch (error) {
 			if (error instanceof ValidationError) return opConflict(index, entry.kind, `real replay: ${error.message}`);
 			throw error;
 		}
 	}
+	return retryPlanPush(doc, plan.ops.length);
+}
+/** Push an already-replayed plan again without replaying or re-running its version gate. */
+async function retryPlanPush(doc, opsApplied) {
+	const result = await doc.push();
+	if (result.kind === "ack" || result.kind === "duplicate" || result.kind === "nothing_to_push") {
+		const reconciled = result.collaborated ? await doc.pull() : void 0;
+		const warnings = reconciled != null && !reconciled.ok ? [{
+			kind: "pull_failed",
+			message: reconciled.error.message
+		}] : void 0;
+		return {
+			kind: "committed",
+			ops_applied: opsApplied,
+			collaborated: result.collaborated,
+			...warnings !== void 0 ? { warnings } : {}
+		};
+	}
+	if (result.kind === "rejected") return {
+		kind: "rejected",
+		reason: "push_rejected",
+		...result.code !== void 0 ? { code: result.code } : {},
+		message: result.error?.message ?? "mengine rejected the sandbox plan"
+	};
 	return {
-		kind: "committed",
-		ops_applied: plan.ops.length
+		kind: "unconfirmed",
+		reason: "push_failed",
+		ops_applied: opsApplied,
+		message: result.error?.message ?? "mengine push failed"
 	};
 }
 function opConflict(index, op_kind, message) {
@@ -1156,6 +1507,112 @@ 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, {
+			deleted_entity_ids: plan.deleted_entity_ids ?? [],
+			deleted_relation_ids: plan.deleted_relation_ids ?? []
+		});
+		return {
+			kind: "committed",
+			ops_applied: plan.entity_commands.length,
+			collaborated: false,
+			entity_revision: committed.revision
+		};
+	} catch (error) {
+		if (error instanceof MengineEntityHttpRequestError) {
+			if (error.status === 409 && isRevisionConflictPayload(error.payload)) {
+				const actualFromPayload = revisionConflictActual(error.payload);
+				try {
+					const current = await client.fetchState();
+					if (current.revision === plan.entity_base_revision + 1 && entityRowsEquivalent(current, rows)) return {
+						kind: "committed",
+						ops_applied: plan.entity_commands.length,
+						collaborated: false,
+						entity_revision: current.revision
+					};
+					return {
+						kind: "rejected",
+						reason: "entity_revision_mismatch",
+						expected: plan.entity_base_revision,
+						actual: current.revision
+					};
+				} catch {
+					if (actualFromPayload !== void 0) return {
+						kind: "rejected",
+						reason: "entity_revision_mismatch",
+						expected: plan.entity_base_revision,
+						actual: actualFromPayload
+					};
+					return {
+						kind: "unconfirmed",
+						reason: "push_failed",
+						ops_applied: plan.entity_commands.length,
+						message: "entity-state conflict could not be reconciled"
+					};
+				}
+			}
+			return {
+				kind: "rejected",
+				reason: "entity_state_rejected",
+				status: error.status,
+				message: entityHttpErrorMessage(error.payload)
+			};
+		}
+		return {
+			kind: "unconfirmed",
+			reason: "push_failed",
+			ops_applied: plan.entity_commands.length,
+			message: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+function revisionConflictActual(payload) {
+	if (!isRecord(payload)) return void 0;
+	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";
+}
+function commitWarnings(result) {
+	return result.kind === "committed" && "warnings" in result && result.warnings !== void 0 ? [...result.warnings] : void 0;
+}
+function entityRowsEquivalent(left, right) {
+	const normalize = (state) => ({
+		entities: [...state.entities].sort((a, b) => a.entity_id.localeCompare(b.entity_id)).map((entity) => canonicalJson(entity)),
+		relations: [...state.relations].sort((a, b) => a.relation_id.localeCompare(b.relation_id)).map((relation) => canonicalJson(relation))
+	});
+	return JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
+}
+function canonicalJson(value) {
+	if (Array.isArray(value)) return value.map(canonicalJson);
+	if (!isRecord(value)) return value;
+	return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalJson(value[key])]));
+}
 function parseInput(value) {
 	if (!isRecord(value)) throw new Error("input must be an object");
 	const op = value.op;
@@ -1166,6 +1623,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");
@@ -1199,58 +1668,78 @@ function parseInput(value) {
 /**
 * Create the self-contained Medeo LLM tool.
 *
-* The package owns session construction, compact projection, sandbox execution,
+* The package owns document construction, compact projection, sandbox execution,
 * plan caching, commit, document get-or-create, and shutdown. The host supplies
 * environment facts plus the authoritative legacy draft loader used only when
 * Mengine has no document yet.
 */
 function createMedeoTool(options) {
-	const sessions = /* @__PURE__ */ new Map();
+	const documents = /* @__PURE__ */ new Map();
+	const entityClients = /* @__PURE__ */ new Map();
+	const documentTails = /* @__PURE__ */ new Map();
+	const pendingPushes = /* @__PURE__ */ new Map();
 	const plans = /* @__PURE__ */ new Map();
 	const modelContextVersions = /* @__PURE__ */ new Map();
 	const maxPlans = options.maxPlans ?? DEFAULT_MAX_PLANS;
 	const maxModelContexts = options.maxModelContexts ?? DEFAULT_MAX_MODEL_CONTEXTS;
 	let closed = false;
-	async function getSession(docId) {
+	async function getDocument(docId) {
 		if (closed) throw new Error("medeo tool is closed");
-		const existing = sessions.get(docId);
+		const existing = documents.get(docId);
 		if (existing != null) return await existing;
 		const created = (async () => {
-			const client = new MengineHttpClient({
+			return await getOrCreateDocument(new MengineHttpClient({
 				docId,
 				httpOrigin: requiredContext(options.httpOrigin, docId, "httpOrigin"),
 				...options.authToken !== void 0 ? { authToken: () => optionalContext(options.authToken, docId) } : {},
 				...options.userId !== void 0 ? { userId: () => optionalContext(options.userId, docId) } : {},
 				...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {}
-			});
-			const peerId = optionalContext(options.peerId, docId);
-			await getOrCreateDocument(client, docId, peerId);
-			const session = new MengineDocSession({
-				docId,
-				client,
-				...peerId !== void 0 ? { peerId } : {},
-				...options.sseReconnectDelayMs !== void 0 ? { sseReconnectDelayMs: options.sseReconnectDelayMs } : {}
-			});
-			try {
-				await session.start();
-				return session;
-			} catch (error) {
-				session.destroy();
-				throw error;
-			}
+			}), docId, optionalContext(options.peerId, docId));
 		})();
-		sessions.set(docId, created);
+		documents.set(docId, created);
 		try {
 			return await created;
 		} catch (error) {
-			if (sessions.get(docId) === created) sessions.delete(docId);
+			if (documents.get(docId) === created) documents.delete(docId);
 			throw error;
 		}
 	}
+	function getEntityClient(docId) {
+		if (closed) throw new Error("medeo tool is closed");
+		const existing = entityClients.get(docId);
+		if (existing != null) return existing;
+		const client = new EntityHttpClient({
+			docId,
+			httpOrigin: requiredContext(options.httpOrigin, docId, "httpOrigin"),
+			...options.authToken !== void 0 ? { authToken: () => optionalContext(options.authToken, docId) } : {},
+			...options.userId !== void 0 ? { userId: () => optionalContext(options.userId, docId) } : {},
+			...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {}
+		});
+		entityClients.set(docId, client);
+		return client;
+	}
+	async function runExclusive(docId, use) {
+		const previous = documentTails.get(docId) ?? Promise.resolve();
+		let release;
+		const gate = new Promise((resolve) => {
+			release = resolve;
+		});
+		const tail = previous.catch(() => {}).then(() => gate);
+		documentTails.set(docId, tail);
+		await previous.catch(() => {});
+		try {
+			return await use(await getDocument(docId));
+		} finally {
+			release();
+			if (documentTails.get(docId) === tail) documentTails.delete(docId);
+		}
+	}
 	async function getOrCreateDocument(client, docId, peerId) {
 		try {
-			await client.fetchSnapshot();
-			return;
+			return await ManualSyncDoc.open({
+				client,
+				...peerId !== void 0 ? { peerId } : {}
+			});
 		} catch (error) {
 			if (!(error instanceof MengineHttpRequestError) || error.status !== 404) throw error;
 			if (options.loadInitialDraft === void 0) throw error;
@@ -1263,119 +1752,338 @@ function createMedeoTool(options) {
 			await client.bootstrapSnapshot(seed.export({ mode: "snapshot" }));
 		} catch (error) {
 			if (!(error instanceof MengineHttpRequestError) || error.status !== 400) throw error;
-			await client.fetchSnapshot();
 		}
+		return await ManualSyncDoc.open({
+			client,
+			...peerId !== void 0 ? { peerId } : {}
+		});
 	}
-	function rememberPlan(docId, plan) {
+	function rememberPlan(docId, plan, baseState) {
 		const planId = randomUUID();
 		plans.set(planId, {
 			docId,
-			plan
+			plan,
+			...plan.plan_kind === "entities" ? { baseState: baseState && structuredClone(baseState) } : {}
 		});
 		while (plans.size > maxPlans) {
-			const oldest = plans.keys().next().value;
-			if (oldest === void 0) break;
-			plans.delete(oldest);
+			const protectedPlanIds = new Set([...pendingPushes.values()].map((pending) => pending.planId));
+			protectedPlanIds.add(planId);
+			const oldestEvictable = [...plans.keys()].find((candidate) => !protectedPlanIds.has(candidate));
+			if (oldestEvictable === void 0) break;
+			plans.delete(oldestEvictable);
 		}
 		return planId;
 	}
+	function assertNoPendingPush(docId) {
+		const pending = pendingPushes.get(docId);
+		if (pending != null) throw new Error(`doc ${docId} has an unconfirmed push; retry plan_id ${pending.planId} before continuing`);
+	}
+	function recordPushResult(docId, planId, plan, result, baseState) {
+		if (result.kind === "unconfirmed") {
+			pendingPushes.set(docId, plan.plan_kind === "timeline" ? {
+				kind: "timeline",
+				planId,
+				plan,
+				opsApplied: result.ops_applied
+			} : {
+				kind: "entities",
+				planId,
+				plan,
+				...baseState !== void 0 ? { baseState } : {}
+			});
+			return;
+		}
+		pendingPushes.delete(docId);
+		if (plan.plan_kind === "timeline" && result.kind === "rejected" && result.reason === "push_rejected") documents.delete(docId);
+	}
+	async function fetchEntityStateForSandbox(docId, doc, pull) {
+		const client = getEntityClient(docId);
+		for (let attempt = 0; attempt < 4; attempt += 1) {
+			const state = await client.fetchState();
+			if (pendingPushes.has(docId)) return state;
+			const document = doc.snapshot();
+			const hasTimeline = state.entities.some((row) => row.entity_kind === "timeline");
+			const hasLegacyContent = Object.keys(document.part_library ?? {}).length > 0 || (document.tracks ?? []).some((track) => (track.items ?? []).length > 0);
+			if (!hasTimeline && hasLegacyContent) return state;
+			if (!hasTimeline) {
+				if (pull.warnings !== void 0) throw new Error("Editor initialization requires a fresh canonical snapshot; retry snapshot");
+				const baseRows = toDslRows(state);
+				const migrated = migrateLegacyTimelineToEntities(document, [], baseRows);
+				try {
+					await getGraphClient(docId).commit({
+						revision: state.revision,
+						rows: baseRows
+					}, migrated, { migrationBaseVv: encodeDocVersionMark(doc.versionMark()) });
+				} catch (error) {
+					if (!(error instanceof MengineHttpRequestError) || error.status !== 409) throw new Error(`Editor initialization was not confirmed; retry snapshot to reconcile state: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				pull = await observePull(doc);
+				continue;
+			}
+			const sandbox = new EntitySandbox({
+				state,
+				idFactory: (prefix) => `${prefix}_${randomUUID()}`
+			});
+			sandbox.ensureFoundation();
+			if (sandbox.commandCount === 0) return state;
+			if (pull.warnings !== void 0) throw new Error("Editor initialization requires a fresh canonical snapshot; retry snapshot");
+			try {
+				const committed = await client.commit(state.revision, sandbox.buildPlan().rows);
+				await doc.pull();
+				return committed;
+			} catch (error) {
+				if (!(error instanceof MengineEntityHttpRequestError) || error.status !== 409) throw new Error(`Editor initialization was not confirmed; retry snapshot to reconcile state: ${error instanceof Error ? error.message : String(error)}`);
+				pull = await observePull(doc);
+			}
+		}
+		throw new Error("Editor initialization conflicted repeatedly; take a fresh snapshot");
+	}
+	function getGraphClient(docId) {
+		return new EntityGraphHttpClient({
+			docId,
+			httpOrigin: requiredContext(options.httpOrigin, docId, "httpOrigin"),
+			...options.authToken === void 0 ? {} : { authToken: () => optionalContext(options.authToken, docId) },
+			...options.userId === void 0 ? {} : { userId: () => optionalContext(options.userId, docId) },
+			...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl }
+		});
+	}
+	async function commitCachedPlan(docId, _doc, plan, validation, baseState) {
+		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");
+		const client = getEntityClient(docId);
+		const preCommitState = baseState ?? (options.loadGenerationFacts !== void 0 ? await client.fetchState() : void 0);
+		return await attachGenerationSync(docId, plan, await commitEntityPlan(client, plan), preCommitState);
+	}
+	/**
+	* After a confirmed entity commit, connect fact-matched generated Relations
+	* from host-recalled lineage. The commit is already durable, so a sync
+	* failure never fails the op; it is attached to the result and surfaced as a
+	* warning instead. The plan's diff against `baseState` scopes the sync:
+	* newly created media Asset identities — not untouched pairs or placement-only edits.
+	* One-sided facts are skipped silently inside the sync.
+	*/
+	async function attachGenerationSync(docId, plan, result, baseState) {
+		if (result.kind !== "committed" || options.loadGenerationFacts === void 0 || baseState === void 0) return result;
+		let outcome;
+		try {
+			outcome = await syncGeneratedRelations({
+				client: getEntityClient(docId),
+				docId,
+				baseState,
+				entityCommands: plan.entity_commands,
+				loadFacts: options.loadGenerationFacts
+			});
+		} catch (error) {
+			outcome = {
+				status: "failed",
+				message: error instanceof Error ? error.message : String(error)
+			};
+		}
+		const warnings = outcome.status === "failed" ? [{
+			kind: "generation_sync_failed",
+			message: outcome.message ?? "generation lineage sync failed"
+		}] : void 0;
+		return {
+			...result,
+			generation_sync: outcome,
+			...warnings !== void 0 ? { warnings } : {}
+		};
+	}
+	async function observePull(doc) {
+		const result = await doc.pull();
+		if (result.ok) return { collaborated: result.changed };
+		return {
+			collaborated: false,
+			warnings: [{
+				kind: "pull_failed",
+				message: result.error.message
+			}]
+		};
+	}
+	function mergeWarnings(...groups) {
+		const warnings = groups.flatMap((group) => group ?? []);
+		return warnings.length > 0 ? warnings : void 0;
+	}
 	async function getModelContext(input) {
 		const docId = input.doc_id.trim();
 		const contextId = input.context_id.trim();
 		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");
-		const documentVersion = (await getSession(docId)).version();
-		const baselineKey = `${contextId}\u0000${docId}`;
-		const previousVersion = modelContextVersions.get(baselineKey);
-		const updatedSincePreviousModelCall = previousVersion == null ? null : previousVersion !== documentVersion;
-		modelContextVersions.delete(baselineKey);
-		modelContextVersions.set(baselineKey, documentVersion);
-		while (modelContextVersions.size > maxModelContexts) {
-			const oldest = modelContextVersions.keys().next().value;
-			if (oldest === void 0) break;
-			modelContextVersions.delete(oldest);
-		}
-		return {
-			prompt: renderMedeoModelContext({
-				documentVersion,
-				updatedSincePreviousModelCall
-			}),
-			document_version: documentVersion,
-			updated_since_previous_model_call: updatedSincePreviousModelCall
-		};
-	}
-	async function confirmCommitted(session, result) {
-		if (result.kind === "committed" && result.ops_applied > 0) await session.waitForServerAck();
-		return result;
+		return await runExclusive(docId, async (doc) => {
+			const entityState = await fetchEntityStateForSandbox(docId, doc, await observePull(doc));
+			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;
+			modelContextVersions.delete(baselineKey);
+			modelContextVersions.set(baselineKey, documentVersion);
+			while (modelContextVersions.size > maxModelContexts) {
+				const oldest = modelContextVersions.keys().next().value;
+				if (oldest === void 0) break;
+				modelContextVersions.delete(oldest);
+			}
+			return {
+				prompt: renderMedeoModelContext({
+					documentVersion,
+					updatedSincePreviousModelCall
+				}),
+				document_version: documentVersion,
+				updated_since_previous_model_call: updatedSincePreviousModelCall
+			};
+		});
 	}
 	async function snapshot(input) {
-		const session = await getSession(input.doc_id);
-		const document = session.snapshot();
-		return {
-			ok: true,
-			op: "snapshot",
-			doc_id: input.doc_id,
-			version: session.version(),
-			preview: renderCompactProjection(document)
-		};
+		return runExclusive(input.doc_id, async (doc) => {
+			assertNoPendingPush(input.doc_id);
+			const pull = await observePull(doc);
+			const entityState = await fetchEntityStateForSandbox(input.doc_id, doc, pull);
+			return {
+				ok: true,
+				op: "snapshot",
+				doc_id: input.doc_id,
+				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 = getGraphClient(input.doc_id);
+			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) {
-		const session = await getSession(input.doc_id);
-		const document = session.snapshot();
-		const baseVersion = session.version();
-		const result = await runEditScript({
-			document,
-			baseVersion,
-			script: input.script,
-			...input.inputs !== void 0 ? { inputs: input.inputs } : {},
-			timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs,
-			memoryLimitMb: input.memory_limit_mb ?? options.sandbox?.memoryLimitMb
+		return runExclusive(input.doc_id, async (doc) => {
+			assertNoPendingPush(input.doc_id);
+			const pull = await observePull(doc);
+			const entityState = await fetchEntityStateForSandbox(input.doc_id, doc, pull);
+			const document = doc.snapshot();
+			const baseVersion = encodeDocVersionMark(doc.versionMark());
+			const result = await runEditScript({
+				document,
+				baseVersion,
+				entityState,
+				entityOnly: true,
+				script: input.script,
+				...input.inputs !== void 0 ? { inputs: input.inputs } : {},
+				timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs,
+				memoryLimitMb: input.memory_limit_mb ?? options.sandbox?.memoryLimitMb
+			});
+			if (!result.ok) return {
+				ok: false,
+				op: "run-edit-script",
+				doc_id: input.doc_id,
+				phase: result.phase,
+				error: result.error,
+				partial: {
+					ops_count: result.partial.ops.length + result.partial.entityCommands.length,
+					logs: result.partial.logs
+				}
+			};
+			const plan = {
+				...result.plan,
+				doc_id: input.doc_id
+			};
+			const planId = rememberPlan(input.doc_id, plan, entityState);
+			const base = {
+				ok: true,
+				op: "run-edit-script",
+				doc_id: input.doc_id,
+				plan_id: planId,
+				plan_kind: plan.plan_kind,
+				base_version: baseVersion,
+				entity_base_revision: plan.entity_base_revision,
+				ops_count: plan.ops.length + plan.entity_commands.length,
+				preview: plan.preview,
+				logs: plan.logs,
+				duration_ms: result.durationMs,
+				collaborated: pull.collaborated,
+				...pull.warnings !== void 0 ? { warnings: pull.warnings } : {}
+			};
+			if (input.auto_commit !== true) return base;
+			const commit = await commitCachedPlan(input.doc_id, doc, plan, void 0, entityState);
+			recordPushResult(input.doc_id, planId, plan, commit, entityState);
+			const warnings = mergeWarnings(pull.warnings, commitWarnings(commit));
+			return {
+				...base,
+				committed: commit.kind === "committed",
+				commit_result: commit,
+				collaborated: pull.collaborated || commit.kind === "committed" && commit.collaborated,
+				...warnings !== void 0 ? { warnings } : {}
+			};
 		});
-		if (!result.ok) return {
-			ok: false,
-			op: "run-edit-script",
-			doc_id: input.doc_id,
-			phase: result.phase,
-			error: result.error,
-			partial: {
-				ops_count: result.partial.ops.length,
-				logs: result.partial.logs
-			}
-		};
-		const planId = rememberPlan(input.doc_id, result.plan);
-		const base = {
-			ok: true,
-			op: "run-edit-script",
-			doc_id: input.doc_id,
-			plan_id: planId,
-			base_version: baseVersion,
-			ops_count: result.plan.ops.length,
-			preview: result.plan.preview,
-			logs: result.plan.logs,
-			duration_ms: result.durationMs
-		};
-		if (input.auto_commit !== true) return base;
-		const commit = await confirmCommitted(session, await commitPlan(session, result.plan));
-		return {
-			...base,
-			committed: commit.kind === "committed",
-			commit_result: commit
-		};
 	}
 	async function commit(input) {
-		const cached = plans.get(input.plan_id);
-		if (cached == null || cached.docId !== input.doc_id) throw new Error(`plan_id ${input.plan_id} is not available for doc ${input.doc_id}`);
-		const session = await getSession(input.doc_id);
-		const commitOptions = input.validation === void 0 ? void 0 : { validation: input.validation };
-		const result = await confirmCommitted(session, await commitPlan(session, cached.plan, commitOptions));
-		return {
-			ok: true,
-			op: "commit-plan",
-			doc_id: input.doc_id,
-			plan_id: input.plan_id,
-			committed: result.kind === "committed",
-			result
-		};
+		return runExclusive(input.doc_id, async (doc) => {
+			const pending = pendingPushes.get(input.doc_id);
+			if (pending != null) {
+				if (pending.planId !== input.plan_id) throw new Error(`doc ${input.doc_id} has an unconfirmed push for plan_id ${pending.planId}; retry it before ${input.plan_id}`);
+				const result = pending.kind === "timeline" ? await retryPlanPush(doc, pending.opsApplied) : await commitCachedPlan(input.doc_id, doc, pending.plan, input.validation, pending.baseState);
+				recordPushResult(input.doc_id, input.plan_id, pending.plan, result, pending.kind === "entities" ? pending.baseState : void 0);
+				const warnings = commitWarnings(result);
+				return {
+					ok: true,
+					op: "commit-plan",
+					doc_id: input.doc_id,
+					plan_id: input.plan_id,
+					plan_kind: pending.plan.plan_kind,
+					committed: result.kind === "committed",
+					result,
+					collaborated: result.kind === "committed" && result.collaborated,
+					...warnings !== void 0 ? { warnings } : {}
+				};
+			}
+			const cached = plans.get(input.plan_id);
+			if (cached == null || cached.docId !== input.doc_id) throw new Error(`plan_id ${input.plan_id} is not available for doc ${input.doc_id}`);
+			const pull = cached.plan.plan_kind === "timeline" ? await observePull(doc) : { collaborated: false };
+			const result = await commitCachedPlan(input.doc_id, doc, cached.plan, input.validation, cached.baseState);
+			recordPushResult(input.doc_id, input.plan_id, cached.plan, result, cached.baseState);
+			const warnings = mergeWarnings(pull.warnings, commitWarnings(result));
+			return {
+				ok: true,
+				op: "commit-plan",
+				doc_id: input.doc_id,
+				plan_id: input.plan_id,
+				plan_kind: cached.plan.plan_kind,
+				committed: result.kind === "committed",
+				result,
+				collaborated: pull.collaborated || result.kind === "committed" && result.collaborated,
+				...warnings !== void 0 ? { warnings } : {}
+			};
+		});
 	}
 	return {
 		name: MEDEO_TOOL_NAME,
@@ -1386,6 +2094,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) {
@@ -1398,18 +2107,22 @@ function createMedeoTool(options) {
 		},
 		async close() {
 			closed = true;
-			const opening = [...sessions.values()];
-			sessions.clear();
+			await Promise.allSettled(documentTails.values());
+			const opening = [...documents.values()];
+			documents.clear();
+			entityClients.clear();
+			documentTails.clear();
+			pendingPushes.clear();
 			plans.clear();
 			modelContextVersions.clear();
 			const errors = [];
-			for (const sessionPromise of opening) try {
-				(await sessionPromise).destroy();
+			for (const documentPromise of opening) try {
+				await documentPromise;
 			} catch (error) {
 				errors.push(error);
 			}
 			if (errors.length === 1) throw errors[0];
-			if (errors.length > 1) throw new AggregateError(errors, "failed to close medeo tool sessions");
+			if (errors.length > 1) throw new AggregateError(errors, "failed to close medeo tool documents");
 		}
 	};
 }