@mengine/medeo-tool 1.2.1-alpha.0 → 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-DdPA4tTf.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,6 +176,150 @@ 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
@@ -359,6 +522,9 @@ const EDIT_SANDBOX_API_DTS = [
 	"  }[];",
 	"}",
 	"",
+	"/**",
+	" * 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.",
@@ -585,6 +751,9 @@ const EDIT_SANDBOX_API_DTS = [
 	"  }[];",
 	"}",
 	"",
+	"/**",
+	" * 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",
@@ -840,6 +1009,7 @@ const EDIT_SANDBOX_API_DTS = [
 	"/** 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. */",
@@ -849,6 +1019,7 @@ const EDIT_SANDBOX_API_DTS = [
 	"  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>;",
@@ -873,6 +1044,185 @@ const EDIT_SANDBOX_API_DTS = [
 	"  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;",
@@ -918,30 +1268,38 @@ const EDIT_SANDBOX_API_DTS = [
 	"",
 	"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 script arguments (opaque). */",
-	"export declare const inputs: unknown;",
+	"/** 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. */
@@ -997,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",
@@ -1025,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: [
@@ -1073,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;
@@ -1120,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) {
@@ -1156,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;
@@ -1199,58 +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;
@@ -1263,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();
@@ -1273,109 +1761,208 @@ 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) {
+		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 {
+			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) => {
+			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) {
-		const session = await getSession(input.doc_id);
-		const document = session.snapshot();
-		return {
-			ok: true,
-			op: "snapshot",
-			doc_id: input.doc_id,
-			version: session.version(),
-			preview: renderCompactProjection(document)
-		};
+		return runExclusive(input.doc_id, async (doc) => {
+			assertNoPendingPush(input.doc_id);
+			const pull = await observePull(doc);
+			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 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,
@@ -1398,18 +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");
 		}
 	};
 }