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

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,35 @@ 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, 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.
+
+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. */
@@ -210,9 +214,9 @@ 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 +230,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,12 +241,116 @@ 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 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';
       readonly minimum: 1;
@@ -264,11 +372,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: {
@@ -436,6 +558,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;
@@ -477,6 +603,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 +682,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 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 };
 //# sourceMappingURL=index.d.mts.map