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

package/README.md

@@ -1,14 +1,14 @@
 # `@mengine/medeo-tool`
 
-Node tool surface for editing a Medeo video document and its explicit
-Entity/Relation state through the deterministic edit sandbox.
+Node tool surface for editing the authoritative Medeo Entity/Relation graph
+through the deterministic edit sandbox. Timeline editing is entity editing,
+not a legacy document mutation followed by optional entity registration.
 
 The package owns the complete tool path:
 
 - compact snapshot projection;
 - trusted worker execution of an agent-authored JavaScript edit script;
-- op-journal `ChangePlan` caching;
-- versioned or per-op-preflight commit through `ManualSyncDoc`;
+- entity-command `ChangePlan` caching;
 - complete Entity/Relation snapshot reads and revision-CAS commits;
 - per-document serialization, document cache, and shutdown.
 
@@ -28,7 +28,8 @@ const snapshot = await medeo.handle({ op: 'snapshot', doc_id: docId });
 const run = await medeo.handle({
   op: 'run-edit-script',
   doc_id: docId,
-  script: 'await edit.deleteBgm({})',
+  script: 'edit.updateClip({ clipEntityId: inputs.clip_id, payload: { volume: -6 } })',
+  inputs: { clip_id: existingClipEntityId },
 });
 if (!run.ok || run.op !== 'run-edit-script') throw new Error('edit script failed');
 const commit = await medeo.handle({
@@ -38,25 +39,28 @@ const commit = await medeo.handle({
 });
 
 // Generation facts are recalled by the host and passed into the sandbox.
+// This example is text-to-image: there is no invented input-media entity.
 const entityRun = await medeo.handle({
   op: 'run-edit-script',
   doc_id: docId,
-  inputs: { output_asset_id: 'asset-from-host', generation_id: 'generation-from-host' },
+  inputs: { output_asset_id: 'asset-from-host', track_entity_id: existingTrackEntityId },
   script: `
-if (typeof inputs.output_asset_id !== 'string' || typeof inputs.generation_id !== 'string') {
+if (typeof inputs.output_asset_id !== 'string' || typeof inputs.track_entity_id !== 'string') {
   throw new Error('missing recalled generation facts');
 }
 const asset = entities.importAsset({ asset_id: inputs.output_asset_id });
-const input = entities.create({
+const output = entities.create({
   entity_kind: 'image',
   payload: { extent: { kind: 'unbounded', start: 0 }, sampling: 'constant', coordinateSpace: 'ms' },
 });
-const output = entities.create({
-  entity_kind: 'video',
-  payload: { extent: { kind: 'bounded', start: 0, end: 1000 }, sampling: 'native', coordinateSpace: 'ms' },
-});
 relations.link({ relation_kind: 'physical-asset', endpoint_0_entity_id: output, endpoint_1_entity_id: asset });
-relations.linkGenerated({ output_entity_id: output, input_entity_id: input, trace: { generation_id: inputs.generation_id } });
+edit.insertClip({
+  trackEntityId: inputs.track_entity_id,
+  contentEntityId: output,
+  sourceRange: { start: 0, end: 1 },
+  duration: { mode: 'fixed', value: 5000 },
+  targetRange: { start: 0, end: 5000 },
+});
   `,
 });
 
@@ -69,6 +73,57 @@ through `inputs`. There is no automatic Asset→Entity projection: the model
 selects and imports assets, creates only known typed Entities, and links them
 explicitly. Assets and media Entities are intentionally not one-to-one.
 
-Timeline mutations and Entity/Relation mutations use different storage and CAS
-boundaries. A single script plan cannot mix them; create and commit two plans
-when a workflow needs both.
+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, 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
+references are Relations. There is no separate orientation or timing profile.
+
+The server validates and commits the graph and its read-only Loro projection in
+one database transaction. `deleted_entity_ids` and `deleted_relation_ids` make
+deletion explicit; dropped rows without deletion intent are rejected. After
+cutover, raw Loro `/updates` cannot mutate the document. Legacy standalone
+sandbox exports remain library compatibility APIs, not a production-tool mode.
+
+Existing nonempty legacy documents require a separate version-CAS migration
+whose projection preserves existing editing facts. `snapshot` identifies that
+requirement and the media IDs needing factual metadata. Call
+`{op:'migrate-legacy',doc_id,asset_facts}` explicitly, then take a fresh snapshot
+before editing. The package reads the canonical document and current Loro
+version itself; it does not accept a caller-supplied snapshot or version, use a
+stale cached document after a failed pull, or combine migration with a new edit.
+Repeating migration on an entity timeline is read-only. An uncertain submission
+must be inspected and retried, never reported as committed.
+
+The compatibility reader covers the existing four lanes: Image/Video, Voice,
+Caption, and background Audio. Coordinates are whole milliseconds for this
+reader. It preserves linear visual remapping (`{kind:'linear',rate:2}`), including
+image display speed, and explicit anchor chains. Nonlinear remapping and multiple
+visual overlay tracks are not existing editor features and remain unsupported.

package/dist/{entity-contract-B3txrzTt.d.mts → entity-contract-DycLxdQ5.d.mts}

@@ -5,7 +5,7 @@ interface JsonObject {
   [key: string]: JsonValue;
 }
 type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
-type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-provenance' | 'caption-provenance' | 'caption-alignment';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-provenance' | 'caption-provenance' | 'caption-alignment' | 'clip-anchor' | 'audio-script-render';
 type AuthorableRelationKind = Exclude<KnownRelationKind, 'generated'>;
 interface BoundedNativeSequencePayload extends JsonObject {
   /** Factual coordinates from recalled media metadata; never invent an end/duration. */
@@ -69,6 +69,8 @@ interface EntityPayloadByKind {
       value: number;
     };
     timeRemapping?: JsonValue;
+    anchorOffset?: number;
+    durationPolicy?: 'timeline';
   };
   viewport: JsonObject;
   'audio-script': JsonObject & {
@@ -102,6 +104,13 @@ type CreateEntityInput = { [K in KnownEntityKind]: {
   entity_kind: K;
   payload: EntityPayloadByKind[K];
 } }[KnownEntityKind];
+interface UpdateEntityInput {
+  entity_id: string;
+  payload: JsonObject;
+}
+interface DeleteEntityInput {
+  entity_id: string;
+}
 interface ImportAssetInput {
   asset_id: string;
   entity_id?: string;
@@ -139,17 +148,44 @@ interface LinkGeneratedRelationInput {
   input_entity_id: string;
   trace?: JsonObject;
 }
+interface LinkClipAnchorRelationInput {
+  relation_id?: string;
+  child_clip_entity_id: string;
+  host_clip_entity_id: string;
+  trace?: JsonObject;
+}
+interface LinkAudioScriptRenderRelationInput {
+  relation_id?: string;
+  output_entity_id: string;
+  script_entity_id: string;
+  trace?: JsonObject;
+}
+interface UnlinkRelationInput {
+  relation_id: string;
+}
 type EntityCommand = {
   kind: 'create-entity';
   entity: SandboxEntity;
+} | {
+  kind: 'update-entity';
+  entity_id: string;
+  payload: JsonObject;
+} | {
+  kind: 'delete-entity';
+  entity_id: string;
 } | {
   kind: 'link-relation';
   relation: SandboxRelation;
+} | {
+  kind: 'unlink-relation';
+  relation_id: string;
 };
 interface EntityPlanState {
   base_revision: number;
   commands: readonly EntityCommand[];
   rows: EntityStoreSnapshot;
+  deleted_entity_ids: readonly string[];
+  deleted_relation_ids: readonly string[];
 }
 interface EntityFacade {
   list(): SandboxEntity[];
@@ -157,6 +193,10 @@ interface EntityFacade {
   /** Return every explicitly imported Asset entity for a Memota asset id. */
   findByAssetId(assetId: string): SandboxEntity<'asset'>[];
   create(input: CreateEntityInput): string;
+  /** Replace one Entity's owned payload without changing its identity or kind. */
+  update(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;
 }
@@ -168,7 +208,13 @@ interface RelationFacade {
   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;
+  /** Remove a Relation by identity; endpoint replacement is an explicit unlink plus link. */
+  unlink(input: UnlinkRelationInput): void;
 }
 //#endregion
-export { SandboxRelation as _, EntityPlanState as a, JsonObject as c, KnownEntityKind as d, KnownRelationKind as f, SandboxEntity as g, RelationFacade as h, EntityFacade as i, JsonPrimitive as l, LinkRelationInput as m, CreateEntityInput as n, EntityStoreSnapshot as o, LinkGeneratedRelationInput as p, EntityCommand as r, ImportAssetInput as s, AuthorableRelationKind as t, JsonValue as u };
-//# sourceMappingURL=entity-contract-B3txrzTt.d.mts.map
+export { SandboxEntity as _, EntityFacade as a, UpdateEntityInput as b, ImportAssetInput as c, JsonValue as d, KnownEntityKind as f, RelationFacade as g, LinkRelationInput as h, EntityCommand as i, JsonObject as l, LinkGeneratedRelationInput as m, CreateEntityInput as n, EntityPlanState as o, KnownRelationKind as p, DeleteEntityInput as r, EntityStoreSnapshot as s, AuthorableRelationKind as t, JsonPrimitive as u, SandboxRelation as v, UnlinkRelationInput as y };
+//# sourceMappingURL=entity-contract-DycLxdQ5.d.mts.map

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { _ as SandboxRelation, a as EntityPlanState, c as JsonObject, d as KnownEntityKind, f as KnownRelationKind, g as SandboxEntity, h as RelationFacade, i as EntityFacade, l as JsonPrimitive, m as LinkRelationInput, n as CreateEntityInput, o as EntityStoreSnapshot, p as LinkGeneratedRelationInput, r as EntityCommand, s as ImportAssetInput, t as AuthorableRelationKind, u as JsonValue } from "./entity-contract-B3txrzTt.mjs";
-import { JournalEntry, ManualSyncDoc, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft, fromVideoDocument } from "@mengine/medeo-client";
+import { _ as SandboxEntity, a as EntityFacade, b as UpdateEntityInput, c as ImportAssetInput, d as JsonValue, f as KnownEntityKind, g as RelationFacade, h as LinkRelationInput, i as EntityCommand, l as JsonObject, m as LinkGeneratedRelationInput, n as CreateEntityInput, o as EntityPlanState, p as KnownRelationKind, r as DeleteEntityInput, s as EntityStoreSnapshot, t as AuthorableRelationKind, u as JsonPrimitive, v as SandboxRelation, y as UnlinkRelationInput } from "./entity-contract-DycLxdQ5.mjs";
+import { JournalEntry, ManualSyncDoc, MediaAssetFact, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft, fromVideoDocument } from "@mengine/medeo-client";
 import { AddSpeechesInput, AddVideoClipsInput, AdjustBgmVolumeInput, AdjustSpeechVolumeInput, AdjustVideoClipDurationInput, AdjustVideoClipVolumeInput, ChangeSpeechScriptInput, ChangeSpeechVoiceInput, DeleteBgmInput, DeleteSpeechesInput, DeleteVideoClipsInput, MoveSpeechesInput, MoveVideoClipsByAnchorInput, MoveVideoClipsInput, ReplaceVideoClipContentInput, ReplaceVideoClipSequenceInput, SetBgmInput, SetCaptionStyleInput, SetCaptionVisibilityInput, SetVideoClipSpeedShiftInput } from "@mengine/medeo-client/schemas";
 
 //#region src/document/compact-projection.d.ts
@@ -56,6 +56,8 @@ interface ChangePlan {
   entity_base_revision: number;
   entity_commands: readonly EntityCommand[];
   entity_rows?: EntityStoreSnapshot;
+  deleted_entity_ids?: readonly string[];
+  deleted_relation_ids?: readonly string[];
   preview: string;
   logs: string[];
 }
@@ -176,6 +178,8 @@ interface RunEditScriptOptions {
   entityState?: EntityStoreSnapshot;
   /** Deterministic id mint label for tests; omit to use the default ULID factory. */
   idLabel?: string;
+  /** @internal Select the graph-native Entity session used by the production host. */
+  entityOnly?: boolean;
   /** Hard wall-clock timeout; default 2000 ms. */
   timeoutMs?: number;
   /** V8 old-generation ceiling for the worker; default 256 MB. */
@@ -205,14 +209,46 @@ 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
 //#region src/schema.d.ts
 declare const MEDEO_TOOL_NAME = "medeo";
-type MedeoToolOp = 'snapshot' | 'run-edit-script' | 'commit-plan';
+type MedeoToolOp = 'snapshot' | 'migrate-legacy' | 'run-edit-script' | 'commit-plan';
 /**
- * JSON Schema for the host-facing three-op `medeo` tool surface.
+ * JSON Schema for the host-facing `medeo` tool surface.
  *
  * The schema intentionally does not return or accept the full op journal:
  * journals stay in the tool process and are referenced by `plan_id`. This keeps
@@ -226,7 +262,7 @@ declare const MEDEO_TOOL_PARAMETERS: {
   readonly properties: {
     readonly op: {
       readonly type: 'string';
-      readonly enum: readonly ['snapshot', 'run-edit-script', 'commit-plan'];
+      readonly enum: readonly ['snapshot', 'migrate-legacy', 'run-edit-script', 'commit-plan'];
       readonly description: 'Which Medeo document operation to run.';
     };
     readonly doc_id: {
@@ -237,11 +273,115 @@ declare const MEDEO_TOOL_PARAMETERS: {
     readonly script: {
       readonly type: 'string';
       readonly minLength: 1;
-      readonly description: 'JavaScript body for run-edit-script. It receives edit, timeline, entities, relations, checkpoint, rollbackTo, inputs, and console. A plan may mutate the timeline or Entity/Relation state, never both.';
+      readonly description: 'JavaScript body for run-edit-script. Use edit, timeline, entities, relations, checkpoint, rollbackTo, inputs, and console. Asset import, media relations, and timeline entity edits share one entity plan.';
     };
     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';
+      readonly 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.';
+      readonly items: {
+        readonly oneOf: readonly [{
+          readonly type: 'object';
+          readonly additionalProperties: false;
+          readonly required: readonly ['assetId', 'kind'];
+          readonly properties: {
+            readonly assetId: {
+              readonly type: 'string';
+              readonly minLength: 1;
+            };
+            readonly kind: {
+              readonly const: 'image';
+            };
+            readonly storageKey: {
+              readonly type: 'string';
+              readonly minLength: 1;
+            };
+          };
+        }, {
+          readonly type: 'object';
+          readonly additionalProperties: false;
+          readonly required: readonly ['assetId', 'kind', 'durationMs'];
+          readonly properties: {
+            readonly assetId: {
+              readonly type: 'string';
+              readonly minLength: 1;
+            };
+            readonly kind: {
+              readonly const: 'video';
+            };
+            readonly durationMs: {
+              readonly type: 'integer';
+              readonly minimum: 1;
+            };
+            readonly storageKey: {
+              readonly type: 'string';
+              readonly minLength: 1;
+            };
+          };
+        }, {
+          readonly type: 'object';
+          readonly additionalProperties: false;
+          readonly required: readonly ['assetId', 'kind', 'durationMs', 'storageKey'];
+          readonly properties: {
+            readonly assetId: {
+              readonly type: 'string';
+              readonly minLength: 1;
+            };
+            readonly kind: {
+              readonly const: 'audio';
+            };
+            readonly durationMs: {
+              readonly type: 'integer';
+              readonly minimum: 1;
+            };
+            readonly storageKey: {
+              readonly type: 'string';
+              readonly minLength: 1;
+            };
+          };
+        }, {
+          readonly type: 'object';
+          readonly additionalProperties: false;
+          readonly required: readonly ['assetId', 'kind', 'durationMs', 'storageKey', 'voice'];
+          readonly properties: {
+            readonly assetId: {
+              readonly type: 'string';
+              readonly minLength: 1;
+            };
+            readonly durationMs: {
+              readonly type: 'integer';
+              readonly minimum: 1;
+            };
+            readonly storageKey: {
+              readonly type: 'string';
+              readonly minLength: 1;
+            };
+            readonly voice: {
+              readonly type: 'object';
+              readonly additionalProperties: false;
+              readonly required: readonly ['system', 'key'];
+              readonly properties: {
+                readonly system: {
+                  readonly const: 'voice-library';
+                };
+                readonly key: {
+                  readonly type: 'string';
+                  readonly minLength: 1;
+                };
+                readonly name: {
+                  readonly type: 'string';
+                };
+              };
+            };
+            readonly kind: {
+              readonly const: 'voice';
+            };
+          };
+        }];
+      };
     };
     readonly timeout_ms: {
       readonly type: 'integer';
@@ -264,11 +404,25 @@ declare const MEDEO_TOOL_PARAMETERS: {
     };
     readonly validation: {
       readonly type: 'string';
-      readonly enum: readonly ['version', 'preflight'];
-      readonly description: 'Timeline commit mode: version rejects any concurrent change; preflight revalidates each op. Entity plans always use revision CAS and reject preflight.';
+      readonly enum: readonly ['version'];
+      readonly description: 'Commit with Entity revision CAS; reject concurrent changes.';
     };
   };
   readonly oneOf: readonly [{
+    readonly required: readonly ['op', 'doc_id', 'asset_facts'];
+    readonly properties: {
+      readonly op: {
+        readonly const: 'migrate-legacy';
+      };
+      readonly doc_id: {
+        readonly $ref: '#/properties/doc_id';
+      };
+      readonly asset_facts: {
+        readonly $ref: '#/properties/asset_facts';
+      };
+    };
+    readonly additionalProperties: false;
+  }, {
     readonly required: readonly ['op', 'doc_id'];
     readonly properties: {
       readonly op: {
@@ -408,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;
@@ -436,6 +599,10 @@ interface MedeoModelContext {
 type MedeoToolInput = {
   op: 'snapshot';
   doc_id: string;
+} | {
+  op: 'migrate-legacy';
+  doc_id: string;
+  asset_facts: readonly MediaAssetFact[];
 } | {
   op: 'run-edit-script';
   doc_id: string;
@@ -450,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';
@@ -477,6 +649,13 @@ type EntityCommitResult = {
 };
 type MedeoCommitResult = CommitPlanResult | EntityCommitResult;
 type MedeoToolResult = {
+  ok: true;
+  op: 'migrate-legacy';
+  doc_id: string;
+  migration_status: 'committed' | 'already_entity';
+  entity_revision: number;
+  next_action: 'snapshot';
+} | {
   ok: true;
   op: 'snapshot';
   doc_id: string;
@@ -549,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 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, 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