@mengine/medeo-tool 1.2.1-alpha.8 → 1.3.1-alpha.6

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as collectAffectedPartIds, o as renderPreview, s as renderCompactProjection, t as EditSandboxSession } from "./script-session-CHyIUBkO.mjs";
+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-1eqBGegp.mjs";
 import { EntityGraphHttpClient, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, migrateLegacyTimelineToEntities, replayJournal, toVideoDocument } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
 import { randomUUID } from "node:crypto";
@@ -205,11 +205,11 @@ const KNOWN_RELATION_KINDS = [
 	"marker-timeline",
 	"physical-asset",
 	"generated",
-	"phonetic-script-provenance",
-	"caption-provenance",
 	"caption-alignment",
 	"clip-anchor",
-	"audio-script-render"
+	"phonetic-script-render",
+	"audio-script-source",
+	"audio-script-marker"
 ];
 //#endregion
 //#region src/entity/entity-http-client.ts
@@ -276,9 +276,9 @@ var EntityHttpClient = class {
 	}
 };
 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 (!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$1(value.rows) || !Array.isArray(value.rows.entities) || !Array.isArray(value.rows.relations)) throw new Error("invalid entity-state response rows");
+	if (!isRecord$2(value.rows) || !Array.isArray(value.rows.entities) || !Array.isArray(value.rows.relations)) throw new Error("invalid entity-state response rows");
 	const response = value;
 	return {
 		revision: response.revision,
@@ -287,15 +287,15 @@ function toSnapshot(value, expectedDocId) {
 	};
 }
 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");
+	if (!isRecord$2(value) || !isTrimmed(value.entity_id) || typeof value.entity_kind !== "string" || !entityKinds.has(value.entity_kind) || !isJsonObject(value.payload)) throw new Error("invalid Entity row in entity-state response");
 	return structuredClone(value);
 }
 function parseRelation(value) {
-	if (!isRecord$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");
+	if (!isRecord$2(value) || !isTrimmed(value.relation_id) || typeof value.relation_kind !== "string" || !relationKinds.has(value.relation_kind) || !isTrimmed(value.endpoint_0_entity_id) || !isTrimmed(value.endpoint_1_entity_id) || !isJsonObject(value.metadata) || !isJsonObject(value.trace)) throw new Error("invalid Relation row in entity-state response");
 	return structuredClone(value);
 }
 function isJsonObject(value) {
-	return isJsonValue(value, /* @__PURE__ */ new Set()) && isRecord$1(value);
+	return isJsonValue(value, /* @__PURE__ */ new Set()) && isRecord$2(value);
 }
 function isJsonValue(value, ancestors) {
 	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
@@ -308,7 +308,7 @@ function isJsonValue(value, ancestors) {
 	ancestors.delete(value);
 	return valid;
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function isTrimmed(value) {
@@ -327,6 +327,187 @@ async function safeReadJson(response) {
 	}
 }
 //#endregion
+//#region src/entity/generation-sync.ts
+/**
+* External systems whose asset entities carry a factual Memota identity.
+* 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");
+	return value.map((item) => {
+		if (!isRecord$1(item)) throw new Error("each generation fact must be an object");
+		const { outputAssetId, inputAssetIds } = item;
+		if (typeof outputAssetId !== "string" || outputAssetId.length === 0 || outputAssetId.trim() !== outputAssetId) throw new Error("generation fact outputAssetId must be a non-empty trimmed string");
+		if (!Array.isArray(inputAssetIds)) throw new Error("generation fact inputAssetIds must be an array (explicit [] means text-only)");
+		const inputs = inputAssetIds;
+		for (const input of inputs) if (typeof input !== "string" || input.length === 0 || input.trim() !== input) throw new Error("generation fact inputAssetIds entries must be non-empty trimmed strings");
+		return {
+			outputAssetId,
+			inputAssetIds: [...inputs]
+		};
+	});
+}
+function planGenerationScope(base, commands, state) {
+	const touchedIds = /* @__PURE__ */ new Set();
+	for (const command of commands) if (command.kind === "create-entity" && isMediaAssetVariantKind(command.entity.entity_kind)) touchedIds.add(command.entity.entity_id);
+	const beforeByKey = resolveMediaByAssetKey(base);
+	const scoped = /* @__PURE__ */ new Set();
+	const queryKeys = /* @__PURE__ */ new Set();
+	for (const [key, mediaIds] of resolveMediaByAssetKey(state)) {
+		const previousIds = new Set(beforeByKey.get(key) ?? []);
+		for (const id of mediaIds) {
+			if (!touchedIds.has(id) || previousIds.has(id)) continue;
+			scoped.add(id);
+			queryKeys.add(key);
+		}
+	}
+	return {
+		scopedMediaIds: scoped,
+		queryAssetKeys: [...queryKeys].sort()
+	};
+}
+/**
+* Ordered generated(output,input) Relations missing from `state` for the given
+* factual records. Both endpoints must already exist and match their own Asset
+* identities, and the pair must involve a media Entity the plan
+* newly fact-exposed (`scopedMediaIds`): lineage scopes to the commit's diff,
+* so a pair the user deleted between untouched entities stays deleted. A pair
+* the facts already resolved against the plan's base state is likewise skipped.
+* One-sided facts, text-only records, self pairs, and already-linked pairs are
+* skipped. Duplicate records collapse to one Relation.
+*/
+function planGeneratedRelations(input) {
+	const { state, facts } = input;
+	const scoped = input.scopedMediaIds;
+	const factKeys = new Set(facts.flatMap((fact) => [fact.outputAssetId, ...fact.inputAssetIds]));
+	const mediaByAssetKey = resolveMediaByAssetKey(state, factKeys);
+	const baseResolvable = new Set(resolvablePairs(resolveMediaByAssetKey(input.baseState, factKeys), facts));
+	const linkedPairs = new Set(state.relations.filter((relation) => relation.relation_kind === "generated").map((relation) => pairKey(relation.endpoint_0_entity_id, relation.endpoint_1_entity_id)));
+	const relations = [];
+	for (const fact of facts) for (const outputId of mediaByAssetKey.get(fact.outputAssetId) ?? []) for (const inputAssetId of fact.inputAssetIds) for (const inputId of mediaByAssetKey.get(inputAssetId) ?? []) {
+		if (outputId === inputId) continue;
+		if (!scoped.has(outputId) && !scoped.has(inputId)) continue;
+		const pair = pairKey(outputId, inputId);
+		if (linkedPairs.has(pair) || baseResolvable.has(pair)) continue;
+		linkedPairs.add(pair);
+		relations.push({
+			relation_id: input.newRelationId(),
+			relation_kind: "generated",
+			endpoint_0_entity_id: outputId,
+			endpoint_1_entity_id: inputId,
+			metadata: {},
+			trace: { synced_by: "generation-sync" }
+		});
+	}
+	return relations;
+}
+/**
+* Sync generation lineage after a confirmed entity commit. Any failure is
+* returned as a `failed` outcome instead of thrown, so the already-durable
+* commit result is never masked; a successful query that finds nothing is
+* `current`. Asset identities are immutable, so facts are queried once. A
+* revision conflict re-reads current entities and relations, re-plans, and
+* retries within `MAX_COMMIT_ATTEMPTS`; deleted endpoints are never recreated.
+*/
+async function syncGeneratedRelations(input) {
+	const { client, docId, baseState, entityCommands, loadFacts } = input;
+	try {
+		let state = await client.fetchState();
+		let scope = planGenerationScope(baseState, entityCommands, state);
+		if (scope.queryAssetKeys.length === 0) return { status: "current" };
+		const facts = parseGenerationFacts(await loadFacts(docId, scope.queryAssetKeys));
+		for (let attempt = 1; attempt <= MAX_COMMIT_ATTEMPTS; attempt++) {
+			if (scope.queryAssetKeys.length === 0) return { status: "current" };
+			const relations = planGeneratedRelations({
+				baseState,
+				state,
+				scopedMediaIds: scope.scopedMediaIds,
+				facts,
+				newRelationId: mintRelationId
+			});
+			if (relations.length === 0) return { status: "current" };
+			try {
+				await client.commit(state.revision, {
+					...state,
+					relations: [...state.relations, ...relations]
+				});
+				return {
+					status: "applied",
+					created_relation_ids: relations.map((relation) => relation.relation_id)
+				};
+			} catch (error) {
+				if (!(error instanceof MengineEntityHttpRequestError && error.status === 409) || attempt === MAX_COMMIT_ATTEMPTS) return {
+					status: "failed",
+					message: `generation lineage sync commit failed: ${errorMessage(error)}`
+				};
+				state = await client.fetchState();
+				scope = planGenerationScope(baseState, entityCommands, state);
+			}
+		}
+		return {
+			status: "failed",
+			message: "generation lineage sync exhausted its retry budget"
+		};
+	} catch (error) {
+		return {
+			status: "failed",
+			message: `generation lineage query failed: ${errorMessage(error)}`
+		};
+	}
+}
+function assetKeyOf(entity) {
+	if (!isMediaAssetVariantKind(entity.entity_kind)) return void 0;
+	const external = entity.payload?.external;
+	if (external == null || typeof external !== "object" || Array.isArray(external)) return void 0;
+	const { system, key } = external;
+	if (typeof system !== "string" || !ASSET_SYSTEMS.has(system)) return void 0;
+	if (typeof key !== "string" || key.length === 0 || key.trim() !== key) return void 0;
+	return key;
+}
+/** Media variants own their Asset locator; generation lookup never follows Relations. */
+function resolveMediaByAssetKey(state, factKeys) {
+	const systemByKey = /* @__PURE__ */ new Map();
+	for (const entity of state.entities) {
+		const key = assetKeyOf(entity);
+		if (key === void 0 || !factKeys?.has(key)) continue;
+		const system = entity.payload.external.system;
+		if (systemByKey.has(key) && systemByKey.get(key) !== system) throw new Error(`Ambiguous generation asset id ${key} across media and speech namespaces`);
+		systemByKey.set(key, system);
+	}
+	const resolved = /* @__PURE__ */ new Map();
+	for (const entity of state.entities) {
+		if (!isMediaAssetVariantKind(entity.entity_kind)) continue;
+		const key = assetKeyOf(entity);
+		if (key === void 0) continue;
+		const matches = resolved.get(key) ?? [];
+		matches.push(entity.entity_id);
+		resolved.set(key, matches);
+	}
+	return resolved;
+}
+function pairKey(endpoint0, endpoint1) {
+	return `${endpoint0}\u0000${endpoint1}`;
+}
+/** Pair keys the facts already resolve to under the given base bindings. */
+function resolvablePairs(mediaByAssetKey, facts) {
+	const pairs = [];
+	for (const fact of facts) for (const outputId of mediaByAssetKey.get(fact.outputAssetId) ?? []) for (const inputAssetId of fact.inputAssetIds) for (const inputId of mediaByAssetKey.get(inputAssetId) ?? []) if (outputId !== inputId) pairs.push(pairKey(outputId, inputId));
+	return pairs;
+}
+function mintRelationId() {
+	return `relation_${randomUUID()}`;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isRecord$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
 //#region src/migration-input.ts
 /** Validate host-recalled facts without accepting a caller-controlled snapshot or VV. */
 function parseMigrationAssetFacts(value) {
@@ -430,6 +611,18 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  readonly system: 'font-library';",
 	"  readonly key: string;",
 	"}",
+	"/**",
+	" * One ordered entry of the Caption's segment selection. `segmentId` quotes the",
+	" * composed AudioScript's own stable segment identity — a local id quoted by the",
+	" * variant, never a peer Entity reference. Text itself is never copied here;",
+	" * complete Caption content is assembled through its direct baseEntityIds.",
+	" * The optional `textRange` narrows one Segment to an intra-Segment sub-span",
+	" * (intra-segment re-segmentation); without it the whole Segment text is selected.",
+	" */",
+	"export type CaptionSegmentSelection = JsonObject & {",
+	"  readonly segmentId: string;",
+	"  readonly textRange?: CaptionTextRange;",
+	"};",
 	"export interface CaptionStyleFields {",
 	"  readonly font?: CaptionFontDescriptor;",
 	"  readonly fontSize?: number;",
@@ -442,6 +635,24 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  readonly positionX?: number;",
 	"  readonly positionY?: number;",
 	"}",
+	"/**",
+	" * Half-open `[start, end)` position window inside one Segment's text, counted",
+	" * in Unicode code points (not UTF-16 code units), so a boundary never splits a",
+	" * surrogate pair. Positions are non-negative safe integers with `start < end`;",
+	" * `end` must not exceed the Segment's code-point length.",
+	" */",
+	"export interface CaptionTextRange extends JsonObject {",
+	"  readonly start: number;",
+	"  readonly end: number;",
+	"}",
+	"export type CaptionTextSelection = JsonObject & {",
+	"  segmentId: string;",
+	"  /** Half-open Unicode code-point range within the selected source segment. */",
+	"  textRange?: {",
+	"    start: number;",
+	"    end: number;",
+	"  };",
+	"};",
 	"export type ClipEntityId = EntityId;",
 	"export type ClipPlacement =",
 	"  | {",
@@ -457,11 +668,21 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"      readonly hostClipEntityId: string;",
 	"      readonly anchorOffset: number;",
 	"    };",
+	"export interface ComposedPhoneticContent extends ComposedScriptContent {",
+	"  phonemeScript?: string;",
+	"  prosody?: JsonObject;",
+	"}",
+	"/** Read result only: base text is assembled from the real AudioScript row. */",
+	"export interface ComposedScriptContent {",
+	"  audio_script_entity_id: string;",
+	"  text: string;",
+	"  segments: ScriptTextSegment[];",
+	"}",
 	"export type CreateEntityInput = {",
 	"  [K in KnownEntityKind]: {",
 	"    entity_id?: string;",
 	"    entity_kind: K;",
-	"    payload: EntityPayloadByKind[K];",
+	"    payload: StoredEntityPayload<K>;",
 	"  };",
 	"}[KnownEntityKind];",
 	"export interface DeleteBgmInput {",
@@ -486,19 +707,29 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'clip-marker'",
 	"  | 'marker-content'",
 	"  | 'axvideo-marker'",
-	"  | 'marker-timeline';",
+	"  | '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;",
-	"  /** Return every explicitly imported Asset entity for a Memota asset id. */",
-	"  findByAssetId(assetId: string): SandboxEntity<'asset'>[];",
+	"  /** 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;",
-	"  /** Replace one Entity's owned payload without changing its identity or kind. */",
+	"  /** 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;",
-	"  /** Import one physical asset without implying a one-to-one media Entity mapping. */",
-	"  importAsset(input: ImportAssetInput): string;",
+	"  /** 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 {",
@@ -509,12 +740,12 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    role?: string;",
 	"  };",
 	"  clip: JsonObject;",
-	"  /** Asset-owned metadata. Peer media associations belong in physical-asset Relations. */",
+	"  /** Physical resource fields; never a copy of Caption content. */",
 	"  asset: JsonObject;",
-	"  video: BoundedNativeSequencePayload;",
-	"  audio: BoundedNativeSequencePayload;",
-	"  voice: BoundedNativeSequencePayload;",
-	"  image: UnboundedConstantSequencePayload;",
+	"  video: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  audio: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  voice: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  image: UnboundedConstantSequencePayload & MediaAssetPayload;",
 	"  'sequence-marker': JsonObject & {",
 	"    sourceRange: {",
 	"      start: number;",
@@ -535,15 +766,27 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    timeRemapping?: JsonValue;",
 	"    anchorOffset?: number;",
 	"    durationPolicy?: 'timeline';",
+	"    /** Directly assigned AudioScript annotation times; annotation Markers only. */",
+	"    segmentRanges?: {",
+	"      segmentId: string;",
+	"      startMs: number;",
+	"      endMs: number;",
+	"    }[];",
 	"  };",
 	"  viewport: JsonObject;",
 	"  'audio-script': JsonObject & {",
 	"    segments: ScriptTextSegment[];",
 	"  };",
 	"  'phonetic-script': JsonObject & {",
-	"    segments: ScriptTextSegment[];",
+	"    baseEntityIds: string[];",
+	"    phonemeScript?: string;",
+	"    prosody?: JsonObject;",
+	"  };",
+	"  caption: BoundedNativeSequencePayload & {",
+	"    baseEntityIds: string[];",
+	"    selections: CaptionTextSelection[];",
+	"    style?: JsonObject;",
 	"  };",
-	"  caption: BoundedNativeSequencePayload;",
 	"}",
 	"export interface EntityStoreSnapshot {",
 	"  revision: number;",
@@ -555,10 +798,18 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  readonly kind: 'image';",
 	"  readonly storageKey?: string;",
 	"}",
-	"export interface ImportAssetInput {",
-	"  asset_id: string;",
-	"  entity_id?: string;",
-	"  payload?: JsonObject;",
+	"export interface InsertCaptionClipInput {",
+	"  readonly timelineEntityId: 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. */",
+	"  readonly baseEntityIds: readonly string[];",
+	"  /** Ordered selection of the AudioScript segments this Caption displays. */",
+	"  readonly selections: readonly CaptionSegmentSelection[];",
+	"  /** Intrinsic cue length of the Caption entity itself; display comes from the placement. */",
+	"  readonly durationMs: number;",
+	"  readonly style?: CaptionStyleFields;",
+	"  readonly placement: ClipPlacement;",
 	"}",
 	"export interface InsertClipInput {",
 	"  readonly trackEntityId: string;",
@@ -623,20 +874,21 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'marker-timeline'",
 	"  | 'physical-asset'",
 	"  | 'generated'",
-	"  | 'phonetic-script-provenance'",
-	"  | 'caption-provenance'",
 	"  | 'caption-alignment'",
 	"  | 'clip-anchor'",
-	"  | 'audio-script-render';",
+	"  | 'phonetic-script-render'",
+	"  | 'audio-script-source'",
+	"  | 'audio-script-marker';",
 	"export interface LinearClipSpeed {",
 	"  readonly kind: 'linear';",
 	"  readonly rate: number;",
 	"  readonly mode?: string;",
 	"}",
-	"export interface LinkAudioScriptRenderRelationInput {",
+	"/** `audio-script-source(script, source)`; the script was transcribed from the source media. */",
+	"export interface LinkAudioScriptSourceRelationInput {",
 	"  relation_id?: string;",
-	"  output_entity_id: string;",
 	"  script_entity_id: string;",
+	"  source_entity_id: string;",
 	"  trace?: JsonObject;",
 	"}",
 	"export interface LinkClipAnchorRelationInput {",
@@ -651,6 +903,12 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  input_entity_id: string;",
 	"  trace?: JsonObject;",
 	"}",
+	"export interface LinkPhoneticScriptRenderRelationInput {",
+	"  relation_id?: string;",
+	"  output_entity_id: string;",
+	"  phonetic_script_entity_id: string;",
+	"  trace?: JsonObject;",
+	"}",
 	"interface LinkRelationBase {",
 	"  relation_id?: string;",
 	"  endpoint_0_entity_id: string;",
@@ -669,17 +927,20 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"      metadata?: JsonObject;",
 	"    })",
 	"  | (LinkRelationBase & {",
-	"      relation_kind: 'phonetic-script-provenance' | 'caption-provenance';",
-	"      metadata: JsonObject & {",
-	"        segmentAlignment: JsonValue;",
-	"      };",
-	"    })",
-	"  | (LinkRelationBase & {",
 	"      relation_kind: 'caption-alignment';",
 	"      metadata: JsonObject & {",
 	"        alignment: JsonValue;",
 	"      };",
 	"    });",
+	"/** Facts resolved from media storage. A trim window never substitutes for intrinsic duration. */",
+	"export type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceMediaAssetFact;",
+	"export type MediaAssetPayload = JsonObject & {",
+	"  external: {",
+	"    system: 'memota' | 'memota-speech';",
+	"    key: string;",
+	"  };",
+	"  storageKey?: string;",
+	"};",
 	"export type MediaClipInsertion =",
 	"  | {",
 	"      readonly kind: 'before';",
@@ -723,14 +984,16 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  list(): SandboxRelation[];",
 	"  /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */",
 	"  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];",
-	"  /** For physical-asset use sequence media as endpoint 0 and Asset as endpoint 1. */",
+	"  /** Link 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 audio-script-render(output,script) without positional endpoint ambiguity. */",
-	"  linkAudioScriptRender(input: LinkAudioScriptRenderRelationInput): 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;",
 	"}",
@@ -760,10 +1023,12 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  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;",
-	"  payload: EntityPayloadByKind[K];",
+	"  payload: StoredEntityPayload<K>;",
 	"}",
 	"export interface SandboxRelation {",
 	"  relation_id: string;",
@@ -821,6 +1086,13 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  /** Playback gain in decibels. */",
 	"  readonly volume: number;",
 	"}",
+	"/** Stored own fields; a variant may obtain required content fields from its declared bases. */",
+	"export type StoredEntityPayload<K extends KnownEntityKind> =",
+	"  | EntityPayloadByKind[K]",
+	"  | (JsonObject &",
+	"      Partial<EntityPayloadByKind[K]> & {",
+	"        baseEntityIds: string[];",
+	"      });",
 	"export interface TrimClipInput {",
 	"  readonly clipEntityId: string;",
 	"  readonly sourceRange: SequenceRange<number>;",
@@ -850,6 +1122,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  /** Passing `undefined` explicitly removes the optional remapping value. */",
 	"  readonly timeRemapping?: JsonValue | undefined;",
 	"}",
+	"/** Patch supplied fields on the assembled entity; omitted fields remain unchanged. */",
 	"export interface UpdateEntityInput {",
 	"  entity_id: string;",
 	"  payload: JsonObject;",
@@ -872,31 +1145,47 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  readonly kind: 'voice';",
 	"  readonly durationMs: number;",
 	"  readonly storageKey: string;",
-	"  readonly voice: VoiceDescriptor;",
+	"  /** 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;",
-	"  readonly text: 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 interface VoiceoverTakeInput {",
+	"export type VoiceoverTakeInput = {",
 	"  readonly timelineEntityId: string;",
 	"  /** Stable placed speech identity, distinct from media.assetId. */",
 	"  readonly voiceoverClipEntityId: string;",
-	"  readonly hostClipEntityId: string;",
-	"  readonly anchorOffset: number;",
 	"  readonly media: VoiceMediaAssetFact;",
-	"  /** Complete spoken text; the editor owns the deterministic local script segment identity. */",
-	"  readonly scriptText: string;",
+	"  /** 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[];",
 	"}",
@@ -927,6 +1216,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  deleteBgm(input: DeleteBgmInput): void;",
 	"  setCaptionVisibility(input: SetCaptionVisibilityInput): void;",
 	"  patchCaptionStyle(input: PatchCaptionStyleInput): void;",
+	"  insertCaptionClip(input: InsertCaptionClipInput): ClipEntityId;",
 	"}",
 	"export interface TimelineApi {",
 	"  snapshot(): EntityStoreSnapshot;",
@@ -949,25 +1239,27 @@ 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: return the Entity/Relation state summary and opaque base version.
+- 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, generated Relations and timeline edits belong in ONE plan. The sandbox has no network, storage or generation access. Pass recalled generation/asset facts through inputs. A successful run returns preview, logs, base revision and plan_id.
+- run-edit-script: inspect timeline.snapshot(), entities.*, and relations.*; edit.* operates existing Entity ids and creates the required Clip/SequenceMarker structural graph. Asset import, media Entity creation and timeline edits belong in ONE plan. The sandbox has no network, storage or generation access. Pass recalled asset facts through inputs; generation history is not a script input — the host program queries it itself after each commit. A successful run returns preview, logs, base revision and plan_id.
 - commit-plan: commit the complete Entity/Relation plan through revision CAS. The server derives the read-only timeline projection in the same transaction. There is no separate writable timeline plan and no preflight replay into a legacy editor. A failed transport is unconfirmed, never committed; retry the same plan_id.
 
 Default flow: snapshot → run-edit-script with auto_commit=false → inspect preview → commit-plan. Use auto_commit=true only for low-risk edits when the host does not need user confirmation. On version mismatch, rerun snapshot and the script; never try to patch a rejected journal by hand.
 
-Generating an Asset alone does not require an Entity. Using that resource in the editor DOES: recall the Asset facts, reuse or create the appropriate media Entity and physical-asset Relation, then pass the media Entity id to edit.insertClip. A raw asset id or URL is not valid contentEntityId. Asset and media Entity identity are not one-to-one. Recall generation history and author known generated(output,input) relations in the same plan; do not invent an input for text-only generation. relations.of(entityId) is endpoint-agnostic.
+Generating an Asset alone does not require an Entity. Using that resource in the editor DOES: recall the Asset facts, call entities.ensureMedia(fact), then pass its contentEntityId to edit.insertClip. A raw external asset id or URL is not valid contentEntityId. Image/Video/Audio/Voice are logical variants of Asset: a resource has ONE identity and ONE typed row owning both media fields and external {system,key}/storageKey, with no separate Asset row or physical-asset relation. ensureMedia returns contentEntityId and reuses that single identity by external asset id. Each placement still gets its own Clip and SequenceMarker. Generation lineage is program-synced: after each successful commit the tool connects existing typed Assets from host-recalled generation facts (endpoint 0 output, endpoint 1 input) that the host queries itself — do not pass generation history through inputs. Do not author generated Relations yourself, and never create an Entity merely to backfill or represent lineage; media variants the edit itself legitimately needs are still created normally. Text-only generation has no input and no lineage edge. relations.of(entityId) is endpoint-agnostic.
 `.trim();
 const MEDEO_TOOL_EXECUTION_RULES = `
 The host supplies the current document. Do not ask for, invent, or pass a document id.
 timeline.snapshot() returns the Entity/Relation graph with its revision, not a legacy VideoDraft. Inspect Timeline, Track, Clip, SequenceMarker and their relations to plan edits.
-Generation lineage and Memota asset facts are host-provided through inputs. Never invent an asset id, Entity kind, or peer Entity id.
-Before importing an Asset, call entities.findByAssetId(assetId), inspect every match, and decide whether an existing Entity represents the intended logical asset. Multiple matches are valid; do not assume Asset↔media is one-to-one.
+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.
-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.
+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.
-Voice links to AudioScript through audio-script-render(output,script). Caption owns text/style and is placed through a Clip anchored to the Voice Clip; caption alignment/provenance agree with that Voice/AudioScript. BGM Audio keeps factual source duration and its Marker declares durationPolicy:'timeline'. External Asset identity and storageKey are distinct from the placed Clip identity. Never introduce a speech entity kind.
-Create only the known entity kinds. On an empty document, explicitly create Timeline and Track(role='video_clip') and connect timeline-track before inserting a Clip. If snapshot reports legacy migration is required, recall the listed asset facts and call migrate-legacy first. Missing facts, unsupported layouts, and version conflicts fail closed; never fall back to an old timeline method or raw update endpoint.
+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.
+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 and four fixed Tracks before editing; inspect and reuse their IDs from timeline.snapshot(), never create another Timeline or Track for each operation. If snapshot reports legacy migration is required, recall the listed asset facts and call migrate-legacy first. Missing facts, unsupported layouts, and version conflicts fail closed; never fall back to an old timeline method or raw update endpoint.
 Use only the globals and methods declared by the following TypeScript interface. Values not declared here are unavailable.
 `.trim();
 /** Render the complete MEngine-owned context injected before one model call. */
@@ -1064,7 +1356,7 @@ const MEDEO_TOOL_PARAMETERS = {
 		},
 		inputs: {
 			type: "object",
-			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."
+			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",
@@ -1569,11 +1861,12 @@ function createMedeoTool(options) {
 			...peerId !== void 0 ? { peerId } : {}
 		});
 	}
-	function rememberPlan(docId, plan) {
+	function rememberPlan(docId, plan, baseState) {
 		const planId = randomUUID();
 		plans.set(planId, {
 			docId,
-			plan
+			plan,
+			...plan.plan_kind === "entities" ? { baseState: baseState && structuredClone(baseState) } : {}
 		});
 		while (plans.size > maxPlans) {
 			const protectedPlanIds = new Set([...pendingPushes.values()].map((pending) => pending.planId));
@@ -1588,7 +1881,7 @@ function createMedeoTool(options) {
 		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) {
+	function recordPushResult(docId, planId, plan, result, baseState) {
 		if (result.kind === "unconfirmed") {
 			pendingPushes.set(docId, plan.plan_kind === "timeline" ? {
 				kind: "timeline",
@@ -1598,21 +1891,107 @@ function createMedeoTool(options) {
 			} : {
 				kind: "entities",
 				planId,
-				plan
+				plan,
+				...baseState !== void 0 ? { baseState } : {}
 			});
 			return;
 		}
 		pendingPushes.delete(docId);
 		if (plan.plan_kind === "timeline" && result.kind === "rejected" && result.reason === "push_rejected") documents.delete(docId);
 	}
-	async function fetchEntityStateForSandbox(docId) {
-		return await getEntityClient(docId).fetchState();
+	async function fetchEntityStateForSandbox(docId, doc, pull) {
+		const client = getEntityClient(docId);
+		for (let attempt = 0; attempt < 4; attempt += 1) {
+			const state = await client.fetchState();
+			if (pendingPushes.has(docId)) return state;
+			const document = doc.snapshot();
+			const hasTimeline = state.entities.some((row) => row.entity_kind === "timeline");
+			const hasLegacyContent = Object.keys(document.part_library ?? {}).length > 0 || (document.tracks ?? []).some((track) => (track.items ?? []).length > 0);
+			if (!hasTimeline && hasLegacyContent) return state;
+			if (!hasTimeline) {
+				if (pull.warnings !== void 0) throw new Error("Editor initialization requires a fresh canonical snapshot; retry snapshot");
+				const baseRows = toDslRows(state);
+				const migrated = migrateLegacyTimelineToEntities(document, [], baseRows);
+				try {
+					await getGraphClient(docId).commit({
+						revision: state.revision,
+						rows: baseRows
+					}, migrated, { migrationBaseVv: encodeDocVersionMark(doc.versionMark()) });
+				} catch (error) {
+					if (!(error instanceof MengineHttpRequestError) || error.status !== 409) throw new Error(`Editor initialization was not confirmed; retry snapshot to reconcile state: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				pull = await observePull(doc);
+				continue;
+			}
+			const sandbox = new EntitySandbox({
+				state,
+				idFactory: (prefix) => `${prefix}_${randomUUID()}`
+			});
+			sandbox.ensureFoundation();
+			if (sandbox.commandCount === 0) return state;
+			if (pull.warnings !== void 0) throw new Error("Editor initialization requires a fresh canonical snapshot; retry snapshot");
+			try {
+				const committed = await client.commit(state.revision, sandbox.buildPlan().rows);
+				await doc.pull();
+				return committed;
+			} catch (error) {
+				if (!(error instanceof MengineEntityHttpRequestError) || error.status !== 409) throw new Error(`Editor initialization was not confirmed; retry snapshot to reconcile state: ${error instanceof Error ? error.message : String(error)}`);
+				pull = await observePull(doc);
+			}
+		}
+		throw new Error("Editor initialization conflicted repeatedly; take a fresh snapshot");
+	}
+	function getGraphClient(docId) {
+		return new EntityGraphHttpClient({
+			docId,
+			httpOrigin: requiredContext(options.httpOrigin, docId, "httpOrigin"),
+			...options.authToken === void 0 ? {} : { authToken: () => optionalContext(options.authToken, docId) },
+			...options.userId === void 0 ? {} : { userId: () => optionalContext(options.userId, docId) },
+			...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl }
+		});
 	}
-	async function commitCachedPlan(docId, _doc, plan, validation) {
+	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");
-		return await commitEntityPlan(getEntityClient(docId), plan);
+		const client = getEntityClient(docId);
+		const preCommitState = baseState ?? (options.loadGenerationFacts !== void 0 ? await client.fetchState() : void 0);
+		return await attachGenerationSync(docId, plan, await commitEntityPlan(client, plan), preCommitState);
+	}
+	/**
+	* After a confirmed entity commit, connect fact-matched generated Relations
+	* from host-recalled lineage. The commit is already durable, so a sync
+	* failure never fails the op; it is attached to the result and surfaced as a
+	* warning instead. The plan's diff against `baseState` scopes the sync:
+	* newly created media Asset identities — not untouched pairs or placement-only edits.
+	* One-sided facts are skipped silently inside the sync.
+	*/
+	async function attachGenerationSync(docId, plan, result, baseState) {
+		if (result.kind !== "committed" || options.loadGenerationFacts === void 0 || baseState === void 0) return result;
+		let outcome;
+		try {
+			outcome = await syncGeneratedRelations({
+				client: getEntityClient(docId),
+				docId,
+				baseState,
+				entityCommands: plan.entity_commands,
+				loadFacts: options.loadGenerationFacts
+			});
+		} catch (error) {
+			outcome = {
+				status: "failed",
+				message: error instanceof Error ? error.message : String(error)
+			};
+		}
+		const warnings = outcome.status === "failed" ? [{
+			kind: "generation_sync_failed",
+			message: outcome.message ?? "generation lineage sync failed"
+		}] : void 0;
+		return {
+			...result,
+			generation_sync: outcome,
+			...warnings !== void 0 ? { warnings } : {}
+		};
 	}
 	async function observePull(doc) {
 		const result = await doc.pull();
@@ -1635,7 +2014,7 @@ function createMedeoTool(options) {
 		if (docId.length === 0) throw new Error("doc_id must be a non-empty string");
 		if (contextId.length === 0) throw new Error("context_id must be a non-empty string");
 		return await runExclusive(docId, async (doc) => {
-			const [, entityState] = await Promise.all([observePull(doc), fetchEntityStateForSandbox(docId)]);
+			const entityState = await fetchEntityStateForSandbox(docId, doc, await observePull(doc));
 			const documentVersion = `${encodeDocVersionMark(doc.versionMark())}:entities:${entityState.revision}`;
 			const baselineKey = `${contextId}\u0000${docId}`;
 			const previousVersion = modelContextVersions.get(baselineKey);
@@ -1660,7 +2039,8 @@ function createMedeoTool(options) {
 	async function snapshot(input) {
 		return runExclusive(input.doc_id, async (doc) => {
 			assertNoPendingPush(input.doc_id);
-			const [pull, entityState] = await Promise.all([observePull(doc), fetchEntityStateForSandbox(input.doc_id)]);
+			const pull = await observePull(doc);
+			const entityState = await fetchEntityStateForSandbox(input.doc_id, doc, pull);
 			return {
 				ok: true,
 				op: "snapshot",
@@ -1675,13 +2055,7 @@ function createMedeoTool(options) {
 	async function migrate(input) {
 		return runExclusive(input.doc_id, async (doc) => {
 			assertNoPendingPush(input.doc_id);
-			const client = new EntityGraphHttpClient({
-				docId: input.doc_id,
-				httpOrigin: requiredContext(options.httpOrigin, input.doc_id, "httpOrigin"),
-				...options.authToken === void 0 ? {} : { authToken: () => optionalContext(options.authToken, input.doc_id) },
-				...options.userId === void 0 ? {} : { userId: () => optionalContext(options.userId, input.doc_id) },
-				...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl }
-			});
+			const client = getGraphClient(input.doc_id);
 			const base = await client.fetchState();
 			if (base.rows.entities.some((row) => row.entityKind === "timeline")) return {
 				ok: true,
@@ -1717,7 +2091,8 @@ function createMedeoTool(options) {
 	async function run(input) {
 		return runExclusive(input.doc_id, async (doc) => {
 			assertNoPendingPush(input.doc_id);
-			const [pull, entityState] = await Promise.all([observePull(doc), fetchEntityStateForSandbox(input.doc_id)]);
+			const pull = await observePull(doc);
+			const entityState = await fetchEntityStateForSandbox(input.doc_id, doc, pull);
 			const document = doc.snapshot();
 			const baseVersion = encodeDocVersionMark(doc.versionMark());
 			const result = await runEditScript({
@@ -1745,7 +2120,7 @@ function createMedeoTool(options) {
 				...result.plan,
 				doc_id: input.doc_id
 			};
-			const planId = rememberPlan(input.doc_id, plan);
+			const planId = rememberPlan(input.doc_id, plan, entityState);
 			const base = {
 				ok: true,
 				op: "run-edit-script",
@@ -1762,8 +2137,8 @@ function createMedeoTool(options) {
 				...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 commit = await commitCachedPlan(input.doc_id, doc, plan, void 0, entityState);
+			recordPushResult(input.doc_id, planId, plan, commit, entityState);
 			const warnings = mergeWarnings(pull.warnings, commitWarnings(commit));
 			return {
 				...base,
@@ -1779,8 +2154,8 @@ function createMedeoTool(options) {
 			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 result = pending.kind === "timeline" ? await retryPlanPush(doc, pending.opsApplied) : await commitCachedPlan(input.doc_id, doc, pending.plan, input.validation, pending.baseState);
+				recordPushResult(input.doc_id, input.plan_id, pending.plan, result, pending.kind === "entities" ? pending.baseState : void 0);
 				const warnings = commitWarnings(result);
 				return {
 					ok: true,
@@ -1797,8 +2172,8 @@ function createMedeoTool(options) {
 			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 result = await commitCachedPlan(input.doc_id, doc, cached.plan, input.validation, cached.baseState);
+			recordPushResult(input.doc_id, input.plan_id, cached.plan, result, cached.baseState);
 			const warnings = mergeWarnings(pull.warnings, commitWarnings(result));
 			return {
 				ok: true,