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

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { i as renderCompactProjection, n as collectAffectedPartIds, r as renderPreview, t as EditSandboxSession } from "./script-session-DdPA4tTf.mjs";
-import { MengineDocSession, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, replayJournal, toVideoDocument } from "@mengine/medeo-client";
+import { a as collectAffectedPartIds, o as renderPreview, s as renderCompactProjection, t as EditSandboxSession } from "./script-session-CHyIUBkO.mjs";
+import { EntityGraphHttpClient, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, migrateLegacyTimelineToEntities, replayJournal, toVideoDocument } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
 import { randomUUID } from "node:crypto";
 //#region src/sandbox/node-host.ts
@@ -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,795 @@ function runEditScript(options) {
 	});
 }
 //#endregion
-//#region src/sandbox/generated/edit-sandbox-model-context.ts
-/**
-* @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY
-*
-* Runtime copy of the sandbox TypeScript disclosure. The model prompt imports
-* this value so its interface and the checked-in declaration cannot drift.
-*/
-const EDIT_SANDBOX_API_DTS = [
-	"/**",
-	" * @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY",
-	" *",
-	" * Schema version: video-document/v0",
-	" * Semantic ops: 20",
-	" *",
-	" * Boundary: zod `superRefine` / custom refine rules are NOT introspectable and",
-	" * do not appear here. Business mutual-exclusion rules surface via runtime",
-	" * validation errors (L3 feedback channel).",
-	" *",
-	" * @example 读取→计算→批量写",
-	" * ```ts",
-	" * const clips = timeline.clipsInRange(0, 10_000);",
-	" * await edit.setVideoClipSpeedShift({",
-	" *   clips: clips.map((c) => ({ clip_id: c.id, speed_shift: { category: 'linear', mode: 'constant', config: { linear: { speed: 1.5 } } } })),",
-	" * });",
-	" * ```",
-	" *",
-	" * @example anchored 删除",
-	" * ```ts",
-	" * await edit.deleteVideoClips({ clip_ids: ['clip_a'], on_anchored: 'detach' });",
-	" * ```",
-	" */",
-	"",
-	"/**",
-	" * A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.",
-	" */",
-	"export interface SpeedShift {",
-	"  category: 'linear' | 'curve';",
-	"  mode: string;",
-	"  config:",
-	"    | {",
-	"        linear: {",
-	"          /**",
-	"           * @constraint positive",
-	"           */",
-	"          speed: number;",
-	"        };",
-	"      }",
-	"    | {",
-	"        curve: {",
-	"          /**",
-	"           * @constraint minLength(2)",
-	"           */",
-	"          keyframes: {",
-	"            /**",
-	"             * @constraint min(0)",
-	"             * @constraint max(1)",
-	"             */",
-	"            position: number;",
-	"            /**",
-	"             * @constraint min(0)",
-	"             */",
-	"            rate: number;",
-	"            /**",
-	"             * Bezier tangent handle (x, y)",
-	"             */",
-	"            in_tangent?: { x: number; y: number };",
-	"            /**",
-	"             * Bezier tangent handle (x, y)",
-	"             */",
-	"            out_tangent?: { x: number; y: number };",
-	"          }[];",
+//#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$1(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$1(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$1(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$1(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$1(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$1(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/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;",
+	"  /** Return every explicitly imported Asset entity for a Memota asset id. */",
+	"  findByAssetId(assetId: string): SandboxEntity<'asset'>[];",
+	"  create(input: CreateEntityInput): string;",
+	"  /** Replace one Entity's owned payload without changing its identity or kind. */",
+	"  update(input: UpdateEntityInput): void;",
+	"  /** Delete an Entity only after all of its incident Relations have been explicitly unlinked. */",
+	"  delete(input: DeleteEntityInput): void;",
+	"  /** Import one physical asset without implying a one-to-one media Entity mapping. */",
+	"  importAsset(input: ImportAssetInput): string;",
+	"}",
+	"export type EntityId = string;",
+	"export interface EntityPayloadByKind {",
+	"  axvideo: BoundedDerivedSequencePayload;",
+	"  timeline: JsonObject;",
+	"  track: JsonObject & {",
+	"    hidden?: boolean;",
+	"    role?: string;",
+	"  };",
+	"  clip: JsonObject;",
+	"  /** Asset-owned metadata. Peer media associations belong in physical-asset Relations. */",
+	"  asset: JsonObject;",
+	"  video: BoundedNativeSequencePayload;",
+	"  audio: BoundedNativeSequencePayload;",
+	"  voice: BoundedNativeSequencePayload;",
+	"  image: UnboundedConstantSequencePayload;",
+	"  'sequence-marker': JsonObject & {",
+	"    sourceRange: {",
+	"      start: number;",
+	"      end: number;",
+	"    };",
+	"    targetRange?: {",
+	"      start: number;",
+	"      end: number;",
+	"    };",
+	"    duration:",
+	"      | {",
+	"          mode: 'from-source';",
+	"        }",
+	"      | {",
+	"          mode: 'fixed';",
+	"          value: number;",
 	"        };",
-	"      };",
+	"    timeRemapping?: JsonValue;",
+	"    anchorOffset?: number;",
+	"    durationPolicy?: 'timeline';",
+	"  };",
+	"  viewport: JsonObject;",
+	"  'audio-script': JsonObject & {",
+	"    segments: ScriptTextSegment[];",
+	"  };",
+	"  'phonetic-script': JsonObject & {",
+	"    segments: ScriptTextSegment[];",
+	"  };",
+	"  caption: BoundedNativeSequencePayload;",
+	"}",
+	"export interface EntityStoreSnapshot {",
+	"  revision: number;",
+	"  entities: SandboxEntity[];",
+	"  relations: SandboxRelation[];",
+	"}",
+	"export interface ImageMediaAssetFact {",
+	"  readonly assetId: string;",
+	"  readonly kind: 'image';",
+	"  readonly storageKey?: string;",
+	"}",
+	"export interface ImportAssetInput {",
+	"  asset_id: string;",
+	"  entity_id?: string;",
+	"  payload?: JsonObject;",
+	"}",
+	"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;",
+	"}",
+	"export interface InsertMediaClipsInput {",
+	"  readonly timelineEntityId: string;",
+	"  readonly clips: readonly ReplacementMediaClipInput[];",
+	"  /** One placement decision for the whole input-ordered block. */",
+	"  readonly insertion: MediaClipInsertion;",
+	"}",
+	"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;",
 	"}",
-	"",
-	"/**",
-	" * TTS voice summary attached to a speech",
-	" */",
-	"export interface Voice {",
-	"  /**",
-	"   * @constraint minLength(1)",
-	"   */",
-	"  id: string;",
-	"  name: string;",
+	"export interface LinkClipAnchorRelationInput {",
+	"  relation_id?: string;",
+	"  child_clip_entity_id: string;",
+	"  host_clip_entity_id: string;",
+	"  trace?: JsonObject;",
 	"}",
-	"",
-	"/**",
-	" * 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 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;",
+	"      };",
+	"    });",
+	"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[];",
+	"  /** For physical-asset use sequence media as endpoint 0 and Asset as endpoint 1. */",
+	"  link(input: LinkRelationInput): string;",
+	"  /** Author ordered generated(output,input); generic link() deliberately rejects this kind. */",
+	"  linkGenerated(input: LinkGeneratedRelationInput): string;",
+	"  /** Author ordered clip-anchor(child,host) without positional endpoint ambiguity. */",
+	"  linkClipAnchor(input: LinkClipAnchorRelationInput): string;",
+	"  /** Author ordered audio-script-render(output,script) without positional endpoint ambiguity. */",
+	"  linkAudioScriptRender(input: LinkAudioScriptRenderRelationInput): string;",
+	"  /** Remove a Relation by identity; endpoint replacement is an explicit unlink plus link. */",
+	"  unlink(input: UnlinkRelationInput): void;",
 	"}",
-	"",
-	"/**",
-	" * 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[];",
+	"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: return the Entity/Relation state summary and opaque base version.
+- migrate-legacy: explicitly migrate an existing legacy timeline using recalled asset_facts. MEngine reads the canonical document and version, verifies that editing facts are preserved, and commits migration alone. Then take a fresh snapshot before any edit; never pass a caller-created legacy snapshot or version.
+- run-edit-script: inspect timeline.snapshot(), entities.*, and relations.*; edit.* operates existing Entity ids and creates the required Clip/SequenceMarker structural graph. Asset import, media Entity creation, generated Relations and timeline edits belong in ONE plan. The sandbox has no network, storage or generation access. Pass recalled generation/asset facts through inputs. A successful run returns preview, logs, base revision and plan_id.
+- commit-plan: commit the complete Entity/Relation plan through revision CAS. The server derives the read-only timeline projection in the same transaction. There is no separate writable timeline plan and no preflight replay into a legacy editor. A failed transport is unconfirmed, never committed; retry the same plan_id.
 
 Default flow: snapshot → run-edit-script with auto_commit=false → inspect preview → commit-plan. Use auto_commit=true only for low-risk edits when the host does not need user confirmation. On version mismatch, rerun snapshot and the script; never try to patch a rejected journal by hand.
+
+Generating an Asset alone does not require an Entity. Using that resource in the editor DOES: recall the Asset facts, reuse or create the appropriate media Entity and physical-asset Relation, then pass the media Entity id to edit.insertClip. A raw asset id or URL is not valid contentEntityId. Asset and media Entity identity are not one-to-one. Recall generation history and author known generated(output,input) relations in the same plan; do not invent an input for text-only generation. relations.of(entityId) is endpoint-agnostic.
 `.trim();
 const MEDEO_TOOL_EXECUTION_RULES = `
 The host supplies the current document. Do not ask for, invent, or pass a document id.
-Use timeline.snapshot() for the whole draft projection. Its duration is timeline.snapshot().timeline?.duration_ms; there is no top-level duration_ms.
+timeline.snapshot() returns the Entity/Relation graph with its revision, not a legacy VideoDraft. Inspect Timeline, Track, Clip, SequenceMarker and their relations to plan edits.
+Generation lineage and Memota asset facts are host-provided through inputs. Never invent an asset id, Entity kind, or peer Entity id.
+Before importing an Asset, call entities.findByAssetId(assetId), inspect every match, and decide whether an existing Entity represents the intended logical asset. Multiple matches are valid; do not assume Asset↔media is one-to-one.
+For recalled video/audio/voice, create a bounded/native payload whose extent end comes from factual media duration/coordinates in inputs; never fabricate a duration. Image uses unbounded/constant semantics and has no invented end. If required facts are absent, do not create the media Entity yet.
+For physical-asset authoring, use sequence media as endpoint_0_entity_id and Asset as endpoint_1_entity_id. For generated lineage, use linkGenerated so endpoint 0 is output and endpoint 1 is input. relations.of remains endpoint-agnostic for lookup.
+The compatibility reader supports the existing four Track roles: video_clip (Image/Video), speech (Voice), caption (Caption), and bgm (Audio), one of each. Clip.volume is decibels (-60 to 20, 0 = original). Marker.sourceRange is the selected source interval; Marker.duration is effective display/playback duration. Coordinates and duration are whole milliseconds for this reader, not a global DSL restriction. Placement is exactly one of Clip.order, Marker.targetRange, or clip-anchor(child,host) plus Marker.anchorOffset. Use the native move/delete/voiceover helpers so placement and cascade decisions are in the same entity plan. Reading the graph never rebinds anchors or invents empty clips. Linear timeRemapping is {kind:'linear',rate:2,mode:'constant'} and agrees with rounded source span divided by rate. Image remains unbounded/constant; an explicit linear rate scales its display window, not an invented media extent. Nonlinear speed and multiple visual overlay tracks are unsupported.
+Voice links to AudioScript through audio-script-render(output,script). Caption owns text/style and is placed through a Clip anchored to the Voice Clip; caption alignment/provenance agree with that Voice/AudioScript. BGM Audio keeps factual source duration and its Marker declares durationPolicy:'timeline'. External Asset identity and storageKey are distinct from the placed Clip identity. Never introduce a speech entity kind.
+Create only the known entity kinds. On an empty document, explicitly create Timeline and Track(role='video_clip') and connect timeline-track before inserting a Clip. If snapshot reports legacy migration is required, recall the listed asset facts and call migrate-legacy first. Missing facts, unsupported layouts, and version conflicts fail closed; never fall back to an old timeline method or raw update endpoint.
 Use only the globals and methods declared by the following TypeScript interface. Values not declared here are unavailable.
 `.trim();
 /** Render the complete MEngine-owned context injected before one model call. */
@@ -960,15 +986,51 @@ When updated_since_previous_model_call is true, the document changed after the p
 
 Sandbox TypeScript interface:
 \`\`\`ts
-${EDIT_SANDBOX_API_DTS}
+${ENTITY_EDIT_SANDBOX_API_DTS}
 \`\`\`
 `.trim();
 }
 //#endregion
 //#region src/schema.ts
 const MEDEO_TOOL_NAME = "medeo";
+const assetFactProperties = {
+	assetId: {
+		type: "string",
+		minLength: 1
+	},
+	kind: {
+		type: "string",
+		enum: [
+			"image",
+			"video",
+			"audio",
+			"voice"
+		]
+	},
+	durationMs: {
+		type: "integer",
+		minimum: 1
+	},
+	storageKey: {
+		type: "string",
+		minLength: 1
+	},
+	voice: {
+		type: "object",
+		additionalProperties: false,
+		required: ["system", "key"],
+		properties: {
+			system: { const: "voice-library" },
+			key: {
+				type: "string",
+				minLength: 1
+			},
+			name: { type: "string" }
+		}
+	}
+};
 /**
-* JSON Schema for the host-facing three-op `medeo` tool surface.
+* JSON Schema for the host-facing `medeo` tool surface.
 *
 * The schema intentionally does not return or accept the full op journal:
 * journals stay in the tool process and are referenced by `plan_id`. This keeps
@@ -984,6 +1046,7 @@ const MEDEO_TOOL_PARAMETERS = {
 			type: "string",
 			enum: [
 				"snapshot",
+				"migrate-legacy",
 				"run-edit-script",
 				"commit-plan"
 			],
@@ -997,11 +1060,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 generation lineage and asset facts. Generation and network IO must happen in the host before this call."
+		},
+		asset_facts: {
+			type: "array",
+			description: "Factual asset metadata recalled by the host for migrate-legacy only. The package reads the canonical legacy snapshot and version itself; never supply a clip trim window as media duration.",
+			items: { oneOf: [
+				{
+					type: "object",
+					additionalProperties: false,
+					required: ["assetId", "kind"],
+					properties: {
+						assetId: assetFactProperties.assetId,
+						kind: { const: "image" },
+						storageKey: assetFactProperties.storageKey
+					}
+				},
+				{
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"assetId",
+						"kind",
+						"durationMs"
+					],
+					properties: {
+						assetId: assetFactProperties.assetId,
+						kind: { const: "video" },
+						durationMs: assetFactProperties.durationMs,
+						storageKey: assetFactProperties.storageKey
+					}
+				},
+				{
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"assetId",
+						"kind",
+						"durationMs",
+						"storageKey"
+					],
+					properties: {
+						assetId: assetFactProperties.assetId,
+						kind: { const: "audio" },
+						durationMs: assetFactProperties.durationMs,
+						storageKey: assetFactProperties.storageKey
+					}
+				},
+				{
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"assetId",
+						"kind",
+						"durationMs",
+						"storageKey",
+						"voice"
+					],
+					properties: {
+						...assetFactProperties,
+						kind: { const: "voice" }
+					}
+				}
+			] }
 		},
 		timeout_ms: {
 			type: "integer",
@@ -1024,11 +1149,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 +1211,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 +1256,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 +1318,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 +1434,18 @@ function parseInput(value) {
 		op,
 		doc_id: docId
 	};
+	if (op === "migrate-legacy") {
+		if (Object.keys(value).some((key) => ![
+			"op",
+			"doc_id",
+			"asset_facts"
+		].includes(key))) throw new Error("migrate-legacy accepts asset_facts only; the package reads the canonical document and version");
+		return {
+			op,
+			doc_id: docId,
+			asset_facts: parseMigrationAssetFacts(value.asset_facts)
+		};
+	}
 	if (op === "run-edit-script") {
 		if (typeof value.script !== "string" || value.script.length === 0) throw new Error("script must be a non-empty string");
 		if (value.inputs !== void 0 && !isRecord(value.inputs)) throw new Error("inputs must be an object");
@@ -1199,58 +1479,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,8 +1563,11 @@ 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) {
 		const planId = randomUUID();
@@ -1273,109 +1576,242 @@ function createMedeoTool(options) {
 			plan
 		});
 		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) {
+		if (result.kind === "unconfirmed") {
+			pendingPushes.set(docId, plan.plan_kind === "timeline" ? {
+				kind: "timeline",
+				planId,
+				plan,
+				opsApplied: result.ops_applied
+			} : {
+				kind: "entities",
+				planId,
+				plan
+			});
+			return;
+		}
+		pendingPushes.delete(docId);
+		if (plan.plan_kind === "timeline" && result.kind === "rejected" && result.reason === "push_rejected") documents.delete(docId);
+	}
+	async function fetchEntityStateForSandbox(docId) {
+		return await getEntityClient(docId).fetchState();
+	}
+	async function commitCachedPlan(docId, _doc, plan, validation) {
+		if (plan.plan_kind === "timeline") throw new Error("Legacy timeline plans are not editable; use an Entity/Relation plan");
+		if (validation === "preflight") throw new Error("Entity plans use revision CAS; validation=preflight is not supported");
+		if (plan.entity_rows === void 0) throw new Error("entity plan is missing its authoritative rows");
+		return await commitEntityPlan(getEntityClient(docId), plan);
+	}
+	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 Promise.all([observePull(doc), fetchEntityStateForSandbox(docId)]);
+			const documentVersion = `${encodeDocVersionMark(doc.versionMark())}:entities:${entityState.revision}`;
+			const baselineKey = `${contextId}\u0000${docId}`;
+			const previousVersion = modelContextVersions.get(baselineKey);
+			const updatedSincePreviousModelCall = previousVersion == null ? null : previousVersion !== documentVersion;
+			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, entityState] = await Promise.all([observePull(doc), fetchEntityStateForSandbox(input.doc_id)]);
+			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 = new EntityGraphHttpClient({
+				docId: input.doc_id,
+				httpOrigin: requiredContext(options.httpOrigin, input.doc_id, "httpOrigin"),
+				...options.authToken === void 0 ? {} : { authToken: () => optionalContext(options.authToken, input.doc_id) },
+				...options.userId === void 0 ? {} : { userId: () => optionalContext(options.userId, input.doc_id) },
+				...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl }
+			});
+			const base = await client.fetchState();
+			if (base.rows.entities.some((row) => row.entityKind === "timeline")) return {
+				ok: true,
+				op: "migrate-legacy",
+				doc_id: input.doc_id,
+				migration_status: "already_entity",
+				entity_revision: base.revision,
+				next_action: "snapshot"
+			};
+			const pull = await doc.pull();
+			if (!pull.ok) throw new Error(`Migration requires a fresh canonical snapshot: ${pull.error.message}`);
+			const migrationBaseVv = encodeDocVersionMark(doc.versionMark());
+			const nextRows = migrateLegacyTimelineToEntities(doc.snapshot(), input.asset_facts, base.rows);
+			let revision;
+			try {
+				revision = (await client.commit(base, nextRows, { migrationBaseVv })).revision;
+			} catch (error) {
+				if (error instanceof MengineHttpRequestError) throw new Error(`Migration rejected (HTTP ${error.status}): ${entityHttpErrorMessage(error.payload)}; take a fresh snapshot before retrying`);
+				throw new Error("Migration submission is unconfirmed; take a fresh snapshot and retry migrate-legacy to inspect whether the Entity timeline already exists");
+			}
+			documents.delete(input.doc_id);
+			for (const [id, cached] of plans) if (cached.docId === input.doc_id) plans.delete(id);
+			return {
+				ok: true,
+				op: "migrate-legacy",
+				doc_id: input.doc_id,
+				migration_status: "committed",
+				entity_revision: revision,
+				next_action: "snapshot"
+			};
+		});
 	}
 	async function run(input) {
-		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, entityState] = await Promise.all([observePull(doc), fetchEntityStateForSandbox(input.doc_id)]);
+			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);
+			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);
+			recordPushResult(input.doc_id, planId, plan, commit);
+			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);
+				recordPushResult(input.doc_id, input.plan_id, pending.plan, result);
+				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);
+			recordPushResult(input.doc_id, input.plan_id, cached.plan, result);
+			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 +1822,7 @@ function createMedeoTool(options) {
 			try {
 				const parsed = parseInput(input);
 				if (parsed.op === "snapshot") return await snapshot(parsed);
+				if (parsed.op === "migrate-legacy") return await migrate(parsed);
 				if (parsed.op === "run-edit-script") return await run(parsed);
 				return await commit(parsed);
 			} catch (error) {
@@ -1398,18 +1835,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");
 		}
 	};
 }