@mengine/medeo-tool 1.0.1-alpha.2 → 1.2.1-alpha.7

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { i as renderCompactProjection, n as collectAffectedPartIds, r as renderPreview, t as EditSandboxSession } from "./script-session-B8fc9Ccb.mjs";
-import { MengineDocSession, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, replayJournal, toVideoDocument } from "@mengine/medeo-client";
+import { i as renderCompactProjection, n as collectAffectedPartIds, r as renderPreview, t as EditSandboxSession } from "./script-session-BF44uKv_.mjs";
+import { ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, replayJournal, toVideoDocument } from "@mengine/medeo-client";
 import { 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,6 +34,7 @@ function runEditScript(options) {
 				document: options.document,
 				script: options.script,
 				inputs: options.inputs,
+				entityState: options.entityState,
 				idLabel: options.idLabel
 			},
 			execArgv: resolveRegisterUrl.pathname.endsWith(".ts") ? [
@@ -54,6 +56,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 +84,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 +96,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 +117,13 @@ 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 } : {},
 						preview: message.preview,
 						logs: logs.slice()
 					},
@@ -121,6 +137,7 @@ function runEditScript(options) {
 				error: message.error,
 				partial: {
 					ops: ops.slice(),
+					entityCommands: entityCommands.slice(),
 					logs: logs.slice()
 				}
 			});
@@ -137,6 +154,7 @@ function runEditScript(options) {
 				},
 				partial: {
 					ops: ops.slice(),
+					entityCommands: entityCommands.slice(),
 					logs: logs.slice()
 				}
 			});
@@ -150,6 +168,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,17 +176,1152 @@ function runEditScript(options) {
 	});
 }
 //#endregion
+//#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"
+];
+//#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) {
+		return toSnapshot(await this.requestJson({
+			method: "POST",
+			body: JSON.stringify({
+				expected_revision: expectedRevision,
+				rows: {
+					entities: state.entities,
+					relations: state.relations
+				}
+			})
+		}), 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/sandbox/generated/edit-sandbox-model-context.ts
+/**
+* @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY
+*
+* Runtime copy of the sandbox TypeScript disclosure. The model prompt imports
+* this value so its interface and the checked-in declaration cannot drift.
+*/
+const EDIT_SANDBOX_API_DTS = [
+	"/**",
+	" * @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY",
+	" *",
+	" * Schema version: video-document/v0",
+	" * Semantic ops: 20",
+	" *",
+	" * Boundary: zod `superRefine` / custom refine rules are NOT introspectable and",
+	" * do not appear here. Business mutual-exclusion rules surface via runtime",
+	" * validation errors (L3 feedback channel).",
+	" *",
+	" * @example 读取→计算→批量写",
+	" * ```ts",
+	" * const clips = timeline.clipsInRange(0, 10_000);",
+	" * await edit.setVideoClipSpeedShift({",
+	" *   clips: clips.map((c) => ({ clip_id: c.id, speed_shift: { category: 'linear', mode: 'constant', config: { linear: { speed: 1.5 } } } })),",
+	" * });",
+	" * ```",
+	" *",
+	" * @example anchored 删除",
+	" * ```ts",
+	" * await edit.deleteVideoClips({ clip_ids: ['clip_a'], on_anchored: 'detach' });",
+	" * ```",
+	" */",
+	"",
+	"/**",
+	" * A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.",
+	" */",
+	"export interface SpeedShift {",
+	"  category: 'linear' | 'curve';",
+	"  mode: string;",
+	"  config:",
+	"    | {",
+	"        linear: {",
+	"          /**",
+	"           * @constraint positive",
+	"           */",
+	"          speed: number;",
+	"        };",
+	"      }",
+	"    | {",
+	"        curve: {",
+	"          /**",
+	"           * @constraint minLength(2)",
+	"           */",
+	"          keyframes: {",
+	"            /**",
+	"             * @constraint min(0)",
+	"             * @constraint max(1)",
+	"             */",
+	"            position: number;",
+	"            /**",
+	"             * @constraint min(0)",
+	"             */",
+	"            rate: number;",
+	"            /**",
+	"             * Bezier tangent handle (x, y)",
+	"             */",
+	"            in_tangent?: { x: number; y: number };",
+	"            /**",
+	"             * Bezier tangent handle (x, y)",
+	"             */",
+	"            out_tangent?: { x: number; y: number };",
+	"          }[];",
+	"        };",
+	"      };",
+	"}",
+	"",
+	"/**",
+	" * TTS voice summary attached to a speech",
+	" */",
+	"export interface Voice {",
+	"  /**",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  id: string;",
+	"  name: string;",
+	"}",
+	"",
+	"/**",
+	" * A materialized speech-subtree write (speeches + their captions).",
+	" */",
+	"export interface SpeechAssets {",
+	"  /**",
+	"   * Materialized speech parts to write",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  speeches: {",
+	"    /**",
+	"     * The speech part ID (= side-effect speech_parts[].id)",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    speech_id: string;",
+	"    /**",
+	"     * Host video clip part ID the speech anchors to (RFC 02 §4)",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    anchor_part_id: string;",
+	"    /**",
+	"     * Offset within the host clip (speech.abs = host.abs + offset_ms)",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    offset_ms: number;",
+	"    /**",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    audio_storage_key: string;",
+	"    /**",
+	"     * Duration in milliseconds (> 0)",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    duration_ms: number;",
+	"    audio_script: string;",
+	"    /**",
+	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)",
+	"     * @constraint min(-60)",
+	"     * @constraint max(20)",
+	"     */",
+	"    volume: number;",
+	"    /**",
+	"     * TTS voice summary attached to a speech",
+	"     */",
+	"    voice: {",
+	"      /**",
+	"       * @constraint minLength(1)",
+	"       */",
+	"      id: string;",
+	"      name: string;",
+	"    };",
+	"    /**",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    origin_speech_id: string;",
+	"    /**",
+	"     * Caption part IDs owned by this speech",
+	"     */",
+	"    caption_ids: string[];",
+	"  }[];",
+	"  /**",
+	"   * Materialized caption parts owned by the speeches",
+	"   */",
+	"  captions: {",
+	"    /**",
+	"     * The caption part ID (= side-effect created_caption_parts[].id)",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    caption_id: string;",
+	"    /**",
+	"     * The owning speech part ID",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    speech_part_id: string;",
+	"    text: string;",
+	"    /**",
+	"     * Offset within the host speech (caption.abs = speech.abs + start_ms)",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    start_ms: number;",
+	"    /**",
+	"     * Duration in milliseconds (> 0)",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    duration_ms: number;",
+	"  }[];",
+	"}",
+	"",
+	"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;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * Reorder a set of main-track clips relative to a reference clip.",
+	" */",
+	"export interface MoveVideoClipsByAnchorInput {",
+	"  /**",
+	"   * Clips to move as one block, keeping their relative order. Need not be contiguous on the track.",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clip_ids: string[];",
+	"  /**",
+	"   * Where the moved block lands: before/after a reference clip, or at the head of the track",
+	"   */",
+	"  anchor:",
+	"    | {",
+	"        position: 'before';",
+	"        /**",
+	"         * The moved block lands immediately before this clip",
+	"         * @constraint minLength(1)",
+	"         */",
+	"        clip_id: string;",
+	"      }",
+	"    | {",
+	"        position: 'after';",
+	"        /**",
+	"         * The moved block lands immediately after this clip",
+	"         * @constraint minLength(1)",
+	"         */",
+	"        clip_id: string;",
+	"      }",
+	"    | { position: 'track_start' };",
+	"  /**",
+	"   * What happens to speeches anchored to the moved clips (required — see the policy doc)",
+	"   */",
+	"  on_anchored: 'follow' | 'keep_absolute';",
+	"}",
+	"",
+	"export interface 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';",
+	"}",
+	"",
+	"/**",
+	" * 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 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;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * 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;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * 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;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * Replace a contiguous run of main-track clips with a new run.",
+	" */",
+	"export interface ReplaceVideoClipSequenceInput {",
+	"  /**",
+	"   * The clips being replaced: a contiguous main-track run, listed in timeline order",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  old_clip_ids: string[];",
+	"  /**",
+	"   * The replacement clips, in the order they take on the track",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  new_clips: {",
+	"    /**",
+	"     * The replacement media asset ID. Omit to create an empty placeholder clip.",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    media_id?: string;",
+	"    /**",
+	"     * The source media's intrinsic full length in ms",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    media_duration_ms: number;",
+	"    /**",
+	"     * Trim window start in the media (default 0)",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    play_in?: number;",
+	"    /**",
+	"     * Trim window end in the media (default media_duration_ms)",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    play_out?: number;",
+	"  }[];",
+	"  /**",
+	"   * What happens to speeches anchored to the replaced clips (required — see the policy doc)",
+	"   */",
+	"  on_anchored: 'remap' | 'cascade';",
+	"}",
+	"",
+	"/**",
+	" * 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;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * 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[];",
+	"}",
+	"",
+	"/**",
+	" * 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;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * 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;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * Toggle caption visibility (the caption track's `is_hidden` flag).",
+	" */",
+	"export interface SetCaptionVisibilityInput {",
+	"  /**",
+	"   * Whether the caption track is hidden",
+	"   */",
+	"  is_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;",
+	"}",
+	"",
+	"/**",
+	" * 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;",
+	"}",
+	"",
+	"/**",
+	" * Remove the document BGM.",
+	" */",
+	"export interface DeleteBgmInput {",
+	"  [key: string]: never;",
+	"}",
+	"",
+	"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;",
+	"  }[];",
+	"}",
+	"",
+	"/** Agent write surface — one method per SemanticOp kind. */",
+	"export interface EditApi {",
+	"  moveVideoClips(input: MoveVideoClipsInput): Promise<void>;",
+	"  /** Reorder a set of main-track clips relative to a reference clip. */",
+	"  moveVideoClipsByAnchor(input: MoveVideoClipsByAnchorInput): Promise<void>;",
+	"  deleteVideoClips(input: DeleteVideoClipsInput): Promise<void>;",
+	"  /** Add video clips to a track. */",
+	"  addVideoClips(input: AddVideoClipsInput): Promise<void>;",
+	"  adjustVideoClipVolume(input: AdjustVideoClipVolumeInput): Promise<void>;",
+	"  /** Set the playback speed of existing video clips. */",
+	"  setVideoClipSpeedShift(input: SetVideoClipSpeedShiftInput): Promise<void>;",
+	"  /** Replace the media backing existing video clips. */",
+	"  replaceVideoClipContent(input: ReplaceVideoClipContentInput): Promise<void>;",
+	"  /** Replace a contiguous run of main-track clips with a new run. */",
+	"  replaceVideoClipSequence(input: ReplaceVideoClipSequenceInput): Promise<void>;",
+	"  /** Re-trim existing video clips (the user-facing \"adjust duration\" gesture is a trim of the source window). */",
+	"  adjustVideoClipDuration(input: AdjustVideoClipDurationInput): Promise<void>;",
+	"  /** Add speeches (and their captions). */",
+	"  addSpeeches(input: AddSpeechesInput): Promise<void>;",
+	"  /** Delete speeches with their captions. */",
+	"  deleteSpeeches(input: DeleteSpeechesInput): Promise<void>;",
+	"  /** Move speeches in time. */",
+	"  moveSpeeches(input: MoveSpeechesInput): Promise<void>;",
+	"  /** Change a speech's script or voice. */",
+	"  changeSpeechScript(input: ChangeSpeechScriptInput): Promise<void>;",
+	"  changeSpeechVoice(input: ChangeSpeechVoiceInput): Promise<void>;",
+	"  adjustSpeechVolume(input: AdjustSpeechVolumeInput): Promise<void>;",
+	"  /** Toggle caption visibility (the caption track's `is_hidden` flag). */",
+	"  setCaptionVisibility(input: SetCaptionVisibilityInput): Promise<void>;",
+	"  /** Set the caption visual style. */",
+	"  setCaptionStyle(input: SetCaptionStyleInput): Promise<void>;",
+	"  /** Set the document BGM. */",
+	"  setBgm(input: SetBgmInput): Promise<void>;",
+	"  /** Remove the document BGM. */",
+	"  deleteBgm(input: DeleteBgmInput): Promise<void>;",
+	"  adjustBgmVolume(input: AdjustBgmVolumeInput): Promise<void>;",
+	"}",
+	"",
+	"export type JsonPrimitive = string | number | boolean | null;",
+	"export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];",
+	"export interface JsonObject {",
+	"  [key: string]: 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';",
+	"",
+	"export interface BoundedNativeSequencePayload extends JsonObject {",
+	"  /** Use factual recalled coordinates; never invent an end or duration. */",
+	"  extent: { kind: 'bounded'; start: number; end: number };",
+	"  sampling: 'native';",
+	"  coordinateSpace: JsonValue;",
+	"}",
+	"export interface UnboundedConstantSequencePayload extends JsonObject {",
+	"  extent: { kind: 'unbounded'; start: number };",
+	"  sampling: 'constant';",
+	"  coordinateSpace: JsonValue;",
+	"}",
+	"export interface BoundedDerivedSequencePayload extends JsonObject {",
+	"  extent: { kind: 'bounded'; start: number; end: number };",
+	"  sampling: 'derived';",
+	"  coordinateSpace: JsonValue;",
+	"}",
+	"export type ScriptTextSegment = JsonObject & {",
+	"  segmentId: string;",
+	"  text: string;",
+	"  language?: string;",
+	"};",
+	"",
+	"export interface EntityPayloadByKind {",
+	"  axvideo: BoundedDerivedSequencePayload;",
+	"  timeline: JsonObject;",
+	"  track: JsonObject & { hidden?: boolean; role?: string };",
+	"  clip: JsonObject;",
+	"  asset: JsonObject;",
+	"  video: BoundedNativeSequencePayload;",
+	"  audio: BoundedNativeSequencePayload;",
+	"  voice: BoundedNativeSequencePayload;",
+	"  image: UnboundedConstantSequencePayload;",
+	"  'sequence-marker': JsonObject & {",
+	"    sourceRange: { start: number; end: number };",
+	"    targetRange?: { start: number; end: number };",
+	"    duration: { mode: 'from-source' } | { mode: 'fixed'; value: number };",
+	"    timeRemapping?: JsonValue;",
+	"  };",
+	"  viewport: JsonObject;",
+	"  'audio-script': JsonObject & { segments: ScriptTextSegment[] };",
+	"  'phonetic-script': JsonObject & { segments: ScriptTextSegment[] };",
+	"  caption: BoundedNativeSequencePayload;",
+	"}",
+	"",
+	"export type CreateEntityInput = {",
+	"  [K in KnownEntityKind]: {",
+	"    entity_id?: string;",
+	"    entity_kind: K;",
+	"    payload: EntityPayloadByKind[K];",
+	"  };",
+	"}[KnownEntityKind];",
+	"",
+	"export interface ImportAssetInput {",
+	"  asset_id: string;",
+	"  entity_id?: string;",
+	"  payload?: JsonObject;",
+	"}",
+	"",
+	"export interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {",
+	"  entity_id: string;",
+	"  entity_kind: K;",
+	"  payload: EntityPayloadByKind[K];",
+	"}",
+	"",
+	"export interface SandboxRelation {",
+	"  relation_id: string;",
+	"  relation_kind: KnownRelationKind;",
+	"  endpoint_0_entity_id: string;",
+	"  endpoint_1_entity_id: string;",
+	"  metadata: JsonObject;",
+	"  trace: JsonObject;",
+	"}",
+	"",
+	"export type EmptyRelationKind =",
+	"  | 'timeline-track'",
+	"  | 'track-clip'",
+	"  | 'clip-marker'",
+	"  | 'marker-content'",
+	"  | 'axvideo-marker'",
+	"  | 'marker-timeline';",
+	"export type LinkRelationInput =",
+	"  | {",
+	"      relation_id?: string;",
+	"      relation_kind: EmptyRelationKind;",
+	"      endpoint_0_entity_id: string;",
+	"      endpoint_1_entity_id: string;",
+	"      metadata?: { [key: string]: never };",
+	"      trace?: JsonObject;",
+	"    }",
+	"  | {",
+	"      relation_id?: string;",
+	"      relation_kind: 'physical-asset';",
+	"      /** Canonical endpoint 0 is sequence media; endpoint 1 is Asset. */",
+	"      endpoint_0_entity_id: string;",
+	"      endpoint_1_entity_id: string;",
+	"      metadata?: JsonObject;",
+	"      trace?: JsonObject;",
+	"    }",
+	"  | {",
+	"      relation_id?: string;",
+	"      relation_kind: 'phonetic-script-provenance' | 'caption-provenance';",
+	"      endpoint_0_entity_id: string;",
+	"      endpoint_1_entity_id: string;",
+	"      metadata: JsonObject & { segmentAlignment: JsonValue };",
+	"      trace?: JsonObject;",
+	"    }",
+	"  | {",
+	"      relation_id?: string;",
+	"      relation_kind: 'caption-alignment';",
+	"      endpoint_0_entity_id: string;",
+	"      endpoint_1_entity_id: string;",
+	"      metadata: JsonObject & { alignment: JsonValue };",
+	"      trace?: JsonObject;",
+	"    };",
+	"",
+	"export interface LinkGeneratedRelationInput {",
+	"  relation_id?: string;",
+	"  /** Generated output media Entity; persisted as endpoint 0. */",
+	"  output_entity_id: string;",
+	"  /** Input media Entity used to generate the output; persisted as endpoint 1. */",
+	"  input_entity_id: string;",
+	"  trace?: JsonObject;",
+	"}",
+	"",
+	"/** Explicit Entity authoring. Assets and media Entities are not one-to-one. */",
+	"export interface EntityApi {",
+	"  list(): SandboxEntity[];",
+	"  get(entityId: string): SandboxEntity | null;",
+	"  /** Call before importAsset; inspect every match and decide whether to reuse one. */",
+	"  findByAssetId(assetId: string): SandboxEntity<'asset'>[];",
+	"  create(input: CreateEntityInput): string;",
+	"  /** Create only an Asset Entity when no existing match should be reused; this does not infer media. */",
+	"  importAsset(input: ImportAssetInput): string;",
+	"}",
+	"",
+	"/** Incident reads ignore endpoint position; relation semantics preserve it. */",
+	"export interface RelationApi {",
+	"  list(): SandboxRelation[];",
+	"  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];",
+	"  link(input: LinkRelationInput): string;",
+	"  /** Author ordered generated(output,input). */",
+	"  linkGenerated(input: LinkGeneratedRelationInput): string;",
+	"}",
+	"",
+	"/** 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;",
+	"}",
+	"",
+	"/** 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;",
+	"}",
+	"",
+	"/** 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;",
+	"}",
+	"",
+	"/** Opaque checkpoint handle for rollback. */",
+	"export interface SandboxCheckpoint {",
+	"  readonly index: number;",
+	"}",
+	"",
+	"export declare const edit: EditApi;",
+	"export declare const timeline: TimelineApi;",
+	"export declare const entities: EntityApi;",
+	"export declare const relations: RelationApi;",
+	"",
+	"/** Capture a rollback point. */",
+	"export declare function checkpoint(): SandboxCheckpoint;",
+	"/** Roll the sandbox document back to a prior checkpoint. */",
+	"export declare function rollbackTo(cp: SandboxCheckpoint): void;",
+	"/** Host-injected, pre-materialized facts. Validate each field before use. */",
+	"export declare const inputs: Readonly<Record<string, unknown>>;",
+	""
+].join("\n");
+//#endregion
 //#region src/prompt.ts
 const MEDEO_TOOL_DESCRIPTION = `
-Edit a Medeo video document through a deterministic, side-effect-free JavaScript sandbox.
+Edit a Medeo video document and its explicit Entity/Relation state through a deterministic, side-effect-free JavaScript sandbox.
 
 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.
+- run-edit-script: execute JavaScript against forked timeline and Entity/Relation snapshots. Inspect timeline.*, entities.*, and relations.*; call edit.* for timeline mutations or the explicit entity APIs for domain mutations. The sandbox has no network, storage, clock, or generation access. Pass recalled generation/asset facts through inputs. A successful run returns preview, logs, plan_kind, base versions, and plan_id — not the full journals.
+- commit-plan: commit a cached plan_id. Timeline plans replay into ManualSyncDoc and push one causally complete update; Entity plans replace the authoritative row set through revision CAS. validation=preflight is timeline-only. A failed transport is unconfirmed, never committed; retry the same plan_id.
 
 Default flow: snapshot → run-edit-script with auto_commit=false → inspect preview → commit-plan. Use auto_commit=true only for low-risk edits when the host does not need user confirmation. On version mismatch, rerun snapshot and the script; never try to patch a rejected journal by hand.
+
+One plan must mutate exactly one store: timeline or Entity/Relation state. If both are needed, author and commit two separate plans. There is no automatic Asset→Entity projection: select the relevant recalled fact, explicitly import an Asset if useful, explicitly create only known typed Entities, and author relations. Asset and media Entity identity are not one-to-one. relations.linkGenerated({ output_entity_id, input_entity_id }) means generated(output,input); incident lookup with relations.of(entityId) is endpoint-agnostic.
 `.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.
+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.
+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. */
+function renderMedeoModelContext(input) {
+	const updated = input.updatedSincePreviousModelCall == null ? "unknown (first model call)" : String(input.updatedSincePreviousModelCall);
+	return `
+${MEDEO_TOOL_DESCRIPTION}
+
+${MEDEO_TOOL_EXECUTION_RULES}
+
+Current MEngine document state (sampled dynamically immediately before this model call):
+- document_version: ${JSON.stringify(input.documentVersion)}
+- updated_since_previous_model_call: ${updated}
+
+When updated_since_previous_model_call is true, the document changed after the previous model call. The change may have come from this tool or another editor, so take a fresh snapshot before planning further edits.
+
+Sandbox TypeScript interface:
+\`\`\`ts
+${EDIT_SANDBOX_API_DTS}
+\`\`\`
+`.trim();
+}
 //#endregion
 //#region src/schema.ts
 const MEDEO_TOOL_NAME = "medeo";
@@ -201,11 +1355,11 @@ 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. It receives edit, timeline, entities, relations, checkpoint, rollbackTo, inputs, and console. A plan may mutate the timeline or Entity/Relation state, never both."
 		},
 		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."
 		},
 		timeout_ms: {
 			type: "integer",
@@ -229,7 +1383,7 @@ 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."
+			description: "Timeline commit mode: version rejects any concurrent change; preflight revalidates each op. Entity plans always use revision CAS and reject preflight."
 		}
 	},
 	oneOf: [
@@ -277,39 +1431,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;
@@ -324,15 +1476,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) {
@@ -347,6 +1525,7 @@ function opConflict(index, op_kind, message) {
 //#endregion
 //#region src/host-tool.ts
 const DEFAULT_MAX_PLANS = 16;
+const DEFAULT_MAX_MODEL_CONTEXTS = 128;
 function isRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -359,6 +1538,89 @@ 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;
 }
+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);
+		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) {
+				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 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;
@@ -402,56 +1664,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;
@@ -464,8 +1748,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();
@@ -474,85 +1761,214 @@ 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;
 	}
-	async function snapshot(input) {
-		const session = await getSession(input.doc_id);
-		const document = session.snapshot();
+	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) {
+		try {
+			return await getEntityClient(docId).fetchState();
+		} catch (error) {
+			if (error instanceof MengineEntityHttpRequestError && error.status === 404) return {
+				revision: 0,
+				entities: [],
+				relations: []
+			};
+			throw error;
+		}
+	}
+	async function commitCachedPlan(docId, doc, plan, validation) {
+		if (plan.plan_kind === "timeline") return await commitPlan(doc, plan, validation === void 0 ? void 0 : { validation });
+		if (validation === "preflight") throw new Error("validation=preflight applies only to timeline plans; entity plans use revision CAS");
+		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 {
-			ok: true,
-			op: "snapshot",
-			doc_id: input.doc_id,
-			version: session.version(),
-			preview: renderCompactProjection(document)
+			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");
+		return await runExclusive(docId, async (doc) => {
+			await observePull(doc);
+			const documentVersion = encodeDocVersionMark(doc.versionMark());
+			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) {
+		return runExclusive(input.doc_id, async (doc) => {
+			assertNoPendingPush(input.doc_id);
+			const pull = await observePull(doc);
+			return {
+				ok: true,
+				op: "snapshot",
+				doc_id: input.doc_id,
+				version: encodeDocVersionMark(doc.versionMark()),
+				preview: renderCompactProjection(doc.snapshot()),
+				collaborated: pull.collaborated,
+				...pull.warnings !== void 0 ? { warnings: pull.warnings } : {}
+			};
+		});
+	}
 	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,
+				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 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 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,
 		description: MEDEO_TOOL_DESCRIPTION,
 		parameters: MEDEO_TOOL_PARAMETERS,
+		getModelContext,
 		async handle(input) {
 			try {
 				const parsed = parseInput(input);
@@ -569,17 +1985,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");
 		}
 	};
 }