@mengine/medeo-tool 1.4.1-alpha.0 → 1.4.1-alpha.2

package/README.md

@@ -57,11 +57,35 @@ const entityRun = await medeo.handle({
 await medeo.close();
 ```
 
-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.
+The sandbox exposes only business Entity/Relation operations. It has no Asset
+lookup, read, create, update, delete, import or binding API. `ensureMedia`,
+`findByAssetId` and Asset-based editor shortcuts remain host-only.
+Generation tools may return Asset IDs. Entity operations accept these IDs in
+`external: { system: 'memota', key: assetId }`; assembled entity reads preserve
+that reference. An Asset ID is not an Entity ID, a composition base or a Relation
+endpoint. Physical `storageKey` access and Asset rows remain host-only.
+
+`await rgetAssetFromEntity(entityId)` reads the immutable resource attached to an
+Entity through host I/O and returns `{ assetId, content }`. It does not accept an
+Asset ID. For a new Caption, pass `payload.external` to `entities.create`, then
+await this function before placing it. The host reads the resource and the
+session initializes Caption intrinsic timing, the composed project AudioScript
+text and its annotation Marker. No Asset row or physical-asset relation is
+created. Pending Caption initialization also completes before final validation.
+Failure publishes no partial plan. Repeated reads preserve edited text; raw
+resource content remains immutable. Native Loro updates retain the original
+causal baseline and merge independent collaborator edits.
+
+```js
+const caption = entities.create({
+  entity_kind: 'caption',
+  payload: {
+    external: { system: 'memota', key: inputs.captionAssetId },
+  },
+});
+const asset = await rgetAssetFromEntity(caption);
+console.log(entities.readCaptionContent(caption));
+```
 
 `materializeResources` is a host API. It creates media entities from factual
 resources, or Caption with composed AudioScript text, ASR annotation markers

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

@@ -118,10 +118,15 @@ interface EntityPayloadByKind {
     baseEntityIds: string[];
     selections: CaptionTextSelection[];
     style?: JsonObject;
+    segmentRanges?: {
+      segmentId: string;
+      startMs: number;
+      endMs: number;
+    }[];
   };
 }
 /** Stored own fields; a variant may obtain required content fields from its declared bases. */
-type StoredEntityPayload<K extends KnownEntityKind> = EntityPayloadByKind[K] | (JsonObject & Partial<EntityPayloadByKind[K]> & {
+type StoredEntityPayload<K extends KnownEntityKind> = EntityPayloadByKind[K] | (K extends 'caption' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never) | (JsonObject & Partial<EntityPayloadByKind[K]> & {
   baseEntityIds: string[];
 });
 interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {
@@ -273,4 +278,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-DHasvrhq.d.mts.map
+//# sourceMappingURL=entity-contract-Cpf3P69H.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-DHasvrhq.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-Cpf3P69H.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";
 
@@ -33,6 +33,15 @@ declare function collectAffectedPartIds(journal: readonly JournalEntry[]): Set<s
  */
 declare function renderPreview(document: VideoDocument, journal: readonly JournalEntry[]): string;
 //#endregion
+//#region src/entity/entity-asset.d.ts
+/** Immutable resource content resolved by the host for a document Entity. */
+interface EntityAssetContent {
+  assetId: string;
+  content: JsonValue;
+}
+/** Host-only I/O. The sandbox supplies an Entity, never an arbitrary Asset query. */
+type EntityAssetLoader = (docId: string, entity: SandboxEntity) => Promise<EntityAssetContent>;
+//#endregion
 //#region src/entity/entity-sandbox.d.ts
 type DomainIdFactory = (prefix: 'entity' | 'relation') => string;
 //#endregion
@@ -172,6 +181,7 @@ interface ConsoleShim {
  * injects loaders that break worker boot.
  */
 interface RunEditScriptOptions {
+  loadEntityAsset?: (entity: SandboxEntity) => Promise<EntityAssetContent>;
   document: VideoDocument;
   baseVersion: string;
   script: string;
@@ -480,6 +490,7 @@ interface CreateMedeoToolOptions {
   loadGenerationFacts?: GenerationFactsLoader;
   /** Assemble optional Caption artifacts by immutable entity ID; never exposed to scripts. */
   loadCaptionAssets?: CaptionAssetsLoader;
+  loadEntityAsset?: EntityAssetLoader;
   fetchImpl?: typeof fetch;
   /** @deprecated ManualSyncDoc has no SSE or reconnect loop. */
   sseReconnectDelayMs?: number;
@@ -652,5 +663,5 @@ 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 };
+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 EntityAssetContent, type EntityAssetLoader, 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

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as createEntityId, c as collectAffectedPartIds, i as businessState, l as renderPreview, n as EntitySandbox, o as createRelationId, s as isMediaAssetVariantKind, t as EditSandboxSession, u as renderCompactProjection } from "./script-session-DTq_VPEA.mjs";
+import { a as createEntityId, c as collectAffectedPartIds, i as businessState, l as renderPreview, n as EntitySandbox, o as createRelationId, s as isMediaAssetVariantKind, t as EditSandboxSession, u as renderCompactProjection } from "./script-session-lXpqmupK.mjs";
 import { LoroEntityDocument, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, base64ToBytes, bytesToBase64, compileEntityRows, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, ensureEditorFoundation, replayJournal, toVideoDocument } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
 import { createHash, randomUUID } from "node:crypto";
@@ -81,6 +81,26 @@ function runEditScript(options) {
 				armTimeout();
 				return;
 			}
+			if (message.t === "entity-asset") {
+				(async () => {
+					try {
+						if (!options.loadEntityAsset) throw new Error("Entity Asset loader is unavailable");
+						const result = await options.loadEntityAsset(message.entity);
+						if (!settled) worker.postMessage({
+							t: "entity-asset-result",
+							requestId: message.requestId,
+							result
+						});
+					} catch (error) {
+						if (!settled) worker.postMessage({
+							t: "entity-asset-result",
+							requestId: message.requestId,
+							error: error instanceof Error ? error.message : String(error)
+						});
+					}
+				})();
+				return;
+			}
 			if (message.t === "entry") {
 				ops.push(message.entry);
 				return;
@@ -742,6 +762,11 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'axvideo-marker'",
 	"  | 'marker-timeline'",
 	"  | 'audio-script-marker';",
+	"/** Immutable resource content resolved by the host for a document Entity. */",
+	"export interface EntityAssetContent {",
+	"  assetId: string;",
+	"  content: JsonValue;",
+	"}",
 	"export type EntityId = string;",
 	"export interface EntityPayloadByKind {",
 	"  axvideo: BoundedDerivedSequencePayload;",
@@ -751,10 +776,10 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    role?: string;",
 	"  };",
 	"  clip: JsonObject;",
-	"  video: BoundedNativeSequencePayload;",
-	"  audio: BoundedNativeSequencePayload;",
-	"  voice: BoundedNativeSequencePayload;",
-	"  image: UnboundedConstantSequencePayload;",
+	"  video: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  audio: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  voice: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  image: UnboundedConstantSequencePayload & MediaAssetPayload;",
 	"  'sequence-marker': JsonObject & {",
 	"    sourceRange: {",
 	"      start: number;",
@@ -795,6 +820,11 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    baseEntityIds: string[];",
 	"    selections: CaptionTextSelection[];",
 	"    style?: JsonObject;",
+	"    segmentRanges?: {",
+	"      segmentId: string;",
+	"      startMs: number;",
+	"      endMs: number;",
+	"    }[];",
 	"  };",
 	"}",
 	"export interface EntityStoreSnapshot {",
@@ -925,6 +955,12 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"        alignment: JsonValue;",
 	"      };",
 	"    });",
+	"export type MediaAssetPayload = JsonObject & {",
+	"  external: {",
+	"    system: 'memota' | 'memota-speech';",
+	"    key: string;",
+	"  };",
+	"};",
 	"export interface MoveClipInput {",
 	"  readonly clipEntityId: string;",
 	"  readonly trackEntityId: string;",
@@ -1018,6 +1054,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"/** Stored own fields; a variant may obtain required content fields from its declared bases. */",
 	"export type StoredEntityPayload<K extends KnownEntityKind> =",
 	"  | EntityPayloadByKind[K]",
+	"  | (K extends 'caption' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never)",
 	"  | (JsonObject &",
 	"      Partial<EntityPayloadByKind[K]> & {",
 	"        baseEntityIds: string[];",
@@ -1091,6 +1128,8 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"export declare const timeline: TimelineApi;",
 	"export declare const entities: BusinessEntityFacade;",
 	"export declare const relations: BusinessRelationFacade;",
+	"/** Resolve the resource attached to an Entity through the host; await before using a new Caption. */",
+	"export declare function rgetAssetFromEntity(entityId: string): Promise<EntityAssetContent>;",
 	"export declare function checkpoint(): SandboxCheckpoint;",
 	"export declare function rollbackTo(cp: SandboxCheckpoint): void;",
 	"export declare const inputs: Readonly<Record<string, unknown>>;",
@@ -1103,18 +1142,19 @@ Edit the authoritative Medeo Entity/Relation graph through a deterministic, side
 
 Operations:
 - snapshot: read the current Entity/Relation view, project attachments and causal Loro baseline. Reading does not initialize or mutate domain data.
-- run-edit-script: inspect timeline.snapshot(), entities.*, and relations.*; edit.* operates existing Entity ids and creates the required Clip/SequenceMarker structural graph. The sandbox has no network, storage or generation access. Use assembled entity fields; the host manages resource storage and generation provenance. 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. The sandbox has no direct network, storage or generation access. rgetAssetFromEntity(entityId) delegates an attached-resource read to the host. Use assembled entity fields; the host manages resource storage and generation provenance. A successful run returns preview, logs, base revision and plan_id.
 - commit-plan: publish the native Loro update compiled against the plan’s causal baseline. Concurrent independent edits merge through Loro. The timeline and AudioScript panel read the merged entity state. A failed transport is unconfirmed; retry the same plan_id so operation identities are preserved.
 
 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. Concurrent edits do not require replaying the script against a newer snapshot. If a domain conflict is reported, inspect the merged state and resolve it explicitly; never replace the complete document to force the edit through.
 
-Generated resources are materialized into domain Entities by the host. Use the returned Entity ids and assembled fields to edit or place content with edit.insertClip. Asset creation, lookup, reading, binding, resource locators and storage are host infrastructure, unavailable to the model through any tool or sandbox API. Each placement has its own Clip and SequenceMarker. Generation lineage is host-synced; relations.of(entityId) is endpoint-agnostic.
+Generation tools return Asset references, not domain Entity ids. An Asset id may be passed as an entity resource field: external: { system: "memota", key: assetId }. Create or update the domain Entity using entities.*, then place its Entity id with edit.insertClip. Asset ids are not Entity ids, baseEntityIds or Relation endpoints. The sandbox exposes no Asset creation, lookup, reading or storage API; the host resolves resource references. Each placement has its own Clip and SequenceMarker. Generation lineage is host-synced; 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.
-Inspect existing Image/Video/Audio/Voice Entities and their factual extents before placing them. The host materializes generated content and resolves its physical resource. Replace a Clip's content using another content Entity id. Never fabricate a duration.
-Caption composes AudioScript text. Its optional physical resource binding is host-owned. A Caption created from AudioScript may have no physical resource. Read and edit assembled fields through entities; do not author infrastructure bindings or generated Relations.
+Inspect existing Image/Video/Audio/Voice Entities and their factual extents before placing them. For an uploaded or generated resource, create its media Entity with the returned Asset id in external.key and the factual media extent. The host resolves its physical resource. Replace a Clip's content using another content Entity id. Never fabricate a duration.
+For a Caption Asset, create a Caption with payload:{external:{system:'memota',key:assetId}}, then await rgetAssetFromEntity(captionEntityId). This initializes its intrinsic segmentRanges/extent and the project AudioScript text in the same plan. The result {assetId,content} is the original resource content. entities.get/readCaptionContent then expose editable assembled text. Call the getter before placing a newly resource-backed Caption. Caption resource initialization also runs before final plan validation; failure aborts the plan. Do not transcribe repeatedly or infer speech absence from visual descriptions when an output_caption Asset already exists. Existing text edits are preserved on repeated reads. No Asset ID can be used as the getter argument.
+Caption composes AudioScript text. Its optional external field may carry the Caption Asset id; the host resolves that resource. A Caption created from AudioScript may have no physical resource. Read and edit assembled fields through entities; do not create Asset entities or physical-asset Relations.
 The editor projection 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.
 Entities own fields; ordinary Relations express associations; variants directly hold baseEntityIds and assemble the referenced entities. These foundations are fixed: implementation must follow them, never redefine them. Any entity may compose multiple bases. Equal field names from multiple bases (even equal values) are errors, even when the variant declares that field itself. After validating all base fields are unambiguous, explicitly declared own fields may override base fields without mutating the bases. Base ordering never resolves conflicts. AudioScript owns segmented text. Caption and PhoneticScript persist baseEntityIds including their AudioScript, plus their own fields; no composition Relation exists. Create the real bases before reading or committing a variant. Inside the DSL sandbox, entities.get/list expose complete assembled fields. Consumers read fields without inspecting base IDs or merging bases. entities.update patches supplied fields and routes inherited fields to their declaring entity; omitted fields remain unchanged. entities.declareFields explicitly declares own overrides and is distinct from an ordinary field edit. Persistence keeps owned fields only. entities.readCaptionContent(id) and entities.readPhoneticScriptContent(id) return assembled text. Missing/cyclic bases and field conflicts fail before persistence.
 Use edit.insertCaptionClip with baseEntityIds and selections, plus captionEntityId when generation returned a Caption identity; each voiceover caption also supplies baseEntityIds. A selection names segmentId and may use a half-open Unicode code-point textRange to split a segment for the screen without rewriting AudioScript. Generate Voice from an existing PhoneticScript, then use phoneticScriptEntityId in the voiceover helper or relations.linkPhoneticScriptRender({output_entity_id,phonetic_script_entity_id}) for its render relation. Caption and Voice have their own Clips; display anchoring is explicit and independent of composition/alignment.
@@ -1725,9 +1765,10 @@ function createMedeoTool(options) {
 				baseVersion,
 				entityState,
 				entityOnly: true,
+				loadEntityAsset: options.loadEntityAsset ? (entity) => options.loadEntityAsset(input.doc_id, entity) : void 0,
 				script: input.script,
 				...input.inputs !== void 0 ? { inputs: input.inputs } : {},
-				timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs,
+				timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs ?? 3e4,
 				memoryLimitMb: input.memory_limit_mb ?? options.sandbox?.memoryLimitMb
 			});
 			if (!result.ok) return {