@mengine/medeo-tool 1.3.1-alpha.8 → 1.4.1-alpha.0

package/README.md

@@ -16,7 +16,7 @@ A host supplies only environment facts: Mengine HTTP origin, optional request
 identity headers, `fetch`, and a stable agent peer id.
 
 ```ts
-import { createMedeoTool } from '@mengine/medeo-tool';
+import { materializeResources, createMedeoTool } from '@mengine/medeo-tool';
 
 const medeo = createMedeoTool({
   httpOrigin: process.env.MENGINE_HTTP_ORIGIN!,
@@ -38,53 +38,39 @@ const commit = await medeo.handle({
   plan_id: run.plan_id,
 });
 
-// Media facts are recalled by the host and passed into the sandbox.
-// This example is text-to-image: there is no invented input-media entity.
+// Only the host imports resource facts. Model inputs contain domain identities.
+const [contentEntityId] = await materializeResources({ docId, httpOrigin }, [
+  { assetId: 'asset-from-host', kind: 'image' },
+]);
 const entityRun = await medeo.handle({
   op: 'run-edit-script',
   doc_id: docId,
-  inputs: { output_asset_id: 'asset-from-host', track_entity_id: existingTrackEntityId },
-  script: `
-if (typeof inputs.output_asset_id !== 'string' || typeof inputs.track_entity_id !== 'string') {
-  throw new Error('missing recalled generation facts');
-}
-const { contentEntityId: output } = entities.ensureMedia({
-  assetId: inputs.output_asset_id,
-  kind: 'image',
-});
-edit.insertClip({
-  trackEntityId: inputs.track_entity_id,
-  contentEntityId: output,
-  sourceRange: { start: 0, end: 1 },
-  duration: { mode: 'fixed', value: 5000 },
-  targetRange: { start: 0, end: 5000 },
-});
-  `,
+  inputs: { content_entity_id: contentEntityId, track_entity_id: existingTrackEntityId },
+  script: `edit.insertClip({
+    trackEntityId: inputs.track_entity_id,
+    contentEntityId: inputs.content_entity_id,
+    sourceRange: { start: 0, end: 1 }, duration: { mode: 'fixed', value: 5000 },
+    targetRange: { start: 0, end: 5000 },
+  });`,
 });
 
 await medeo.close();
 ```
 
-The sandbox has no network, storage, clock, or generation access. Materialize
-or recall speech/media side effects in the host first and pass stable facts
-through `inputs`. There is no automatic Asset→Entity projection: the model
-selects when to bring a recalled asset into the editor through `entities.ensureMedia`.
-The resolver gets or creates one typed Asset by external `(system, key)` within
-the document. Image/Video/Audio/Voice are logical Asset variants: the typed row
-directly owns `external`, `storageKey` and its media fields, and its Asset ID is
-also its content Entity ID. Imports create no separate physical-only Asset
-row and no `physical-asset` relation. Raw typed resource creation also reuses
-an existing identity; prefer `ensureMedia` with the recalled media kind.
-`findByAssetId` includes Voice (`memota-speech`) variants. There is no separate
-`importAsset` API.
-Generation facts currently carry bare asset IDs. If a returned fact matches
-both media and speech namespaces, synchronization fails explicitly without
-writing ambiguous lineage edges.
-Conflicting facts or duplicate candidates fail explicitly; no automatic
-merge or deletion occurs. This is the MEngine editor profile, not a global DSL
-cardinality rule. Separate Asset+media graphs are invalid: every media variant
-must directly own its external identity, with no read fallback or migration.
-Inline caption Assets without external identity are not deduplicated.
+The model has only business Entity/Relation operations. No Asset lookup,
+read, create, update, delete, import, binding or locator API is exposed in the
+sandbox or through another model tool. `ensureMedia`, `findByAssetId` and
+Asset-based editor shortcuts are host-only. Generic entity writes reject
+`external` and `storageKey`, and cannot access physical Asset rows or bindings.
+
+`materializeResources` is a host API. It creates media entities from factual
+resources, or Caption with composed AudioScript text, ASR annotation markers
+and an optional physical-asset binding. It publishes a native Loro update
+before returning domain Entity IDs. Text edits through Caption version its
+AudioScript base and rewire composition; Caption's own ID stays unchanged.
+Repeated materialization reuses the persisted resource binding. Generation
+facts, when supplied, are resolved before the same commit so resource import
+and ordered provenance are atomic.
 
 Before model context/snapshot/editing, the host ensures one Timeline and the four
 fixed Tracks (`video_clip`, `speech`, `caption`, `bgm`). Existing IDs, settings and

package/dist/{entity-contract-Dm3AMEC9.d.mts → entity-contract-DHasvrhq.d.mts}

@@ -138,7 +138,10 @@ interface SandboxRelation {
   trace: JsonObject;
 }
 interface EntityStoreSnapshot {
+  /** Causal compiler baseline; required for publishing edits. */
+  loroSnapshot?: string;
   revision: number;
+  /** Current AudioScript version attached to the project; initialized projects always attach a script, possibly empty. */
   audioScriptEntityId: string | null;
   entities: SandboxEntity[];
   relations: SandboxRelation[];
@@ -206,9 +209,6 @@ interface UnlinkRelationInput {
   relation_id: string;
 }
 type EntityCommand = {
-  kind: 'set-document-audio-script';
-  audioScriptEntityId: string | null;
-} | {
   kind: 'create-entity';
   entity: SandboxEntity;
 } | {
@@ -273,4 +273,4 @@ interface RelationFacade {
 }
 //#endregion
 export { SandboxEntity as _, EntityFacade as a, UpdateEntityInput as b, JsonObject as c, KnownEntityKind as d, KnownRelationKind as f, ResourceEntityKind as g, RelationFacade as h, EntityCommand as i, JsonPrimitive as l, LinkRelationInput as m, CreateEntityInput as n, EntityPlanState as o, LinkGeneratedRelationInput as p, DeleteEntityInput as r, EntityStoreSnapshot as s, AuthorableRelationKind as t, JsonValue as u, SandboxRelation as v, UnlinkRelationInput as y };
-//# sourceMappingURL=entity-contract-Dm3AMEC9.d.mts.map
+//# sourceMappingURL=entity-contract-DHasvrhq.d.mts.map

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { _ as SandboxEntity, a as EntityFacade, b as UpdateEntityInput, c as JsonObject, d as KnownEntityKind, f as KnownRelationKind, g as ResourceEntityKind, h as RelationFacade, i as EntityCommand, l as JsonPrimitive, m as LinkRelationInput, n as CreateEntityInput, o as EntityPlanState, p as LinkGeneratedRelationInput, r as DeleteEntityInput, s as EntityStoreSnapshot, t as AuthorableRelationKind, u as JsonValue, v as SandboxRelation, y as UnlinkRelationInput } from "./entity-contract-Dm3AMEC9.mjs";
+import { _ as SandboxEntity, a as EntityFacade, b as UpdateEntityInput, c as JsonObject, d as KnownEntityKind, f as KnownRelationKind, g as ResourceEntityKind, h as RelationFacade, i as EntityCommand, l as JsonPrimitive, m as LinkRelationInput, n as CreateEntityInput, o as EntityPlanState, p as LinkGeneratedRelationInput, r as DeleteEntityInput, s as EntityStoreSnapshot, t as AuthorableRelationKind, u as JsonValue, v as SandboxRelation, y as UnlinkRelationInput } from "./entity-contract-DHasvrhq.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";
 
@@ -49,6 +49,8 @@ interface SandboxCheckpoint {
   readonly index: number;
 }
 interface ChangePlan {
+  /** Native operations compiled against the causal sandbox baseline. */
+  loro_update?: string;
   readonly plan_kind: 'timeline' | 'entities';
   doc_id: string;
   base_version: string;
@@ -209,6 +211,29 @@ type EditScriptResult = {
 /** Run `script` against a forked document snapshot; always resolves (never rejects). */
 declare function runEditScript(options: RunEditScriptOptions): Promise<EditScriptResult>;
 //#endregion
+//#region src/entity/entity-http-client.d.ts
+interface EntityHttpClientOptions {
+  docId: string;
+  httpOrigin: string;
+  authToken?: string | (() => string | undefined);
+  userId?: string | (() => string | undefined);
+  fetchImpl?: typeof fetch;
+}
+//#endregion
+//#region src/entity/caption-asset-assembly.d.ts
+/** Optional physical artifact registered for one immutable Caption identity. */
+interface CaptionAssetFact {
+  readonly captionEntityId: string;
+  readonly assetId: string;
+  readonly storageKey: string;
+}
+/** Host-only lookup. Missing facts mean the Caption has no physical artifact. */
+type CaptionAssetsLoader = (docId: string, captionEntityIds: readonly string[]) => Promise<readonly CaptionAssetFact[]>;
+interface CaptionAssetAssemblyOutcome {
+  readonly status: 'applied' | 'current' | 'failed';
+  readonly message?: string;
+}
+//#endregion
 //#region src/entity/generation-sync.d.ts
 /** Factual generation lineage for recalled Memota assets, supplied by the host. */
 interface AssetGenerationFact {
@@ -246,7 +271,7 @@ declare const MEDEO_TOOL_DESCRIPTION: string;
 //#endregion
 //#region src/schema.d.ts
 declare const MEDEO_TOOL_NAME = "medeo";
-type MedeoToolOp = 'snapshot' | 'migrate-legacy' | 'run-edit-script' | 'commit-plan';
+type MedeoToolOp = 'snapshot' | 'run-edit-script' | 'commit-plan';
 /**
  * JSON Schema for the host-facing `medeo` tool surface.
  *
@@ -262,7 +287,7 @@ declare const MEDEO_TOOL_PARAMETERS: {
   readonly properties: {
     readonly op: {
       readonly type: "string";
-      readonly enum: readonly ["snapshot", "migrate-legacy", "run-edit-script", "commit-plan"];
+      readonly enum: readonly ["snapshot", "run-edit-script", "commit-plan"];
       readonly description: "Which Medeo document operation to run.";
     };
     readonly doc_id: {
@@ -279,110 +304,6 @@ declare const MEDEO_TOOL_PARAMETERS: {
       readonly type: "object";
       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 kind: {
-              readonly const: "voice";
-            };
-            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 timeout_ms: {
       readonly type: "integer";
       readonly minimum: 1;
@@ -404,25 +325,11 @@ declare const MEDEO_TOOL_PARAMETERS: {
     };
     readonly validation: {
       readonly type: "string";
-      readonly enum: readonly ["version"];
-      readonly description: "Commit with Entity revision CAS; reject concurrent changes.";
+      readonly enum: readonly ["preflight"];
+      readonly description: "Publish the native update already validated on its causal Loro fork.";
     };
   };
   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: {
@@ -571,6 +478,8 @@ interface CreateMedeoToolOptions {
    * names entities, relations, or endpoints.
    */
   loadGenerationFacts?: GenerationFactsLoader;
+  /** Assemble optional Caption artifacts by immutable entity ID; never exposed to scripts. */
+  loadCaptionAssets?: CaptionAssetsLoader;
   fetchImpl?: typeof fetch;
   /** @deprecated ManualSyncDoc has no SSE or reconnect loop. */
   sseReconnectDelayMs?: number;
@@ -599,10 +508,6 @@ 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;
@@ -615,9 +520,12 @@ type MedeoToolInput = {
   op: 'commit-plan';
   doc_id: string;
   plan_id: string;
-  validation?: 'version' | 'preflight';
+  validation?: 'preflight';
 };
 type MedeoToolWarning = {
+  kind: 'asset_assembly_failed';
+  message: string;
+} | {
   kind: 'pull_failed';
   message: string;
 } | {
@@ -625,22 +533,23 @@ type MedeoToolWarning = {
   message: string;
 };
 type EntityCommitResult = {
+  kind: 'conflicted';
+  accepted: true;
+  entity_revision: number;
+  message: string;
+} | {
   kind: 'committed';
   ops_applied: number;
-  collaborated: false;
+  collaborated: boolean;
   entity_revision: number; /** Present only when the host supplies loadGenerationFacts. */
   generation_sync?: GenerationSyncOutcome;
+  asset_assembly?: CaptionAssetAssemblyOutcome;
   warnings?: MedeoToolWarning[];
 } | {
   kind: 'unconfirmed';
   reason: 'push_failed';
   ops_applied: number;
   message: string;
-} | {
-  kind: 'rejected';
-  reason: 'entity_revision_mismatch';
-  expected: number;
-  actual: number;
 } | {
   kind: 'rejected';
   reason: 'entity_state_rejected';
@@ -649,13 +558,6 @@ 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;
@@ -728,5 +630,27 @@ type MedeoInitialDraft = VideoDraft;
  */
 declare function createMedeoTool(options: CreateMedeoToolOptions): MedeoTool;
 //#endregion
-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 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 ResourceEntityKind, type RunEditScriptOptions, type SandboxCheckpoint, type SandboxEntity, type SandboxRelation, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
+//#region src/entity/materialize-resources.d.ts
+/** Host facts only. This contract is never included in the model's sandbox API. */
+type GeneratedResource = MediaAssetFact | {
+  kind: 'caption';
+  assetId: string;
+  storageKey: string;
+  segments: readonly {
+    text: string;
+    startMs: number;
+    endMs: number; /** ASR word timing is available as an annotation for model segmentation. */
+    words?: readonly {
+      text: string;
+      startMs: number;
+      endMs: number;
+    }[];
+  }[];
+};
+/** Persist resources before model consumption. The host serializes repeated imports of the same generation task. */
+declare function materializeResources(options: EntityHttpClientOptions & {
+  loadGenerationFacts?: GenerationFactsLoader;
+}, resources: readonly GeneratedResource[]): Promise<readonly string[]>;
+//#endregion
+export { type AssetGenerationFact, type AuthorableRelationKind, type CaptionAssetAssemblyOutcome, type CaptionAssetFact, type CaptionAssetsLoader, 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 GeneratedResource, type GenerationFactsLoader, type GenerationSyncOutcome, 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 ResourceEntityKind, type RunEditScriptOptions, type SandboxCheckpoint, type SandboxEntity, type SandboxRelation, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, materializeResources, renderCompactProjection, renderPreview, runEditScript };
 //# sourceMappingURL=index.d.mts.map