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

package/README.md

@@ -76,9 +76,31 @@ explicitly. Assets and media Entities are intentionally not one-to-one.
 The production tool exposes native Clip/Marker editing plus visual placement,
 voiceover, caption, and BGM helpers through its generated sandbox interface.
 They preserve structural and anchor relations in the same plan. Timeline targets
-are Entity IDs, never raw asset IDs or URLs. Asset import, media creation, factual `generated` relations, and Clip
-insertion belong in the **same entity plan**. `generated` retains output at
-endpoint 0 and input at endpoint 1, while lookup can use either endpoint.
+are Entity IDs, never raw asset IDs or URLs. Asset import, media creation, and
+Clip insertion belong in the **same entity plan**.
+
+Generation lineage is program-synced, not model-authored. After a confirmed
+entity commit the tool resolves the plan's diff against host-supplied generation
+facts and commits missing `generated` Relations between fact-matched media
+Entities already present in the document (endpoint 0 output, endpoint 1 input;
+lookup can use either endpoint). The diff covers created media Entities, edits
+that re-point an existing physical-asset binding or Asset external key, and
+creations; pairs already fact-resolvable before the plan stay untouched. Models
+do not pass generation history through inputs — the host queries it with
+`loadGenerationFacts(docId, assetIds)`, returning every known generation record
+involving the given asset ids in either role. Each record must carry an explicit
+`inputAssetIds` array: an explicit empty array declares text-only generation
+with no lineage edge, while a missing or non-array field is a malformed record
+that fails the whole query instead of being silently read as text-only.
+One-sided facts are skipped without creating entities or blocking the commit —
+lineage sync never backfills a missing source or output Entity; entity creation
+stays a model decision inside the edit plan. Repeated commits are idempotent,
+and deletions, rebindings, and revision conflicts are respected: a CAS-conflict
+retry re-derives the trigger keys from the fresh bindings and re-queries the
+newly scoped facts, so a backfillable edge is never misreported as current.
+An empty result array means no known lineage; a rejection means the lineage
+query failed and is reported as `generation_sync: {status:'failed'}` plus a
+`generation_sync_failed` warning — never as synced state.
 
 Entities own their facts: SequenceMarker owns source/target ranges, duration,
 and time remapping; Clip owns volume; Track owns role/visibility. Cross-entity

package/dist/index.d.mts

@@ -209,6 +209,38 @@ type EditScriptResult = {
 /** Run `script` against a forked document snapshot; always resolves (never rejects). */
 declare function runEditScript(options: RunEditScriptOptions): Promise<EditScriptResult>;
 //#endregion
+//#region src/entity/generation-sync.d.ts
+/** Factual generation lineage for recalled Memota assets, supplied by the host. */
+interface AssetGenerationFact {
+  /** External asset id of the generation output (memota asset or speech result id). */
+  readonly outputAssetId: string;
+  /** Factual input asset ids; empty for text-only generation. */
+  readonly inputAssetIds: readonly string[];
+}
+/**
+ * Host callback resolving lineage by external asset id. Implementations return
+ * every known generation record involving the given ids in either role; an
+ * empty array means no known lineage and a rejection means the lineage query
+ * failed. Entity and Relation semantics stay inside this package.
+ */
+type GenerationFactsLoader = (docId: string, assetIds: readonly string[]) => Promise<readonly AssetGenerationFact[]>;
+/**
+ * Outcome of the post-commit lineage sync. `failed` is always also surfaced as
+ * a `generation_sync_failed` warning so an unavailable lineage query is never
+ * presented as synced state.
+ */
+interface GenerationSyncOutcome {
+  /**
+   * applied: new generated Relations were committed.
+   * current: the query succeeded and nothing was missing (no created asset,
+   * single side absent, text-only generation, or pair already linked).
+   * failed: the host query or the sync commit failed.
+   */
+  readonly status: 'applied' | 'current' | 'failed';
+  readonly created_relation_ids?: readonly string[];
+  readonly message?: string;
+}
+//#endregion
 //#region src/prompt.d.ts
 declare const MEDEO_TOOL_DESCRIPTION: string;
 //#endregion
@@ -245,7 +277,7 @@ declare const MEDEO_TOOL_PARAMETERS: {
     };
     readonly inputs: {
       readonly type: 'object';
-      readonly 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.';
+      readonly 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.';
     };
     readonly asset_facts: {
       readonly type: 'array';
@@ -530,6 +562,15 @@ interface CreateMedeoToolOptions {
    * snapshot, and tolerates a concurrent creator winning the race.
    */
   loadInitialDraft?: (docId: string) => Promise<VideoDraft>;
+  /**
+   * Resolve factual generation lineage by external asset id after a confirmed
+   * entity commit. Return every known generation record involving the given
+   * ids in either role; an empty array means no known lineage and a rejection
+   * means the lineage query failed (surfaced as a warning, never as synced
+   * state). The package owns all Entity/Relation semantics: the host never
+   * names entities, relations, or endpoints.
+   */
+  loadGenerationFacts?: GenerationFactsLoader;
   fetchImpl?: typeof fetch;
   /** @deprecated ManualSyncDoc has no SSE or reconnect loop. */
   sseReconnectDelayMs?: number;
@@ -576,15 +617,20 @@ type MedeoToolInput = {
   plan_id: string;
   validation?: 'version' | 'preflight';
 };
-interface MedeoToolWarning {
+type MedeoToolWarning = {
   kind: 'pull_failed';
   message: string;
-}
+} | {
+  kind: 'generation_sync_failed';
+  message: string;
+};
 type EntityCommitResult = {
   kind: 'committed';
   ops_applied: number;
   collaborated: false;
-  entity_revision: number;
+  entity_revision: number; /** Present only when the host supplies loadGenerationFacts. */
+  generation_sync?: GenerationSyncOutcome;
+  warnings?: MedeoToolWarning[];
 } | {
   kind: 'unconfirmed';
   reason: 'push_failed';
@@ -682,5 +728,5 @@ type MedeoInitialDraft = VideoDraft;
  */
 declare function createMedeoTool(options: CreateMedeoToolOptions): MedeoTool;
 //#endregion
-export { type AuthorableRelationKind, type ChangePlan, type CommitPlan, type CommitPlanOptions, type CommitPlanResult, type CompactProjectionOptions, type ConsoleShim, type CreateEntityInput, type CreateMedeoToolOptions, type DeleteEntityInput, type EditFacade, EditSandboxSession, type EditSandboxSessionOptions, type EditScriptResult, type EntityCommand, type EntityCommitResult, type EntityFacade, type EntityPlanState, type EntityStoreSnapshot, type ImportAssetInput, type JsonObject, type JsonPrimitive, type JsonValue, type KnownEntityKind, type KnownRelationKind, type LinkGeneratedRelationInput, type LinkRelationInput, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, type MedeoCommitResult, type MedeoInitialDraft, type MedeoModelContext, type MedeoModelContextInput, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RelationFacade, type RunEditScriptOptions, type SandboxCheckpoint, type SandboxEntity, type SandboxRelation, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
+export { type AssetGenerationFact, type AuthorableRelationKind, type ChangePlan, type CommitPlan, type CommitPlanOptions, type CommitPlanResult, type CompactProjectionOptions, type ConsoleShim, type CreateEntityInput, type CreateMedeoToolOptions, type DeleteEntityInput, type EditFacade, EditSandboxSession, type EditSandboxSessionOptions, type EditScriptResult, type EntityCommand, type EntityCommitResult, type EntityFacade, type EntityPlanState, type EntityStoreSnapshot, type GenerationFactsLoader, type GenerationSyncOutcome, type ImportAssetInput, type JsonObject, type JsonPrimitive, type JsonValue, type KnownEntityKind, type KnownRelationKind, type LinkGeneratedRelationInput, type LinkRelationInput, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, type MedeoCommitResult, type MedeoInitialDraft, type MedeoModelContext, type MedeoModelContextInput, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RelationFacade, type RunEditScriptOptions, type SandboxCheckpoint, type SandboxEntity, type SandboxRelation, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -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,223 @@ 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"]);
+/** Entity kinds that may carry a generated Relation endpoint (DSL `GeneratedMedia`). */
+const GENERATED_MEDIA_KINDS = new Set([
+	"video",
+	"image",
+	"audio",
+	"voice"
+]);
+/** 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 createdMediaIds = /* @__PURE__ */ new Set();
+	const keyChangedAssetIds = /* @__PURE__ */ new Set();
+	const bindingTouchedMediaIds = /* @__PURE__ */ new Set();
+	for (const command of commands) if (command.kind === "create-entity") {
+		if (command.entity.entity_kind === "asset") keyChangedAssetIds.add(command.entity.entity_id);
+		else if (GENERATED_MEDIA_KINDS.has(command.entity.entity_kind)) createdMediaIds.add(command.entity.entity_id);
+	} else if (command.kind === "update-entity") {
+		const baseEntity = base.entities.find((entity) => entity.entity_id === command.entity_id);
+		if (baseEntity?.entity_kind !== "asset") continue;
+		const before = assetKeyOf(baseEntity);
+		const after = assetKeyOf({
+			entity_id: command.entity_id,
+			entity_kind: "asset",
+			payload: command.payload
+		});
+		if (after !== void 0 && before !== after) keyChangedAssetIds.add(command.entity_id);
+	} else if (command.kind === "link-relation") {
+		if (command.relation.relation_kind === "physical-asset") bindingTouchedMediaIds.add(command.relation.endpoint_0_entity_id);
+	} else if (command.kind === "unlink-relation") {
+		const removed = base.relations.find((relation) => relation.relation_id === command.relation_id);
+		if (removed?.relation_kind === "physical-asset") bindingTouchedMediaIds.add(removed.endpoint_0_entity_id);
+	}
+	const scoped = new Set([...createdMediaIds, ...bindingTouchedMediaIds]);
+	const assetsById = new Map(state.entities.filter((entity) => entity.entity_kind === "asset").map((entity) => [entity.entity_id, entity]));
+	for (const relation of state.relations) {
+		if (relation.relation_kind !== "physical-asset") continue;
+		if (!keyChangedAssetIds.has(relation.endpoint_1_entity_id)) continue;
+		scoped.add(relation.endpoint_0_entity_id);
+	}
+	const queryKeys = /* @__PURE__ */ new Set();
+	for (const relation of state.relations) {
+		if (relation.relation_kind !== "physical-asset") continue;
+		if (!scoped.has(relation.endpoint_0_entity_id)) continue;
+		const asset = assetsById.get(relation.endpoint_1_entity_id);
+		const key = asset === void 0 ? void 0 : assetKeyOf(asset);
+		if (key !== void 0) 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 fact-match through
+* physical-asset bindings, 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 mediaByAssetKey = resolveMediaByAssetKey(state);
+	const baseResolvable = new Set(resolvablePairs(resolveMediaByAssetKey(input.baseState), 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`. A revision conflict re-reads, re-derives the trigger keys from
+* the fresh bindings, queries any newly scoped facts, re-plans, and retries
+* within `MAX_COMMIT_ATTEMPTS` before reporting failure — a stale asset query
+* must never let a backfillable edge be reported as `current`.
+*/
+async function syncGeneratedRelations(input) {
+	const { client, docId, baseState, entityCommands, loadFacts } = input;
+	let state;
+	let facts = [];
+	const queriedKeys = /* @__PURE__ */ new Set();
+	try {
+		state = await client.fetchState();
+		let scope = planGenerationScope(baseState, entityCommands, state);
+		for (let attempt = 1; attempt <= MAX_COMMIT_ATTEMPTS; attempt++) {
+			const unseenKeys = scope.queryAssetKeys.filter((key) => !queriedKeys.has(key));
+			for (const key of unseenKeys) queriedKeys.add(key);
+			if (unseenKeys.length > 0) facts = [...facts, ...parseGenerationFacts(await loadFacts(docId, unseenKeys))];
+			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 (entity.entity_kind !== "asset") 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 Entity ids fact-matched to each external asset key. Bindings follow
+* the canonical physical-asset direction (endpoint 0 = sequence media,
+* endpoint 1 = Asset) that the DSL spec enforces.
+*/
+function resolveMediaByAssetKey(state) {
+	const assetsById = new Map(state.entities.filter((entity) => entity.entity_kind === "asset").map((entity) => [entity.entity_id, entity]));
+	const mediaKinds = new Set([...GENERATED_MEDIA_KINDS]);
+	const mediaIds = new Set(state.entities.filter((entity) => mediaKinds.has(entity.entity_kind)).map((entity) => entity.entity_id));
+	const resolved = /* @__PURE__ */ new Map();
+	for (const relation of state.relations) {
+		if (relation.relation_kind !== "physical-asset") continue;
+		if (!mediaIds.has(relation.endpoint_0_entity_id)) continue;
+		const asset = assetsById.get(relation.endpoint_1_entity_id);
+		const key = asset === void 0 ? void 0 : assetKeyOf(asset);
+		if (key === void 0) continue;
+		const media = resolved.get(key);
+		if (media === void 0) resolved.set(key, [relation.endpoint_0_entity_id]);
+		else if (!media.includes(relation.endpoint_0_entity_id)) media.push(relation.endpoint_0_entity_id);
+	}
+	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) {
@@ -951,20 +1168,20 @@ Edit the authoritative Medeo Entity/Relation graph through a deterministic, side
 Operations:
 - snapshot: return the Entity/Relation state summary and opaque base version.
 - migrate-legacy: explicitly migrate an existing legacy timeline using recalled asset_facts. MEngine reads the canonical document and version, verifies that editing facts are preserved, and commits migration alone. Then take a fresh snapshot before any edit; never pass a caller-created legacy snapshot or version.
-- run-edit-script: inspect timeline.snapshot(), entities.*, and relations.*; edit.* operates existing Entity ids and creates the required Clip/SequenceMarker structural graph. Asset import, media Entity creation, generated Relations and timeline edits belong in ONE plan. The sandbox has no network, storage or generation access. Pass recalled generation/asset facts through inputs. A successful run returns preview, logs, base revision and plan_id.
+- 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, 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. Generation lineage is program-synced: after each successful commit the tool connects existing media Entities 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 Entities the edit itself legitimately needs (for example placing a recalled input asset) 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.
+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.
 Before importing an Asset, call entities.findByAssetId(assetId), inspect every match, and decide whether an existing Entity represents the intended logical asset. Multiple matches are valid; do not assume Asset↔media is one-to-one.
 For recalled video/audio/voice, create a bounded/native payload whose extent end comes from factual media duration/coordinates in inputs; never fabricate a duration. Image uses unbounded/constant semantics and has no invented end. If required facts are absent, do not create the media Entity yet.
-For physical-asset authoring, use sequence media as endpoint_0_entity_id and Asset as endpoint_1_entity_id. For generated lineage, use linkGenerated so endpoint 0 is output and endpoint 1 is input. relations.of remains endpoint-agnostic for lookup.
+For physical-asset authoring, use sequence media as endpoint_0_entity_id and Asset as endpoint_1_entity_id. Generated lineage Relations are not model-authored: the tool derives them from host generation facts after a successful commit, so do not call relations.linkGenerated to record provenance. 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.
@@ -1064,7 +1281,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 +1786,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 +1806,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,7 +1816,8 @@ function createMedeoTool(options) {
 			} : {
 				kind: "entities",
 				planId,
-				plan
+				plan,
+				...baseState !== void 0 ? { baseState } : {}
 			});
 			return;
 		}
@@ -1608,11 +1827,49 @@ function createMedeoTool(options) {
 	async function fetchEntityStateForSandbox(docId) {
 		return await getEntityClient(docId).fetchState();
 	}
-	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:
+	* created media Entities, edits that re-point an existing physical-asset
+	* binding or Asset external key, and creations — not untouched pairs.
+	* 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();
@@ -1745,7 +2002,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 +2019,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 +2036,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 +2054,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,