@mengine/medeo-tool 1.3.1-alpha.9 → 1.4.1-alpha.1

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { c as renderPreview, l as renderCompactProjection, n as EntitySandbox, o as isMediaAssetVariantKind, r as toDslRows, s as collectAffectedPartIds, t as EditSandboxSession } from "./script-session-B2UQ1W_y.mjs";
-import { EntityGraphHttpClient, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, migrateLegacyTimelineToEntities, replayJournal, toVideoDocument } from "@mengine/medeo-client";
+import { a as createEntityId, c as collectAffectedPartIds, i as businessState, l as renderPreview, n as EntitySandbox, o as createRelationId, s as isMediaAssetVariantKind, t as EditSandboxSession, u as renderCompactProjection } from "./script-session-AukLN7x7.mjs";
+import { LoroEntityDocument, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, base64ToBytes, bytesToBase64, compileEntityRows, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, ensureEditorFoundation, replayJournal, toVideoDocument } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 //#region src/sandbox/node-host.ts
 const DEFAULT_TIMEOUT_MS = 2e3;
 const DEFAULT_MEMORY_MB = 256;
@@ -122,6 +122,7 @@ function runEditScript(options) {
 						doc_id: options.document.meta.draft_id ?? "",
 						base_version: options.baseVersion,
 						ops: ops.slice(),
+						...message.loroUpdate ? { loro_update: message.loroUpdate } : {},
 						entity_base_revision: message.entityBaseRevision,
 						entity_commands: entityCommands.slice(),
 						...message.entityRows !== void 0 ? { entity_rows: message.entityRows } : {},
@@ -179,6 +180,78 @@ function runEditScript(options) {
 	});
 }
 //#endregion
+//#region src/entity/caption-asset-assembly.ts
+/** Assemble optional infrastructure after business execution, using exact entity identity. */
+async function assembleCaptionAssets(input) {
+	try {
+		const state = await input.client.fetchState();
+		const candidates = state.entities.filter((entity) => entity.entity_kind === "caption" && !state.relations.some((relation) => relation.relation_kind === "physical-asset" && (relation.endpoint_0_entity_id === entity.entity_id || relation.endpoint_1_entity_id === entity.entity_id)));
+		if (!candidates.length) return { status: "current" };
+		const ids = new Set(candidates.map((entity) => entity.entity_id));
+		const facts = await input.loadAssets(input.docId, [...ids]);
+		const entities = [...state.entities];
+		const relations = [...state.relations];
+		const bound = /* @__PURE__ */ new Map();
+		for (const fact of facts) {
+			if (!ids.has(fact.captionEntityId) || !trimmed(fact.assetId) || !trimmed(fact.storageKey)) throw new Error("Caption Asset fact must identify a requested Caption and a real Asset locator");
+			const previous = bound.get(fact.captionEntityId);
+			if (previous !== void 0) {
+				if (previous !== fact.assetId) throw new Error(`Conflicting Assets for Caption ${fact.captionEntityId}`);
+				continue;
+			}
+			bound.set(fact.captionEntityId, fact.assetId);
+			const matches = entities.filter((entity) => {
+				const external = entity.payload.external;
+				return external !== null && typeof external === "object" && !Array.isArray(external) && external.system === "memota" && external.key === fact.assetId;
+			});
+			if (matches.length > 1 || matches[0] && matches[0].entity_kind !== "asset") throw new Error(`Conflicting resource identity for Caption Asset ${fact.assetId}`);
+			let asset = matches[0];
+			if (asset && asset.payload.storageKey !== fact.storageKey) throw new Error(`Conflicting storage key for Caption Asset ${fact.assetId}`);
+			if (!asset) {
+				asset = {
+					entity_id: stableId$1("asset", fact.assetId),
+					entity_kind: "asset",
+					payload: {
+						external: {
+							system: "memota",
+							key: fact.assetId
+						},
+						storageKey: fact.storageKey
+					}
+				};
+				if (entities.some((entity) => entity.entity_id === asset.entity_id)) throw new Error("Caption Asset identity collision");
+				entities.push(asset);
+			}
+			relations.push({
+				relation_id: stableId$1("relation", fact.captionEntityId, asset.entity_id),
+				relation_kind: "physical-asset",
+				endpoint_0_entity_id: fact.captionEntityId,
+				endpoint_1_entity_id: asset.entity_id,
+				metadata: {},
+				trace: {}
+			});
+		}
+		if (!bound.size) return { status: "current" };
+		await input.client.commit(state.revision, {
+			...state,
+			entities,
+			relations
+		});
+		return { status: "applied" };
+	} catch (error) {
+		return {
+			status: "failed",
+			message: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+function stableId$1(prefix, ...parts) {
+	return `${prefix}_${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
+}
+function trimmed(value) {
+	return typeof value === "string" && value.length > 0 && value.trim() === value;
+}
+//#endregion
 //#region src/entity/entity-contract.ts
 const KNOWN_ENTITY_KINDS = [
 	"axvideo",
@@ -226,7 +299,7 @@ var MengineEntityHttpRequestError = class extends Error {
 		this.name = "MengineEntityHttpRequestError";
 	}
 };
-/** Narrow authenticated client for the entity-store CAS endpoint. */
+/** Narrow authenticated client for the Loro entity endpoint. */
 var EntityHttpClient = class {
 	options;
 	fetchImpl;
@@ -237,18 +310,30 @@ var EntityHttpClient = class {
 	async fetchState() {
 		return toSnapshot(await this.requestJson({ method: "GET" }), this.options.docId);
 	}
-	async commit(expectedRevision, state, deletions = {}) {
+	async commit(_transportSequence, state, _deletions = {}) {
+		if (!state.loroSnapshot) throw new Error("Entity edit is missing its causal Loro baseline");
+		const rows = {
+			entities: state.entities.map((row) => ({
+				entityId: createEntityId(row.entity_id),
+				entityKind: row.entity_kind,
+				payload: row.payload
+			})),
+			relations: state.relations.map((row) => ({
+				relationId: createRelationId(row.relation_id),
+				relationKind: row.relation_kind,
+				endpoint0EntityId: createEntityId(row.endpoint_0_entity_id),
+				endpoint1EntityId: createEntityId(row.endpoint_1_entity_id),
+				metadata: row.metadata,
+				trace: row.trace
+			}))
+		};
+		const compiled = compileEntityRows(base64ToBytes(state.loroSnapshot), rows);
+		return this.commitUpdate(bytesToBase64(compiled.update));
+	}
+	async commitUpdate(update) {
 		return toSnapshot(await this.requestJson({
 			method: "POST",
-			body: JSON.stringify({
-				expected_revision: expectedRevision,
-				rows: {
-					entities: state.entities,
-					relations: state.relations
-				},
-				deleted_entity_ids: [...deletions.deleted_entity_ids ?? []],
-				deleted_relation_ids: [...deletions.deleted_relation_ids ?? []]
-			})
+			body: JSON.stringify({ update })
 		}), this.options.docId);
 	}
 	async requestJson(init) {
@@ -279,12 +364,13 @@ function toSnapshot(value, expectedDocId) {
 	if (!isRecord$2(value) || typeof value.doc_id !== "string" || !isNonNegativeInteger(value.revision)) throw new Error("invalid entity-state response envelope");
 	if (value.doc_id !== expectedDocId) throw new Error(`entity-state response doc_id mismatch: expected "${expectedDocId}"`);
 	if (!isRecord$2(value.rows) || !Array.isArray(value.rows.entities) || !Array.isArray(value.rows.relations)) throw new Error("invalid entity-state response rows");
-	if (value.audio_script_entity_id === null) {
-		if (value.revision !== 0) throw new Error("Document AudioScript is not initialized");
-	} else if (!isTrimmed(value.audio_script_entity_id)) throw new Error("invalid document AudioScript identity");
+	if (value.audio_script_entity_id === null) throw new Error("Document AudioScript is not initialized");
+	if (!isTrimmed(value.audio_script_entity_id)) throw new Error("invalid document AudioScript identity");
+	if (typeof value.loro_snapshot !== "string") throw new Error("Missing causal Loro snapshot");
 	const response = value;
 	if (response.audio_script_entity_id !== null && !response.rows.entities.some((entity) => entity.entity_id === response.audio_script_entity_id && entity.entity_kind === "audio-script")) throw new Error("Document AudioScript must name the project AudioScript");
 	return {
+		loroSnapshot: response.loro_snapshot,
 		revision: response.revision,
 		audioScriptEntityId: response.audio_script_entity_id,
 		entities: response.rows.entities.map(parseEntity),
@@ -338,8 +424,6 @@ async function safeReadJson(response) {
 * Voice results use the speech system; every other medium uses `memota`.
 */
 const ASSET_SYSTEMS = new Set(["memota", "memota-speech"]);
-/** Bounded CAS retry budget for the sync commit after a concurrent winner. */
-const MAX_COMMIT_ATTEMPTS = 3;
 /** Validate host-supplied facts; a malformed record fails the whole query. */
 function parseGenerationFacts(value) {
 	if (!Array.isArray(value)) throw new Error("generation facts must be an array");
@@ -414,49 +498,33 @@ function planGeneratedRelations(input) {
 * Sync generation lineage after a confirmed entity commit. Any failure is
 * returned as a `failed` outcome instead of thrown, so the already-durable
 * commit result is never masked; a successful query that finds nothing is
-* `current`. Asset identities are immutable, so facts are queried once. A
-* revision conflict re-reads current entities and relations, re-plans, and
-* retries within `MAX_COMMIT_ATTEMPTS`; deleted endpoints are never recreated.
+* `current`. Asset identities are immutable, so facts are queried once. The native update retains its causal baseline and merges without whole-state retries; deleted endpoints are never recreated.
 */
 async function syncGeneratedRelations(input) {
 	const { client, docId, baseState, entityCommands, loadFacts } = input;
 	try {
-		let state = await client.fetchState();
-		let scope = planGenerationScope(baseState, entityCommands, state);
+		const state = await client.fetchState();
+		const scope = planGenerationScope(baseState, entityCommands, state);
 		if (scope.queryAssetKeys.length === 0) return { status: "current" };
 		const facts = parseGenerationFacts(await loadFacts(docId, scope.queryAssetKeys));
-		for (let attempt = 1; attempt <= MAX_COMMIT_ATTEMPTS; attempt++) {
-			if (scope.queryAssetKeys.length === 0) return { status: "current" };
-			const relations = planGeneratedRelations({
-				baseState,
-				state,
-				scopedMediaIds: scope.scopedMediaIds,
-				facts,
-				newRelationId: mintRelationId
-			});
-			if (relations.length === 0) return { status: "current" };
-			try {
-				await client.commit(state.revision, {
-					...state,
-					relations: [...state.relations, ...relations]
-				});
-				return {
-					status: "applied",
-					created_relation_ids: relations.map((relation) => relation.relation_id)
-				};
-			} catch (error) {
-				if (!(error instanceof MengineEntityHttpRequestError && error.status === 409) || attempt === MAX_COMMIT_ATTEMPTS) return {
-					status: "failed",
-					message: `generation lineage sync commit failed: ${errorMessage(error)}`
-				};
-				state = await client.fetchState();
-				scope = planGenerationScope(baseState, entityCommands, state);
-			}
-		}
-		return {
-			status: "failed",
-			message: "generation lineage sync exhausted its retry budget"
-		};
+		const relations = planGeneratedRelations({
+			baseState,
+			state,
+			scopedMediaIds: scope.scopedMediaIds,
+			facts,
+			newRelationId: mintRelationId
+		});
+		if (relations.length === 0) return { status: "current" };
+		const committed = await client.commit(state.revision, {
+			...state,
+			relations: [...state.relations, ...relations]
+		});
+		const active = new Set(committed.relations.map((relation) => relation.relation_id));
+		const created = relations.map((relation) => relation.relation_id).filter((id) => active.has(id));
+		return created.length ? {
+			status: "applied",
+			created_relation_ids: created
+		} : { status: "current" };
 	} catch (error) {
 		return {
 			status: "failed",
@@ -513,86 +581,10 @@ function isRecord$1(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 //#endregion
-//#region src/migration-input.ts
-/** Validate host-recalled facts without accepting a caller-controlled snapshot or VV. */
-function parseMigrationAssetFacts(value) {
-	if (!Array.isArray(value)) throw new Error("asset_facts is required for migrate-legacy and must be an array");
-	return value.map((item) => {
-		if (!record(item)) throw new Error("Each asset_facts entry must be an object");
-		const { assetId, kind, durationMs, storageKey, voice } = item;
-		if (!nonempty(assetId)) throw new Error("asset_facts.assetId must be a non-empty trimmed string");
-		if (kind !== "image" && kind !== "video" && kind !== "audio" && kind !== "voice") throw new Error("asset_facts.kind must be image, video, audio, or voice");
-		if (Object.keys(item).some((key) => ![
-			"assetId",
-			"kind",
-			"durationMs",
-			"storageKey",
-			"voice"
-		].includes(key))) throw new Error("Unknown asset_facts field");
-		if (storageKey !== void 0 && !nonempty(storageKey)) throw new Error("asset_facts.storageKey must be non-empty");
-		if (kind === "image") {
-			if (durationMs !== void 0 || voice !== void 0) throw new Error("Image facts cannot declare duration or voice");
-			return {
-				assetId,
-				kind,
-				...storageKey === void 0 ? {} : { storageKey }
-			};
-		}
-		if (typeof durationMs !== "number" || !Number.isSafeInteger(durationMs) || durationMs <= 0) throw new Error("asset_facts.durationMs must be factual positive whole milliseconds");
-		if (kind === "video") {
-			if (voice !== void 0) throw new Error("Video facts cannot declare voice");
-			return {
-				assetId,
-				kind,
-				durationMs,
-				...storageKey === void 0 ? {} : { storageKey }
-			};
-		}
-		if (!nonempty(storageKey)) throw new Error("Audio and Voice facts require their physical storageKey");
-		if (kind === "audio") {
-			if (voice !== void 0) throw new Error("Audio facts cannot declare a Voice descriptor");
-			return {
-				assetId,
-				kind,
-				durationMs,
-				storageKey
-			};
-		}
-		if (!record(voice) || voice.system !== "voice-library" || !nonempty(voice.key) || voice.name !== void 0 && typeof voice.name !== "string" || Object.keys(voice).some((key) => ![
-			"system",
-			"key",
-			"name"
-		].includes(key))) throw new Error("Voice facts require an explicit voice-library descriptor");
-		return {
-			assetId,
-			kind,
-			durationMs,
-			storageKey,
-			voice: {
-				system: "voice-library",
-				key: voice.key,
-				...voice.name === void 0 ? {} : { name: voice.name }
-			}
-		};
-	});
-}
-function record(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function nonempty(value) {
-	return typeof value === "string" && value.length > 0 && value.trim() === value;
-}
-//#endregion
 //#region src/sandbox/generated/entity-edit-sandbox-model-context.ts
 /** @generated by gen:sandbox-dts. DO NOT EDIT. */
 const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"/** @generated by gen:sandbox-dts. Entity-native editor contract; DO NOT EDIT. */",
-	"export interface AudioMediaAssetFact {",
-	"  readonly assetId: string;",
-	"  readonly kind: 'audio';",
-	"  readonly durationMs: number;",
-	"  readonly storageKey: string;",
-	"}",
 	"export interface BoundedDerivedSequencePayload extends JsonObject {",
 	"  extent: {",
 	"    kind: 'bounded';",
@@ -612,6 +604,42 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  sampling: 'native';",
 	"  coordinateSpace: JsonValue;",
 	"}",
+	"/** Business editing surface. Infrastructure Assets are assembled by the host. */",
+	"export interface BusinessEntityFacade {",
+	"  list(): SandboxEntity[];",
+	"  get(entityId: string): SandboxEntity | null;",
+	"  readCaptionContent(entityId: string): ComposedScriptContent;",
+	"  readPhoneticScriptContent(entityId: string): ComposedPhoneticContent;",
+	"  create(",
+	"    input: Exclude<",
+	"      CreateEntityInput,",
+	"      {",
+	"        entity_kind: 'asset';",
+	"      }",
+	"    >,",
+	"  ): string;",
+	"  update(input: UpdateEntityInput): void;",
+	"  declareFields(input: UpdateEntityInput): void;",
+	"  delete(input: DeleteEntityInput): void;",
+	"}",
+	"/** Physical Asset bindings are maintained outside the sandbox. */",
+	"export interface BusinessRelationFacade {",
+	"  list(): SandboxRelation[];",
+	"  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];",
+	"  link(",
+	"    input: Exclude<",
+	"      LinkRelationInput,",
+	"      {",
+	"        relation_kind: 'physical-asset';",
+	"      }",
+	"    >,",
+	"  ): string;",
+	"  linkGenerated(input: LinkGeneratedRelationInput): string;",
+	"  linkClipAnchor(input: LinkClipAnchorRelationInput): string;",
+	"  linkPhoneticScriptRender(input: LinkPhoneticScriptRenderRelationInput): string;",
+	"  linkAudioScriptSource(input: LinkAudioScriptSourceRelationInput): string;",
+	"  unlink(input: UnlinkRelationInput): void;",
+	"}",
 	"export interface CaptionFontDescriptor {",
 	"  readonly system: 'font-library';",
 	"  readonly key: string;",
@@ -714,28 +742,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'axvideo-marker'",
 	"  | 'marker-timeline'",
 	"  | 'audio-script-marker';",
-	"export interface EntityFacade {",
-	"  /** Read complete assembled fields; returned objects are snapshots. Use update to persist edits. */",
-	"  list(): SandboxEntity[];",
-	"  get(entityId: string): SandboxEntity | null;",
-	"  /** Find document resources by external Memota asset id, including directly composed media variants. */",
-	"  findByAssetId(assetId: string): SandboxEntity<ResourceEntityKind>[];",
-	"  /** Assemble selected Caption text; missing composition is an error. */",
-	"  readCaptionContent(entityId: string): ComposedScriptContent;",
-	"  /** Assemble base text and pronunciation fields before generating Voice. */",
-	"  readPhoneticScriptContent(entityId: string): ComposedPhoneticContent;",
-	"  create(input: CreateEntityInput): string;",
-	"  /** Patch assembled fields, routing inherited fields to their declaring entity. */",
-	"  update(input: UpdateEntityInput): void;",
-	"  /** Explicitly declare own fields, overriding unambiguous bases without modifying them. Ordinary edits use update. */",
-	"  declareFields(input: UpdateEntityInput): void;",
-	"  /** Delete an Entity only after all of its incident Relations have been explicitly unlinked. */",
-	"  delete(input: DeleteEntityInput): void;",
-	"  /** Get or create one typed Asset by factual external id and return its single content identity. Never creates a Clip. */",
-	"  ensureMedia(fact: MediaAssetFact): {",
-	"    contentEntityId: string;",
-	"  };",
-	"}",
 	"export type EntityId = string;",
 	"export interface EntityPayloadByKind {",
 	"  axvideo: BoundedDerivedSequencePayload;",
@@ -745,12 +751,10 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    role?: string;",
 	"  };",
 	"  clip: JsonObject;",
-	"  /** Physical resource fields; never a copy of Caption content. */",
-	"  asset: JsonObject;",
-	"  video: BoundedNativeSequencePayload & MediaAssetPayload;",
-	"  audio: BoundedNativeSequencePayload & MediaAssetPayload;",
-	"  voice: BoundedNativeSequencePayload & MediaAssetPayload;",
-	"  image: UnboundedConstantSequencePayload & MediaAssetPayload;",
+	"  video: BoundedNativeSequencePayload;",
+	"  audio: BoundedNativeSequencePayload;",
+	"  voice: BoundedNativeSequencePayload;",
+	"  image: UnboundedConstantSequencePayload;",
 	"  'sequence-marker': JsonObject & {",
 	"    sourceRange: {",
 	"      start: number;",
@@ -794,19 +798,18 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  };",
 	"}",
 	"export interface EntityStoreSnapshot {",
+	"  /** Causal compiler baseline; required for publishing edits. */",
+	"  loroSnapshot?: string;",
 	"  revision: number;",
-	"  /** Fixed identity outlet of the project's one AudioScript; null only before initialization (revision 0). */",
+	"  /** Current AudioScript version attached to the project; initialized projects always attach a script, possibly empty. */",
 	"  audioScriptEntityId: string | null;",
 	"  entities: SandboxEntity[];",
 	"  relations: SandboxRelation[];",
 	"}",
-	"export interface ImageMediaAssetFact {",
-	"  readonly assetId: string;",
-	"  readonly kind: 'image';",
-	"  readonly storageKey?: string;",
-	"}",
 	"export interface InsertCaptionClipInput {",
 	"  readonly timelineEntityId: string;",
+	"  /** Existing generation identity for newly materialized Caption content, distinct from its Clip. */",
+	"  readonly captionEntityId?: string;",
 	"  /** Stable placed caption identity, distinct from the Caption content identity. */",
 	"  readonly captionClipEntityId?: string;",
 	"  /** Existing bases composed by this variant; includes an AudioScript text owner. */",
@@ -827,21 +830,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  readonly targetRange?: SequenceRange<number>;",
 	"  readonly clipPayload?: JsonObject;",
 	"}",
-	"export interface InsertMediaClipInput {",
-	"  readonly timelineEntityId: string;",
-	"  readonly clipEntityId?: string;",
-	"  readonly media: VisualMediaAssetFact;",
-	"  /** Source/display window in whole milliseconds. Images use this as their finite display span. */",
-	"  readonly sourceRange: SequenceRange<number>;",
-	"  readonly placement: ClipPlacement;",
-	"  readonly volume?: number;",
-	"}",
-	"export interface InsertMediaClipsInput {",
-	"  readonly timelineEntityId: string;",
-	"  readonly clips: readonly ReplacementMediaClipInput[];",
-	"  /** One placement decision for the whole input-ordered block. */",
-	"  readonly insertion: MediaClipInsertion;",
-	"}",
 	"export interface InsertPlacedClipInput {",
 	"  readonly trackEntityId: string;",
 	"  readonly contentEntityId: string;",
@@ -862,7 +850,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'timeline'",
 	"  | 'track'",
 	"  | 'clip'",
-	"  | 'asset'",
 	"  | 'video'",
 	"  | 'audio'",
 	"  | 'voice'",
@@ -879,7 +866,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'marker-content'",
 	"  | 'axvideo-marker'",
 	"  | 'marker-timeline'",
-	"  | 'physical-asset'",
 	"  | 'generated'",
 	"  | 'caption-alignment'",
 	"  | 'clip-anchor'",
@@ -939,28 +925,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"        alignment: JsonValue;",
 	"      };",
 	"    });",
-	"/** Facts resolved from media storage. A trim window never substitutes for intrinsic duration. */",
-	"export type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceMediaAssetFact;",
-	"export type MediaAssetPayload = JsonObject & {",
-	"  external: {",
-	"    system: 'memota' | 'memota-speech';",
-	"    key: string;",
-	"  };",
-	"  storageKey?: string;",
-	"};",
-	"export type MediaClipInsertion =",
-	"  | {",
-	"      readonly kind: 'before';",
-	"      readonly clipEntityId: string;",
-	"    }",
-	"  | {",
-	"      readonly kind: 'after';",
-	"      readonly clipEntityId: string;",
-	"    }",
-	"  | {",
-	"      readonly kind: 'firstStart';",
-	"      readonly startMs: number;",
-	"    };",
 	"export interface MoveClipInput {",
 	"  readonly clipEntityId: string;",
 	"  readonly trackEntityId: string;",
@@ -987,23 +951,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  readonly timelineEntityId: string;",
 	"  readonly style: CaptionStyleFields;",
 	"}",
-	"export interface RelationFacade {",
-	"  list(): SandboxRelation[];",
-	"  /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */",
-	"  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];",
-	"  /** Link existing entities through ordinary associations; variant bases are stored directly on the variant. */",
-	"  link(input: LinkRelationInput): string;",
-	"  /** Author ordered generated(output,input); generic link() deliberately rejects this kind. */",
-	"  linkGenerated(input: LinkGeneratedRelationInput): string;",
-	"  /** Author ordered clip-anchor(child,host) without positional endpoint ambiguity. */",
-	"  linkClipAnchor(input: LinkClipAnchorRelationInput): string;",
-	"  /** Author ordered phonetic-script-render(output,script) without positional endpoint ambiguity. */",
-	"  linkPhoneticScriptRender(input: LinkPhoneticScriptRenderRelationInput): string;",
-	"  /** Author ordered audio-script-source(script,source) without positional endpoint ambiguity. */",
-	"  linkAudioScriptSource(input: LinkAudioScriptSourceRelationInput): string;",
-	"  /** Remove a Relation by identity; endpoint replacement is an explicit unlink plus link. */",
-	"  unlink(input: UnlinkRelationInput): void;",
-	"}",
 	"export interface ReplaceClipContentInput {",
 	"  readonly clipEntityId: string;",
 	"  /** Existing Sequence media Entity id. Asset ids and URLs are not content ids. */",
@@ -1013,25 +960,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  readonly targetRange?: SequenceRange<number>;",
 	"  readonly timeRemapping?: JsonValue;",
 	"}",
-	"export interface ReplaceMediaClipInput {",
-	"  readonly clipEntityId: string;",
-	"  readonly media: VisualMediaAssetFact;",
-	"  readonly sourceRange: SequenceRange<number>;",
-	"}",
-	"export interface ReplaceSequentialClipsInput {",
-	"  readonly timelineEntityId: string;",
-	"  readonly oldClipEntityIds: readonly string[];",
-	"  readonly newClips: readonly ReplacementMediaClipInput[];",
-	"  readonly onAnchored: 'remap' | 'cascade';",
-	"}",
-	"export interface ReplacementMediaClipInput {",
-	"  readonly clipEntityId?: string;",
-	"  readonly media: VisualMediaAssetFact;",
-	"  readonly sourceRange: SequenceRange<number>;",
-	"  readonly volume?: number;",
-	"}",
-	"/** Asset identity, either an old physical-only row or a directly composed media variant. */",
-	"export type ResourceEntityKind = 'image' | 'video' | 'audio' | 'voice';",
 	"export interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {",
 	"  entity_id: string;",
 	"  entity_kind: K;",
@@ -1070,12 +998,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | {",
 	"      readonly position: 'trackStart';",
 	"    };",
-	"export interface SetBgmInput {",
-	"  readonly timelineEntityId: string;",
-	"  readonly bgmClipEntityId: string;",
-	"  readonly media: AudioMediaAssetFact;",
-	"  readonly volume: number;",
-	"}",
 	"export interface SetCaptionVisibilityInput {",
 	"  readonly timelineEntityId: string;",
 	"  readonly hidden: boolean;",
@@ -1134,68 +1056,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  entity_id: string;",
 	"  payload: JsonObject;",
 	"}",
-	"export interface VideoMediaAssetFact {",
-	"  readonly assetId: string;",
-	"  readonly kind: 'video';",
-	"  readonly durationMs: number;",
-	"  readonly storageKey?: string;",
-	"}",
-	"export type VisualMediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact;",
-	"export interface VoiceDescriptor {",
-	"  readonly system: 'voice-library';",
-	"  readonly key: string;",
-	"  readonly name?: string;",
-	"}",
-	"export interface VoiceMediaAssetFact {",
-	"  /** Stable external speech result id, independent of the placed Clip id. */",
-	"  readonly assetId: string;",
-	"  readonly kind: 'voice';",
-	"  readonly durationMs: number;",
-	"  readonly storageKey: string;",
-	"  /** Present for synthesized voice, absent for original recorded audio. */",
-	"  readonly voice?: VoiceDescriptor;",
-	"}",
-	"export interface VoiceoverCaptionFact {",
-	"  /** Stable placed caption identity supplied by the materialized side effect. */",
-	"  readonly captionClipEntityId: string;",
-	"  /** Directly held bases; includes the AudioScript used by the Voice. */",
-	"  readonly baseEntityIds: readonly string[];",
-	"  /** Ordered selection of AudioScript segments; caption text is never passed inline. */",
-	"  readonly selections: readonly CaptionSegmentSelection[];",
-	"  readonly startMs: number;",
-	"  readonly durationMs: number;",
-	"  readonly style?: CaptionStyleFields;",
-	"}",
-	"export type VoiceoverTakeInput = {",
-	"  readonly timelineEntityId: string;",
-	"  /** Stable placed speech identity, distinct from media.assetId. */",
-	"  readonly voiceoverClipEntityId: string;",
-	"  readonly media: VoiceMediaAssetFact;",
-	"  /** Existing pronunciation variant; its composed AudioScript stays the text owner. */",
-	"  readonly phoneticScriptEntityId: string;",
-	"  readonly volume: number;",
-	"  readonly captions: readonly VoiceoverCaptionFact[];",
-	"} & (",
-	"  | {",
-	"      readonly placement: ClipPlacement;",
-	"      readonly hostClipEntityId?: never;",
-	"      readonly anchorOffset?: never;",
-	"    }",
-	"  | {",
-	"      readonly placement?: never;",
-	"      readonly hostClipEntityId: string;",
-	"      readonly anchorOffset: number;",
-	"    }",
-	");",
-	"export interface VoiceoverTakeResult {",
-	"  readonly voiceoverClipEntityId: string;",
-	"  readonly voiceEntityId: string;",
-	"  /** The pronunciation variant the Voice was rendered from. */",
-	"  readonly phoneticScriptEntityId: string;",
-	"  /** The base-text owner resolved from the PhoneticScript baseEntityIds. */",
-	"  readonly audioScriptEntityId: string;",
-	"  readonly captionClipEntityIds: readonly string[];",
-	"}",
 	"/** Timeline writes accept existing media Entity ids, never Memota asset ids or URLs. */",
 	"export interface EditApi {",
 	"  insertClip(input: InsertClipInput): ClipEntityId;",
@@ -1205,21 +1065,15 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  moveSequentialClips(input: MoveSequentialClipsInput): void;",
 	"  moveClip(input: MoveClipInput): void;",
 	"  replaceClipContent(input: ReplaceClipContentInput): void;",
-	"  insertMediaClip(input: InsertMediaClipInput): ClipEntityId;",
-	"  insertMediaClips(input: InsertMediaClipsInput): readonly ClipEntityId[];",
-	"  replaceMediaClip(input: ReplaceMediaClipInput): void;",
 	"  setClipVolume(input: SetClipVolumeInput): void;",
 	"  setClipSpeed(input: SetClipSpeedInput): void;",
 	"  trimClip(input: TrimClipInput): void;",
-	"  replaceSequentialClips(input: ReplaceSequentialClipsInput): readonly ClipEntityId[];",
 	"  deleteClip(input: DeleteClipInput): void;",
 	"  deleteClipTree(input: DeleteClipTreeInput): void;",
 	"  updateClip(input: UpdateClipInput): void;",
-	"  upsertVoiceoverTake(input: VoiceoverTakeInput): VoiceoverTakeResult;",
 	"  moveVoiceover(input: MoveVoiceoverInput): void;",
 	"  moveClipsToStarts(input: MoveClipsToStartsInput): void;",
 	"  deleteVoiceover(input: DeleteVoiceoverInput): void;",
-	"  setBgm(input: SetBgmInput): ClipEntityId;",
 	"  deleteBgm(input: DeleteBgmInput): void;",
 	"  setCaptionVisibility(input: SetCaptionVisibilityInput): void;",
 	"  patchCaptionStyle(input: PatchCaptionStyleInput): void;",
@@ -1235,8 +1089,8 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"}",
 	"export declare const edit: EditApi;",
 	"export declare const timeline: TimelineApi;",
-	"export declare const entities: EntityFacade;",
-	"export declare const relations: RelationFacade;",
+	"export declare const entities: BusinessEntityFacade;",
+	"export declare const relations: BusinessRelationFacade;",
 	"export declare function checkpoint(): SandboxCheckpoint;",
 	"export declare function rollbackTo(cp: SandboxCheckpoint): void;",
 	"export declare const inputs: Readonly<Record<string, unknown>>;",
@@ -1248,27 +1102,25 @@ const MEDEO_TOOL_DESCRIPTION = `
 Edit the authoritative Medeo Entity/Relation graph through a deterministic, side-effect-free JavaScript sandbox. Timeline objects and edit targets are Entities, not Memota assets or legacy parts.
 
 Operations:
-- snapshot: initialize missing fixed editor structure, then return the Entity/Relation state summary and opaque base version. Initialization is idempotent and may advance the entity revision once; unchanged snapshots do not write.
-- migrate-legacy: explicitly migrate an existing legacy timeline using recalled asset_facts. MEngine reads the canonical document and version, verifies that editing facts are preserved, and commits migration alone. Then take a fresh snapshot before any edit; never pass a caller-created legacy snapshot or version.
-- run-edit-script: inspect timeline.snapshot(), entities.*, and relations.*; edit.* operates existing Entity ids and creates the required Clip/SequenceMarker structural graph. Asset import, media Entity creation and timeline edits belong in ONE plan. The sandbox has no network, storage or generation access. Pass recalled asset facts through inputs; generation history is not a script input — the host program queries it itself after each commit. A successful run returns preview, logs, base revision and plan_id.
-- commit-plan: commit the complete Entity/Relation plan through revision CAS. The server derives the read-only timeline projection in the same transaction. There is no separate writable timeline plan and no preflight replay into a legacy editor. A failed transport is unconfirmed, never committed; retry the same plan_id.
+- snapshot: read the current Entity/Relation view, project attachments and causal Loro baseline. Reading does not initialize or mutate domain data.
+- run-edit-script: inspect timeline.snapshot(), entities.*, and relations.*; edit.* operates existing Entity ids and creates the required Clip/SequenceMarker structural graph. The sandbox has no network, storage or generation access. Use assembled entity fields; the host manages resource storage and generation provenance. A successful run returns preview, logs, base revision and plan_id.
+- commit-plan: publish the native Loro update compiled against the plan’s causal baseline. Concurrent independent edits merge through Loro. The timeline and AudioScript panel read the merged entity state. A failed transport is unconfirmed; retry the same plan_id so operation identities are preserved.
 
-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.
+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. Concurrent edits do not require replaying the script against a newer snapshot. If a domain conflict is reported, inspect the merged state and resolve it explicitly; never replace the complete document to force the edit through.
 
-Generating an Asset alone does not require an Entity. Using that resource in the editor DOES: recall the Asset facts, call entities.ensureMedia(fact), then pass its contentEntityId to edit.insertClip. A raw external asset id or URL is not valid contentEntityId. Image/Video/Audio/Voice are logical variants of Asset: a resource has ONE identity and ONE typed row owning both media fields and external {system,key}/storageKey, with no separate Asset row or physical-asset relation. ensureMedia returns contentEntityId and reuses that single identity by external asset id. Each placement still gets its own Clip and SequenceMarker. Generation lineage is program-synced: after each successful commit the tool connects existing typed Assets from host-recalled generation facts (endpoint 0 output, endpoint 1 input) that the host queries itself — do not pass generation history through inputs. Do not author generated Relations yourself, and never create an Entity merely to backfill or represent lineage; media variants the edit itself legitimately needs are still created normally. Text-only generation has no input and no lineage edge. relations.of(entityId) is endpoint-agnostic.
+Generation tools return Asset references, not domain Entity ids. An Asset id may be passed as an entity resource field: external: { system: "memota", key: assetId }. Create or update the domain Entity using entities.*, then place its Entity id with edit.insertClip. Asset ids are not Entity ids, baseEntityIds or Relation endpoints. The sandbox exposes no Asset creation, lookup, reading or storage API; the host resolves resource references. Each placement has its own Clip and SequenceMarker. Generation lineage is host-synced; 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.
 timeline.snapshot() returns the Entity/Relation graph with its revision, not a legacy VideoDraft. Inspect Timeline, Track, Clip, SequenceMarker and their relations to plan edits.
-Generation lineage is not a model input: the host program queries it via loadGenerationFacts and syncs generated Relations after each successful commit. Memota asset facts are host-provided through inputs. Never invent an asset id, Entity kind, or peer Entity id.
-Use entities.ensureMedia(fact) to get or create the canonical typed Asset. Native media placement helpers use the same resolver. findByAssetId includes directly composed media variants, including Voice. Every Image/Video/Audio/Voice must own its external identity; separate Asset+media graphs are invalid. A typed Asset's external identity cannot be removed or rewritten: to replace its source, ensureMedia for the new Asset and replace the Clip's content. Conflicting facts fail closed. Asset generation itself still creates no editor Entities.
-For recalled video/audio/voice, create a bounded/native payload whose extent end comes from factual media duration/coordinates in inputs; never fabricate a duration. Image uses unbounded/constant semantics and has no invented end. If required facts are absent, do not create the media Entity yet.
-Caption content is assembled from AudioScript; never create an inline text Asset for it. Generated media lineage is host-owned; do not author generated Relations yourself. relations.of remains endpoint-agnostic for lookup.
-The compatibility reader supports the existing four Track roles: video_clip (Image/Video), speech (Voice), caption (Caption), and bgm (Audio), one of each. Clip.volume is decibels (-60 to 20, 0 = original). Marker.sourceRange is the selected source interval; Marker.duration is effective display/playback duration. Coordinates and duration are whole milliseconds for this reader, not a global DSL restriction. Placement is exactly one of Clip.order, Marker.targetRange, or clip-anchor(child,host) plus Marker.anchorOffset. Use the native move/delete/voiceover helpers so placement and cascade decisions are in the same entity plan. Reading the graph never rebinds anchors or invents empty clips. Linear timeRemapping is {kind:'linear',rate:2,mode:'constant'} and agrees with rounded source span divided by rate. Image remains unbounded/constant; an explicit linear rate scales its display window, not an invented media extent. Nonlinear speed and multiple visual overlay tracks are unsupported.
+Inspect existing Image/Video/Audio/Voice Entities and their factual extents before placing them. For an uploaded or generated resource, create its media Entity with the returned Asset id in external.key and the factual media extent. The host resolves its physical resource. Replace a Clip's content using another content Entity id. Never fabricate a duration.
+Caption composes AudioScript text. Its optional external field may carry the Caption Asset id; the host resolves that resource. A Caption created from AudioScript may have no physical resource. Read and edit assembled fields through entities; do not create Asset entities or physical-asset Relations.
+The editor projection supports the existing four Track roles: video_clip (Image/Video), speech (Voice), caption (Caption), and bgm (Audio), one of each. Clip.volume is decibels (-60 to 20, 0 = original). Marker.sourceRange is the selected source interval; Marker.duration is effective display/playback duration. Coordinates and duration are whole milliseconds for this reader, not a global DSL restriction. Placement is exactly one of Clip.order, Marker.targetRange, or clip-anchor(child,host) plus Marker.anchorOffset. Use the native move/delete/voiceover helpers so placement and cascade decisions are in the same entity plan. Reading the graph never rebinds anchors or invents empty clips. Linear timeRemapping is {kind:'linear',rate:2,mode:'constant'} and agrees with rounded source span divided by rate. Image remains unbounded/constant; an explicit linear rate scales its display window, not an invented media extent. Nonlinear speed and multiple visual overlay tracks are unsupported.
 Entities own fields; ordinary Relations express associations; variants directly hold baseEntityIds and assemble the referenced entities. These foundations are fixed: implementation must follow them, never redefine them. Any entity may compose multiple bases. Equal field names from multiple bases (even equal values) are errors, even when the variant declares that field itself. After validating all base fields are unambiguous, explicitly declared own fields may override base fields without mutating the bases. Base ordering never resolves conflicts. AudioScript owns segmented text. Caption and PhoneticScript persist baseEntityIds including their AudioScript, plus their own fields; no composition Relation exists. Create the real bases before reading or committing a variant. Inside the DSL sandbox, entities.get/list expose complete assembled fields. Consumers read fields without inspecting base IDs or merging bases. entities.update patches supplied fields and routes inherited fields to their declaring entity; omitted fields remain unchanged. entities.declareFields explicitly declares own overrides and is distinct from an ordinary field edit. Persistence keeps owned fields only. entities.readCaptionContent(id) and entities.readPhoneticScriptContent(id) return assembled text. Missing/cyclic bases and field conflicts fail before persistence.
-Use edit.insertCaptionClip with baseEntityIds and selections; each voiceover caption also supplies baseEntityIds. A selection names segmentId and may use a half-open Unicode code-point textRange to split a segment for the screen without rewriting AudioScript. Generate Voice from an existing PhoneticScript, then use phoneticScriptEntityId in the voiceover helper or relations.linkPhoneticScriptRender({output_entity_id,phonetic_script_entity_id}) for its render relation. Caption and Voice have their own Clips; display anchoring is explicit and independent of composition/alignment.
+Use edit.insertCaptionClip with baseEntityIds and selections, plus captionEntityId when generation returned a Caption identity; each voiceover caption also supplies baseEntityIds. A selection names segmentId and may use a half-open Unicode code-point textRange to split a segment for the screen without rewriting AudioScript. Generate Voice from an existing PhoneticScript, then use phoneticScriptEntityId in the voiceover helper or relations.linkPhoneticScriptRender({output_entity_id,phonetic_script_entity_id}) for its render relation. Caption and Voice have their own Clips; display anchoring is explicit and independent of composition/alignment.
 Move or stretch only the Clip's display Marker; preserve Caption intrinsic Sequence, AudioScript text and its annotation Markers. AudioScript cannot enter a Clip and has no intrinsic time. audio-script-source links its ASR source Audio/Video/Voice; audio-script-marker attaches annotation Markers with directly assigned segmentRanges:{segmentId,startMs,endMs} in whole milliseconds. Annotation Markers have no Clip/AXVideo/content/Timeline relations and never refer to other Markers for time. BGM keeps factual source duration with durationPolicy:'timeline'. Never introduce a speech entity kind.
-Create only the known entity kinds. The host initializes one Timeline, four fixed Tracks, and the project's single AudioScript (initially segments:[]) before editing; inspect and reuse their IDs from timeline.snapshot(), never create another Timeline, Track, or AudioScript for each operation. The AudioScript identity is fixed for the project: edit its segments in place via entities.update, never delete or re-create it. If snapshot reports legacy migration is required, recall the listed asset facts and call migrate-legacy first. Missing facts, unsupported layouts, and version conflicts fail closed; never fall back to an old timeline method or raw update endpoint.
+Create only the known entity kinds. Project creation initializes one current Timeline, four Tracks and an attached AudioScript with segments:[]. Read the current AudioScript ID from timeline.snapshot(); the panel displays this attachment and preserves its segments. Normal edits operate this script, not an unrelated newly created script.
+Immutable updates apply to every entity: editing an owned field creates a new content version ID; changing only a variant's base ID preserves the variant ID. Editing a base through a variant updates the owner, and the compiler advances the affected base links and project attachment. A variant-owned edit creates a new variant version and retains its unchanged bases. Do not manually clone entities or duplicate inherited fields to implement versioning. Versions preserve native text and list editing identities so independent concurrent edits survive. Missing facts, unsupported layouts and composition conflicts are explicit errors; there is no legacy migration or whole-state overwrite path.
 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. */
@@ -1294,42 +1146,6 @@ ${ENTITY_EDIT_SANDBOX_API_DTS}
 //#endregion
 //#region src/schema.ts
 const MEDEO_TOOL_NAME = "medeo";
-const assetFactProperties = {
-	assetId: {
-		type: "string",
-		minLength: 1
-	},
-	kind: {
-		type: "string",
-		enum: [
-			"image",
-			"video",
-			"audio",
-			"voice"
-		]
-	},
-	durationMs: {
-		type: "integer",
-		minimum: 1
-	},
-	storageKey: {
-		type: "string",
-		minLength: 1
-	},
-	voice: {
-		type: "object",
-		additionalProperties: false,
-		required: ["system", "key"],
-		properties: {
-			system: { const: "voice-library" },
-			key: {
-				type: "string",
-				minLength: 1
-			},
-			name: { type: "string" }
-		}
-	}
-};
 /**
 * JSON Schema for the host-facing `medeo` tool surface.
 *
@@ -1347,7 +1163,6 @@ const MEDEO_TOOL_PARAMETERS = {
 			type: "string",
 			enum: [
 				"snapshot",
-				"migrate-legacy",
 				"run-edit-script",
 				"commit-plan"
 			],
@@ -1367,68 +1182,6 @@ const MEDEO_TOOL_PARAMETERS = {
 			type: "object",
 			description: "Pre-materialized, side-effect-free values passed into the script, including recalled asset facts. Generation history is never an input: the host queries lineage itself and syncs generated Relations after each commit. Generation and network IO must happen in the host before this call."
 		},
-		asset_facts: {
-			type: "array",
-			description: "Factual asset metadata recalled by the host for migrate-legacy only. The package reads the canonical legacy snapshot and version itself; never supply a clip trim window as media duration.",
-			items: { oneOf: [
-				{
-					type: "object",
-					additionalProperties: false,
-					required: ["assetId", "kind"],
-					properties: {
-						assetId: assetFactProperties.assetId,
-						kind: { const: "image" },
-						storageKey: assetFactProperties.storageKey
-					}
-				},
-				{
-					type: "object",
-					additionalProperties: false,
-					required: [
-						"assetId",
-						"kind",
-						"durationMs"
-					],
-					properties: {
-						assetId: assetFactProperties.assetId,
-						kind: { const: "video" },
-						durationMs: assetFactProperties.durationMs,
-						storageKey: assetFactProperties.storageKey
-					}
-				},
-				{
-					type: "object",
-					additionalProperties: false,
-					required: [
-						"assetId",
-						"kind",
-						"durationMs",
-						"storageKey"
-					],
-					properties: {
-						assetId: assetFactProperties.assetId,
-						kind: { const: "audio" },
-						durationMs: assetFactProperties.durationMs,
-						storageKey: assetFactProperties.storageKey
-					}
-				},
-				{
-					type: "object",
-					additionalProperties: false,
-					required: [
-						"assetId",
-						"kind",
-						"durationMs",
-						"storageKey",
-						"voice"
-					],
-					properties: {
-						...assetFactProperties,
-						kind: { const: "voice" }
-					}
-				}
-			] }
-		},
 		timeout_ms: {
 			type: "integer",
 			minimum: 1,
@@ -1450,24 +1203,11 @@ const MEDEO_TOOL_PARAMETERS = {
 		},
 		validation: {
 			type: "string",
-			enum: ["version"],
-			description: "Commit with Entity revision CAS; reject concurrent changes."
+			enum: ["preflight"],
+			description: "Publish the native update already validated on its causal Loro fork."
 		}
 	},
 	oneOf: [
-		{
-			required: [
-				"op",
-				"doc_id",
-				"asset_facts"
-			],
-			properties: {
-				op: { const: "migrate-legacy" },
-				doc_id: { $ref: "#/properties/doc_id" },
-				asset_facts: { $ref: "#/properties/asset_facts" }
-			},
-			additionalProperties: false
-		},
 		{
 			required: ["op", "doc_id"],
 			properties: {
@@ -1619,7 +1359,8 @@ function requiredContext(value, docId, field) {
 	if (resolved == null || resolved.length === 0) throw new Error(`${field} must resolve to a non-empty string for doc ${docId}`);
 	return resolved;
 }
-function renderEntitySnapshot(state) {
+function renderEntitySnapshot(raw) {
+	const state = businessState(raw);
 	const rows = [...state.entities.map((entity) => JSON.stringify(entity)), ...state.relations.map((relation) => JSON.stringify(relation))];
 	const shown = rows.slice(0, 200);
 	return [
@@ -1628,61 +1369,25 @@ function renderEntitySnapshot(state) {
 		...shown.length < rows.length ? ["[truncated; inspect entities/relations in the sandbox]"] : []
 	].join("\n");
 }
-function migrationNotice(document, state) {
-	if (state.entities.some((row) => row.entity_kind === "timeline") || Object.keys(document.part_library ?? {}).length === 0) return "";
-	const assetIds = new Set(Object.values(document.part_library ?? {}).flatMap((part) => {
-		const id = part.video_clip?.origin_media_id ?? part.bgm?.origin_media_id;
-		return typeof id === "string" && id !== "" ? [id] : [];
-	}));
-	return `\nLegacy timeline migration required. Recall factual media metadata for ${JSON.stringify([...assetIds])}, then call migrate-legacy with asset_facts. Speech facts are read from the canonical legacy document. Take a fresh snapshot after migration before editing.`;
-}
 async function commitEntityPlan(client, plan) {
-	const rows = plan.entity_rows;
-	if (rows === void 0) throw new Error("entity plan is missing its authoritative rows");
+	if (plan.entity_rows === void 0) throw new Error("entity plan is missing its authoritative rows");
 	try {
-		const committed = await client.commit(plan.entity_base_revision, rows, {
-			deleted_entity_ids: plan.deleted_entity_ids ?? [],
-			deleted_relation_ids: plan.deleted_relation_ids ?? []
-		});
+		if (!plan.loro_update) throw new Error("Entity plan has no compiled Loro update");
+		const committed = await client.commitUpdate(plan.loro_update);
 		return {
 			kind: "committed",
 			ops_applied: plan.entity_commands.length,
-			collaborated: false,
+			collaborated: committed.revision > plan.entity_base_revision + 1,
 			entity_revision: committed.revision
 		};
 	} catch (error) {
 		if (error instanceof MengineEntityHttpRequestError) {
-			if (error.status === 409 && isRevisionConflictPayload(error.payload)) {
-				const actualFromPayload = revisionConflictActual(error.payload);
-				try {
-					const current = await client.fetchState();
-					if (current.revision === plan.entity_base_revision + 1 && entityRowsEquivalent(current, rows)) return {
-						kind: "committed",
-						ops_applied: plan.entity_commands.length,
-						collaborated: false,
-						entity_revision: current.revision
-					};
-					return {
-						kind: "rejected",
-						reason: "entity_revision_mismatch",
-						expected: plan.entity_base_revision,
-						actual: current.revision
-					};
-				} catch {
-					if (actualFromPayload !== void 0) return {
-						kind: "rejected",
-						reason: "entity_revision_mismatch",
-						expected: plan.entity_base_revision,
-						actual: actualFromPayload
-					};
-					return {
-						kind: "unconfirmed",
-						reason: "push_failed",
-						ops_applied: plan.entity_commands.length,
-						message: "entity-state conflict could not be reconciled"
-					};
-				}
-			}
+			if (isRecord(error.payload) && error.payload.accepted === true && typeof error.payload.revision === "number") return {
+				kind: "conflicted",
+				accepted: true,
+				entity_revision: error.payload.revision,
+				message: entityHttpErrorMessage(error.payload)
+			};
 			return {
 				kind: "rejected",
 				reason: "entity_state_rejected",
@@ -1698,34 +1403,14 @@ async function commitEntityPlan(client, plan) {
 		};
 	}
 }
-function revisionConflictActual(payload) {
-	if (!isRecord(payload)) return void 0;
-	const actual = payload.actual_revision;
-	return typeof actual === "number" && Number.isSafeInteger(actual) && actual >= 0 ? actual : void 0;
-}
-function isRevisionConflictPayload(payload) {
-	return isRecord(payload) && payload.code === "revision_conflict";
-}
 function entityHttpErrorMessage(payload) {
+	if (isRecord(payload) && isRecord(payload.error) && typeof payload.error.message === "string") return payload.error.message;
 	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) => ({
-		audioScriptEntityId: state.audioScriptEntityId,
-		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;
@@ -1736,18 +1421,6 @@ function parseInput(value) {
 		op,
 		doc_id: docId
 	};
-	if (op === "migrate-legacy") {
-		if (Object.keys(value).some((key) => ![
-			"op",
-			"doc_id",
-			"asset_facts"
-		].includes(key))) throw new Error("migrate-legacy accepts asset_facts only; the package reads the canonical document and version");
-		return {
-			op,
-			doc_id: docId,
-			asset_facts: parseMigrationAssetFacts(value.asset_facts)
-		};
-	}
 	if (op === "run-edit-script") {
 		if (typeof value.script !== "string" || value.script.length === 0) throw new Error("script must be a non-empty string");
 		if (value.inputs !== void 0 && !isRecord(value.inputs)) throw new Error("inputs must be an object");
@@ -1768,7 +1441,7 @@ function parseInput(value) {
 	}
 	if (op === "commit-plan") {
 		if (typeof value.plan_id !== "string" || value.plan_id.length === 0) throw new Error("plan_id must be a non-empty string");
-		if (value.validation !== void 0 && value.validation !== "version" && value.validation !== "preflight") throw new Error("validation must be \"version\" or \"preflight\"");
+		if (value.validation !== void 0 && value.validation !== "preflight") throw new Error("validation must be \"preflight\"");
 		return {
 			op,
 			doc_id: docId,
@@ -1857,10 +1530,21 @@ function createMedeoTool(options) {
 			if (!(error instanceof MengineHttpRequestError) || error.status !== 404) throw error;
 			if (options.loadInitialDraft === void 0) throw error;
 		}
-		const seed = createMirrorVideoDocument(toVideoDocument(await options.loadInitialDraft(docId)), {
+		const document = toVideoDocument(await options.loadInitialDraft(docId));
+		if (Object.keys(document.part_library ?? {}).length > 0) throw new Error("Legacy content cannot bootstrap a Loro entity project");
+		const seed = createMirrorVideoDocument(document, {
 			...peerId !== void 0 ? { peerId } : {},
 			origin: "mengine.medeo_tool.bootstrap"
 		});
+		const foundation = ensureEditorFoundation({
+			entities: [],
+			relations: []
+		});
+		const entities = LoroEntityDocument.create(foundation.rows, {
+			timelineEntityId: foundation.timelineEntityId,
+			audioScriptEntityId: foundation.audioScriptEntityId
+		});
+		seed.import(entities.doc.export({ mode: "snapshot" }));
 		try {
 			await client.bootstrapSnapshot(seed.export({ mode: "snapshot" }));
 		} catch (error) {
@@ -1909,64 +1593,31 @@ function createMedeoTool(options) {
 		pendingPushes.delete(docId);
 		if (plan.plan_kind === "timeline" && result.kind === "rejected" && result.reason === "push_rejected") documents.delete(docId);
 	}
-	async function fetchEntityStateForSandbox(docId, doc, pull) {
-		const client = getEntityClient(docId);
-		for (let attempt = 0; attempt < 4; attempt += 1) {
-			const state = await client.fetchState();
-			if (pendingPushes.has(docId)) return state;
-			const document = doc.snapshot();
-			const hasTimeline = state.entities.some((row) => row.entity_kind === "timeline");
-			const hasLegacyContent = Object.keys(document.part_library ?? {}).length > 0 || (document.tracks ?? []).some((track) => (track.items ?? []).length > 0);
-			if (!hasTimeline && hasLegacyContent) return state;
-			if (!hasTimeline) {
-				if (pull.warnings !== void 0) throw new Error("Editor initialization requires a fresh canonical snapshot; retry snapshot");
-				const baseRows = toDslRows(state);
-				const migrated = migrateLegacyTimelineToEntities(document, [], baseRows);
-				try {
-					await getGraphClient(docId).commit({
-						revision: state.revision,
-						rows: baseRows
-					}, migrated, { migrationBaseVv: encodeDocVersionMark(doc.versionMark()) });
-				} catch (error) {
-					if (!(error instanceof MengineHttpRequestError) || error.status !== 409) throw new Error(`Editor initialization was not confirmed; retry snapshot to reconcile state: ${error instanceof Error ? error.message : String(error)}`);
-				}
-				pull = await observePull(doc);
-				continue;
-			}
-			const sandbox = new EntitySandbox({
-				state,
-				idFactory: (prefix) => `${prefix}_${randomUUID()}`
-			});
-			sandbox.ensureFoundation();
-			if (sandbox.commandCount === 0) return state;
-			if (pull.warnings !== void 0) throw new Error("Editor initialization requires a fresh canonical snapshot; retry snapshot");
-			try {
-				const committed = await client.commit(state.revision, sandbox.buildPlan().rows);
-				await doc.pull();
-				return committed;
-			} catch (error) {
-				if (!(error instanceof MengineEntityHttpRequestError) || error.status !== 409) throw new Error(`Editor initialization was not confirmed; retry snapshot to reconcile state: ${error instanceof Error ? error.message : String(error)}`);
-				pull = await observePull(doc);
-			}
-		}
-		throw new Error("Editor initialization conflicted repeatedly; take a fresh snapshot");
-	}
-	function getGraphClient(docId) {
-		return new EntityGraphHttpClient({
-			docId,
-			httpOrigin: requiredContext(options.httpOrigin, docId, "httpOrigin"),
-			...options.authToken === void 0 ? {} : { authToken: () => optionalContext(options.authToken, docId) },
-			...options.userId === void 0 ? {} : { userId: () => optionalContext(options.userId, docId) },
-			...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl }
-		});
+	async function fetchEntityStateForSandbox(docId, _doc, _pull) {
+		const state = await getEntityClient(docId).fetchState();
+		if (!state.loroSnapshot) throw new Error("Project requires the Loro entity contract");
+		return state;
 	}
 	async function commitCachedPlan(docId, _doc, plan, validation, baseState) {
 		if (plan.plan_kind === "timeline") throw new Error("Legacy timeline plans are not editable; use an Entity/Relation plan");
-		if (validation === "preflight") throw new Error("Entity plans use revision CAS; validation=preflight is not supported");
 		if (plan.entity_rows === void 0) throw new Error("entity plan is missing its authoritative rows");
 		const client = getEntityClient(docId);
-		const preCommitState = baseState ?? (options.loadGenerationFacts !== void 0 ? await client.fetchState() : void 0);
-		return await attachGenerationSync(docId, plan, await commitEntityPlan(client, plan), preCommitState);
+		if (options.loadGenerationFacts !== void 0 && baseState === void 0) throw new Error("Generation synchronization is missing the cached causal plan baseline");
+		const synced = await attachGenerationSync(docId, plan, await commitEntityPlan(client, plan), baseState);
+		if (synced.kind !== "committed" || options.loadCaptionAssets === void 0) return synced;
+		const assembly = await assembleCaptionAssets({
+			client,
+			docId,
+			loadAssets: options.loadCaptionAssets
+		});
+		return {
+			...synced,
+			asset_assembly: assembly,
+			...assembly.status === "failed" ? { warnings: [...synced.warnings ?? [], {
+				kind: "asset_assembly_failed",
+				message: assembly.message ?? "Caption Asset assembly failed"
+			}] } : {}
+		};
 	}
 	/**
 	* After a confirmed entity commit, connect fact-matched generated Relations
@@ -2056,51 +1707,12 @@ function createMedeoTool(options) {
 				op: "snapshot",
 				doc_id: input.doc_id,
 				version: `${encodeDocVersionMark(doc.versionMark())}:entities:${entityState.revision}`,
-				preview: renderEntitySnapshot(entityState) + migrationNotice(doc.snapshot(), entityState),
+				preview: renderEntitySnapshot(entityState),
 				collaborated: pull.collaborated,
 				...pull.warnings !== void 0 ? { warnings: pull.warnings } : {}
 			};
 		});
 	}
-	async function migrate(input) {
-		return runExclusive(input.doc_id, async (doc) => {
-			assertNoPendingPush(input.doc_id);
-			const snapshotState = await getEntityClient(input.doc_id).fetchState();
-			if (snapshotState.entities.some((row) => row.entity_kind === "timeline")) return {
-				ok: true,
-				op: "migrate-legacy",
-				doc_id: input.doc_id,
-				migration_status: "already_entity",
-				entity_revision: snapshotState.revision,
-				next_action: "snapshot"
-			};
-			const pull = await doc.pull();
-			if (!pull.ok) throw new Error(`Migration requires a fresh canonical snapshot: ${pull.error.message}`);
-			const migrationBaseVv = encodeDocVersionMark(doc.versionMark());
-			const baseRows = toDslRows(snapshotState);
-			const nextRows = migrateLegacyTimelineToEntities(doc.snapshot(), input.asset_facts, baseRows);
-			let revision;
-			try {
-				revision = (await getGraphClient(input.doc_id).commit({
-					revision: snapshotState.revision,
-					rows: baseRows
-				}, nextRows, { migrationBaseVv })).revision;
-			} catch (error) {
-				if (error instanceof MengineHttpRequestError) throw new Error(`Migration rejected (HTTP ${error.status}): ${entityHttpErrorMessage(error.payload)}; take a fresh snapshot before retrying`);
-				throw new Error("Migration submission is unconfirmed; take a fresh snapshot and retry migrate-legacy to inspect whether the Entity timeline already exists");
-			}
-			documents.delete(input.doc_id);
-			for (const [id, cached] of plans) if (cached.docId === input.doc_id) plans.delete(id);
-			return {
-				ok: true,
-				op: "migrate-legacy",
-				doc_id: input.doc_id,
-				migration_status: "committed",
-				entity_revision: revision,
-				next_action: "snapshot"
-			};
-		});
-	}
 	async function run(input) {
 		return runExclusive(input.doc_id, async (doc) => {
 			assertNoPendingPush(input.doc_id);
@@ -2210,7 +1822,6 @@ function createMedeoTool(options) {
 			try {
 				const parsed = parseInput(input);
 				if (parsed.op === "snapshot") return await snapshot(parsed);
-				if (parsed.op === "migrate-legacy") return await migrate(parsed);
 				if (parsed.op === "run-edit-script") return await run(parsed);
 				return await commit(parsed);
 			} catch (error) {
@@ -2243,6 +1854,139 @@ function createMedeoTool(options) {
 	};
 }
 //#endregion
-export { EditSandboxSession, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
+//#region src/entity/materialize-resources.ts
+/** Persist resources before model consumption. The host serializes repeated imports of the same generation task. */
+async function materializeResources(options, resources) {
+	const client = new EntityHttpClient(options);
+	const state = await client.fetchState();
+	let resourceKey = "";
+	const sandbox = new EntitySandbox({
+		state,
+		idFactory: (prefix) => stableId(prefix, options.docId, resourceKey)
+	});
+	const ids = [];
+	for (const resource of resources) {
+		resourceKey = `${resource.kind}:${resource.assetId}`;
+		if (resource.kind !== "caption") {
+			ids.push(sandbox.entities.ensureMedia(resource).contentEntityId);
+			continue;
+		}
+		const assetId = stableId("asset", resource.assetId);
+		const asset = sandbox.entities.get(assetId);
+		if (asset) {
+			if (asset.entity_kind !== "asset" || asset.payload.storageKey !== resource.storageKey) throw new Error("Conflicting Caption resource identity");
+			const captions = sandbox.relations.of(assetId, "physical-asset").map((edge) => sandbox.entities.get(edge.endpoint_0_entity_id)).filter((entity) => entity?.entity_kind === "caption");
+			if (captions.length !== 1) throw new Error("Caption resource must resolve to one materialized Caption");
+			ids.push(captions[0].entity_id);
+			continue;
+		}
+		if (!resource.assetId.trim() || !resource.storageKey.trim() || !resource.segments.length) throw new Error("Caption resource requires a physical locator and timed segments");
+		for (const segment of resource.segments) {
+			if (typeof segment.text !== "string" || !Number.isFinite(segment.startMs) || !Number.isFinite(segment.endMs) || segment.startMs < 0 || segment.endMs <= segment.startMs) throw new Error("Caption resource has invalid ASR text or timing");
+			for (const word of segment.words ?? []) if (typeof word.text !== "string" || !Number.isFinite(word.startMs) || !Number.isFinite(word.endMs) || word.startMs < segment.startMs || word.endMs > segment.endMs || word.endMs < word.startMs) throw new Error("Caption resource has invalid ASR word timing");
+		}
+		const scriptId = sandbox.audioScriptEntityId;
+		if (!scriptId) throw new Error("Document AudioScript is not initialized");
+		const script = sandbox.entities.get(scriptId);
+		const segments = resource.segments.map((segment, index) => ({
+			segmentId: stableId("segment", resource.assetId, String(index)),
+			text: segment.text
+		}));
+		const start = Math.min(...resource.segments.map((segment) => segment.startMs));
+		const end = Math.max(...resource.segments.map((segment) => segment.endMs));
+		sandbox.entities.update({
+			entity_id: scriptId,
+			payload: { segments: [...script.payload.segments, ...segments] }
+		});
+		const captionId = stableId("entity", "caption", resource.assetId);
+		sandbox.entities.create({
+			entity_id: captionId,
+			entity_kind: "caption",
+			payload: {
+				baseEntityIds: [scriptId],
+				selections: segments.map(({ segmentId }) => ({ segmentId })),
+				extent: {
+					kind: "bounded",
+					start,
+					end
+				},
+				sampling: "native",
+				coordinateSpace: "milliseconds"
+			}
+		});
+		const markerId = sandbox.entities.create({
+			entity_id: stableId("entity", "asr-marker", resource.assetId),
+			entity_kind: "sequence-marker",
+			payload: {
+				sourceRange: {
+					start,
+					end
+				},
+				duration: { mode: "from-source" },
+				segmentRanges: resource.segments.map((segment, index) => ({
+					segmentId: segments[index].segmentId,
+					startMs: segment.startMs,
+					endMs: segment.endMs
+				})),
+				wordRanges: resource.segments.flatMap((segment, index) => (segment.words ?? []).map((word) => ({
+					...word,
+					segmentIndex: index
+				})))
+			}
+		});
+		sandbox.relations.link({
+			relation_id: stableId("relation", "asr-marker", resource.assetId),
+			relation_kind: "audio-script-marker",
+			endpoint_0_entity_id: scriptId,
+			endpoint_1_entity_id: markerId
+		});
+		sandbox.entities.create({
+			entity_id: assetId,
+			entity_kind: "asset",
+			payload: {
+				external: {
+					system: "memota",
+					key: resource.assetId
+				},
+				storageKey: resource.storageKey
+			}
+		});
+		sandbox.relations.link({
+			relation_id: stableId("relation", captionId, assetId),
+			relation_kind: "physical-asset",
+			endpoint_0_entity_id: captionId,
+			endpoint_1_entity_id: assetId
+		});
+		ids.push(captionId);
+	}
+	const candidate = sandbox.buildPlan();
+	if (candidate.commands.length && options.loadGenerationFacts) {
+		const newIds = new Set(ids.filter((id) => !state.entities.some((row) => row.entity_id === id)));
+		const facts = parseGenerationFacts(await options.loadGenerationFacts(options.docId, resources.map((item) => item.assetId)));
+		const relations = planGeneratedRelations({
+			baseState: state,
+			state: candidate.rows,
+			scopedMediaIds: newIds,
+			facts,
+			newRelationId: () => `relation_${globalThis.crypto.randomUUID()}`
+		});
+		for (const relation of relations) sandbox.relations.linkGenerated({
+			relation_id: relation.relation_id,
+			output_entity_id: relation.endpoint_0_entity_id,
+			input_entity_id: relation.endpoint_1_entity_id,
+			trace: relation.trace
+		});
+	}
+	const plan = sandbox.buildPlan();
+	if (!plan.commands.length) return ids;
+	const committed = await client.commit(state.revision, plan.rows);
+	for (const id of ids) if (!committed.entities.some((entity) => entity.entity_id === id)) throw new Error(`Resource entity ${id} was not confirmed by the merged document`);
+	return ids;
+}
+function stableId(prefix, ...parts) {
+	return `${prefix}_${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
+}
+//#endregion
+export { EditSandboxSession, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, collectAffectedPartIds, commitPlan, createMedeoTool, materializeResources, renderCompactProjection, renderPreview, runEditScript };
 
 //# sourceMappingURL=index.mjs.map