@mengine/medeo-tool 2.0.1-alpha.10 → 2.0.1-alpha.12

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as UpdateEntityInput, S as UnlinkRelationInput, _ as LinkRelationInput, a as DeleteEntityInput, b as SandboxEntity, c as EntitySandboxCheckpoint, d as JsonObject, f as JsonPrimitive, g as LinkGeneratedRelationInput, h as KnownRelationKind, i as CreateEntityInput, l as EntityStoreSnapshot, m as KnownEntityKind, n as BusinessEntityFacade, o as EntityCommand, p as JsonValue, r as BusinessRelationFacade, s as EntityPlanState, t as AuthorableRelationKind, u as EntityUpdateInput, v as RelationUpdateInput, x as SandboxRelation, y as ResourceEntityKind } from "./entity-contract-Cf3AiSe7.mjs";
+import { C as UpdateEntityInput, S as UnlinkRelationInput, _ as LinkRelationInput, a as DeleteEntityInput, b as SandboxEntity, c as EntitySandboxCheckpoint, d as JsonObject, f as JsonPrimitive, g as LinkGeneratedRelationInput, h as KnownRelationKind, i as CreateEntityInput, l as EntityStoreSnapshot, m as KnownEntityKind, n as BusinessEntityFacade, o as EntityCommand, p as JsonValue, r as BusinessRelationFacade, s as EntityPlanState, t as AuthorableRelationKind, u as EntityUpdateInput, v as RelationUpdateInput, x as SandboxRelation, y as ResourceEntityKind } from "./entity-contract-DNIIwpn1.mjs";
 import { JournalEntry, ManualSyncDoc, MediaAssetFact, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft } from "@mengine/medeo-client";
 
 //#region src/document/compact-projection.d.ts
@@ -50,7 +50,15 @@ interface EntityAssetContent {
   content: JsonValue;
 }
 /** Host-only I/O. The sandbox supplies an Entity, never an arbitrary Asset query. */
-type EntityAssetLoader = (docId: string, entity: SandboxEntity) => Promise<EntityAssetContent>;
+/**
+ * Resolve one entity's stored resource.
+ *
+ * The Asset travels with the entity because the locator lives on the Asset
+ * alone: an entity made from stored bytes names them through a `from-asset`
+ * Relation, never on its own row, so a loader given only the entity would have
+ * nothing to look up.
+ */
+type EntityAssetLoader = (docId: string, entity: SandboxEntity, asset: SandboxEntity) => Promise<EntityAssetContent>;
 /** Program-only initial resource creation; never exposed as a sandbox API. */
 type EntityAssetWriter = (docId: string, entity: SandboxEntity, content: JsonValue) => Promise<EntityAssetContent>;
 //#endregion
@@ -108,7 +116,7 @@ interface ConsoleShim {
 interface RunEditScriptOptions {
   /** Document the plan will be committed against; stated by the host. */
   docId: string;
-  loadEntityAsset?: (entity: SandboxEntity) => Promise<EntityAssetContent>;
+  loadEntityAsset?: (entity: SandboxEntity, asset: SandboxEntity) => Promise<EntityAssetContent>;
   writeEntityAsset?: (entity: SandboxEntity, content: EntityAssetContent['content']) => Promise<EntityAssetContent>;
   document: VideoDocument;
   baseVersion: string;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as createEntityId, i as businessState, o as createRelationId, s as isMediaAssetVariantKind, t as EntitySandbox } from "./entity-sandbox-BTR2cRl1.mjs";
+import { a as createEntityId, i as businessState, o as createRelationId, s as isMediaAssetVariantKind, t as EntitySandbox } from "./entity-sandbox-DpIkxcei.mjs";
 import { ManualSyncDoc, MengineHttpClient, ValidationError, base64ToBytes, bytesToBase64, compileEntityRows, createPlainMemoryAdapter, decodeDocVersionMark, effectiveVideoClipDurationMs, encodeDocVersionMark, replayJournal, solveVideoDocument, speedOf } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
 import { createHash, randomUUID } from "node:crypto";
@@ -226,7 +226,7 @@ function runEditScript(options) {
 							throw new Error("Entity Asset writer is unavailable");
 						}))(message.entity, message.content) : await (options.loadEntityAsset ?? (() => {
 							throw new Error("Entity Asset loader is unavailable");
-						}))(message.entity);
+						}))(message.entity, message.asset);
 						if (!settled) worker.postMessage({
 							t: "entity-asset-result",
 							requestId: message.requestId,
@@ -689,33 +689,39 @@ async function syncGeneratedRelations(input) {
 		};
 	}
 }
-function assetKeyOf(entity) {
-	if (!isMediaAssetVariantKind(entity.entity_kind)) return void 0;
-	const external = entity.payload?.external;
-	if (external == null || typeof external !== "object" || Array.isArray(external)) return void 0;
-	const { system, key } = external;
-	if (typeof system !== "string" || !ASSET_SYSTEMS.has(system)) return void 0;
-	if (typeof key !== "string" || key.length === 0 || key.trim() !== key) return void 0;
-	return key;
+/** The locator an entity reaches through `from-asset`; only Assets state one. */
+function assetLocatorOf(state, entityId) {
+	const assetIds = state.relations.filter((relation) => relation.relation_kind === "from-asset").map((relation) => relation.endpoint_0_entity_id === entityId ? relation.endpoint_1_entity_id : relation.endpoint_1_entity_id === entityId ? relation.endpoint_0_entity_id : void 0).filter((id) => id !== void 0);
+	for (const assetId of assetIds) {
+		const asset = state.entities.find((row) => row.entity_id === assetId && row.entity_kind === "asset");
+		const system = asset?.payload.system;
+		const key = asset?.payload.key;
+		if (typeof system !== "string" || !ASSET_SYSTEMS.has(system)) continue;
+		if (typeof key !== "string" || key.length === 0 || key.trim() !== key) continue;
+		return {
+			system,
+			key
+		};
+	}
 }
-/** Media variants own their Asset locator; generation lookup never follows Relations. */
+/**
+* Media reaches its Asset through `from-asset`, so lineage lookup follows that
+* Relation — the locator is never copied onto the medium's own row.
+*/
 function resolveMediaByAssetKey(state, factKeys) {
 	const systemByKey = /* @__PURE__ */ new Map();
-	for (const entity of state.entities) {
-		const key = assetKeyOf(entity);
-		if (key === void 0 || !factKeys?.has(key)) continue;
-		const system = entity.payload.external.system;
-		if (systemByKey.has(key) && systemByKey.get(key) !== system) throw new Error(`Ambiguous generation asset id ${key} across media and speech namespaces`);
-		systemByKey.set(key, system);
-	}
 	const resolved = /* @__PURE__ */ new Map();
 	for (const entity of state.entities) {
 		if (!isMediaAssetVariantKind(entity.entity_kind)) continue;
-		const key = assetKeyOf(entity);
-		if (key === void 0) continue;
-		const matches = resolved.get(key) ?? [];
+		const locator = assetLocatorOf(state, entity.entity_id);
+		if (locator === void 0) continue;
+		if (factKeys?.has(locator.key)) {
+			if (systemByKey.has(locator.key) && systemByKey.get(locator.key) !== locator.system) throw new Error(`Ambiguous generation asset id ${locator.key} across media and speech namespaces`);
+			systemByKey.set(locator.key, locator.system);
+		}
+		const matches = resolved.get(locator.key) ?? [];
 		matches.push(entity.entity_id);
-		resolved.set(key, matches);
+		resolved.set(locator.key, matches);
 	}
 	return resolved;
 }
@@ -779,6 +785,18 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    entity_id?: string;",
 	"    entity_kind: K;",
 	"    payload: StoredEntityPayload<K>;",
+	"    /**",
+	"     * The stored resource this entity is made from.",
+	"     *",
+	"     * Naming it here is the only way to say where an entity's bytes come from:",
+	"     * the Asset row and the `from-asset` Relation that reaches it are assembled",
+	"     * by the host, never authored. Only a kind that declares `FromAsset` —",
+	"     * video, audio, image, caption, audio-script — accepts one.",
+	"     */",
+	"    asset?: {",
+	"      system: 'memota' | 'memota-speech';",
+	"      key: string;",
+	"    };",
 	"  };",
 	"}[KnownEntityKind];",
 	"export interface DeleteEntityInput {",
@@ -1047,13 +1065,13 @@ Entities own data. Relations associate two existing entities; endpoint_0 and end
 
 Variants directly hold baseEntityIds. Assembly validates every base before applying explicit own overrides: two bases supplying the same field are an error even if values match or the variant declares that field. Missing/cyclic bases fail. Consumers operate assembled fields without copying inherited content or resolving owners themselves. An owned-field edit creates a new immutable entity version. Base changes automatically advance variant base references and project attachments without versioning an unchanged variant. A variant-owned change versions the variant and retains unchanged bases. Do not manually clone entities for versioning. Use the current plan's ids throughout that execution; refresh after commit.
 
-Generation tools return resource references. An asset id names an Asset entity ({system:'memota',key:assetId}); every entity made from it links to that Asset with from-asset(entity,asset) and copies no locator of its own. An asset id is never an entity id, baseEntityId or relation endpoint. Physical resources are host infrastructure. The sandbox has no direct resource lookup/CRUD by asset id. rgetAssetFromEntity takes only an existing business entity id and returns {assetId,content} for its attached resource. For output_caption, create a Caption, link it with from-asset to the Asset for that assetId, then await rgetAssetFromEntity(captionId). The host initializes the complete AudioScript and one Caption per resource segment in the same causal plan when selection is omitted. The requested Caption represents the first segment; additional Caption entities share that same script and external reference. After awaiting, discover ALL resource Captions with entities.list filtered by entity_kind and their from-asset Asset, inspect each singular selection/durationMs, and place each in its own Clip/SequenceMarker. Discover them by following from-asset from the Asset. An explicit selection initializes only that selected Caption. Never place the first Caption over the whole transcript; Without explicit bases, the host creates an independent AudioScript for that resource. With bases, it resolves their unique AudioScript text owner and preserves other nonconflicting bases. It never routes text through the panel selection. Read the editable fields with entities.get afterwards. Repeated reads preserve edited text and return the original immutable resource content. Unawaited initialization is completed before validation; failure prevents publication. Resource-free Caption composition from AudioScript is also valid.
+Generation tools return resource references. An asset id names stored bytes. Say which bytes an entity is made from by passing asset:{system,key} to entities.create; the host mints the Asset row and the from-asset Relation for you. Asset rows and from-asset are invisible to scripts and cannot be created, linked or unlinked by them, and no entity copies a locator of its own. An asset id is never an entity id, baseEntityId or relation endpoint. Physical resources are host infrastructure. The sandbox has no direct resource lookup/CRUD by asset id. rgetAssetFromEntity takes only an existing business entity id and returns {assetId,content} for its attached resource. For output_caption, create a Caption with asset:{system:'memota',key:assetId}, then await rgetAssetFromEntity(captionId). The host initializes the complete AudioScript and one Caption per resource segment in the same causal plan when selection is omitted. The requested Caption represents the first segment; additional Caption entities share that same script and the same Asset. After awaiting, discover ALL resource Captions with entities.list filtered by entity_kind, inspect each singular selection/durationMs, and place each in its own Clip/SequenceMarker.  An explicit selection initializes only that selected Caption. Never place the first Caption over the whole transcript; Without explicit bases, the host creates an independent AudioScript for that resource. With bases, it resolves their unique AudioScript text owner and preserves other nonconflicting bases. It never routes text through the panel selection. Read the editable fields with entities.get afterwards. Repeated reads preserve edited text and return the original immutable resource content. Unawaited initialization is completed before validation; failure prevents publication. Resource-free Caption composition from AudioScript is also valid.
 
 Project initialization creates one current Timeline, the four standard Tracks and one attached AudioScript with segments:[]. A project may contain multiple independent complete AudioScripts (for example a generated script and an uploaded video transcript). The project AudioScript attachment selects only the panel view; it is not a singleton or membership constraint. Locate scripts with entities.list and choose the appropriate source. AudioScript owns independent multi-segment text; each can have multiple Caption variants. Caption and PhoneticScript compose it through baseEntityIds. Caption locates its text as AudioScript plus index: it owns exactly one selection object ({segmentId,textRange?}), never an array or the legacy selections field. segmentId is that segment's stable identity rather than its ordinal, so a concurrent insert or re-segmentation cannot slide a Caption onto other text. It selects one script segment or a contiguous substring, and owns only that selection's intrinsic timing and style; selection textRange is a half-open code-point range and can split display text without rewriting the script. PhoneticScript owns pronunciation/prosody; the voiceover is an Audio rendered from it and related by phonetic-script-render(audio,phoneticScript). Voice is only a timbre identity ({voice:{system:'voice-library',key}}) and is never playable; link the rendered Audio to it with voice-timbre(audio,voice). Speech and caption occupy separate Clips. Caption carries Sequence: it owns its display timing and can be Clip content directly. Subtitles normally accompany sound; use source media or render a voiceover Audio from PhoneticScript when the request requires narration. Do not fabricate a sound resource.
 
-For Speech resources, create an Audio and link it with from-asset to the Asset {system:'memota-speech',key:speechId}, then await rgetAssetFromEntity(audioId) before linking its placement. The host supplies the factual durationMs and assembles physical storage facts internally; the voice-library identity stays on its own Voice entity. Read the visible fields through entities.get; never invent them or use a Speech ID as a Memota media ID. A TTS voiceover still requires its real PhoneticScript relation; resource loading does not invent script content.
+For Speech resources, create an Audio with asset:{system:'memota-speech',key:speechId}, then await rgetAssetFromEntity(audioId) before linking its placement. The host supplies the factual durationMs and assembles physical storage facts internally; the voice-library identity stays on its own Voice entity. Read the visible fields through entities.get; never invent them or use a Speech ID as a Memota media ID. A TTS voiceover still requires its real PhoneticScript relation; resource loading does not invent script content.
 
-Direct AudioScript creation saves its segments as a resource before publication. Its assembled segments remain readable and editable; committed text changes preserve native Loro operations and save a new immutable resource, automatically advancing the external reference. AudioScripts initialized through Caption resources keep inline segments without an additional script resource. Do not manage these resources yourself. AudioScript has no intrinsic time and cannot be Clip content. ASR input Audio/Video associates via audio-script-source(script,source). Its external annotation SequenceMarker associates via audio-script-marker(script,marker) and receives assigned segmentRanges, not references to another marker. Caption intrinsic timing and its Clip's display SequenceMarker are distinct. Move/stretch display by editing only the placement marker.
+Direct AudioScript creation saves its segments as a resource before publication. Its assembled segments remain readable and editable; committed text changes preserve native Loro operations and save a new immutable resource, automatically advancing which Asset the script is made from. AudioScripts initialized through Caption resources keep inline segments without an additional script resource. Do not manage these resources yourself. AudioScript has no intrinsic time and cannot be Clip content. ASR input Audio/Video associates via audio-script-source(script,source). Its external annotation SequenceMarker associates via audio-script-marker(script,marker) and receives assigned segmentRanges, not references to another marker. Caption intrinsic timing and its Clip's display SequenceMarker are distinct. Move/stretch display by editing only the placement marker.
 
 To place content, create a Clip and a SequenceMarker, then link track-clip(track,clip), clip-marker(clip,marker) and marker-content(marker,content). Existing track membership uses timeline-track(timeline,track). The editor has one track of each role: video_clip for Image/Video, speech for the voiceover Audio, caption for Caption, bgm for Audio. Content states only its own durationMs in whole milliseconds, never a position: where it is taken from is Marker.sourceRange and where it lands is Marker.targetRange. A still Image states durationMs:null and each use decides how long it runs; an AXVideo stores none because its Timeline decides it. Inspect factual media durations; never invent one. Each placement is exactly one of Clip.order (sequential), Marker.targetRange (absolute) or clip-anchor(childClip,hostClip) plus Marker.anchorOffset. Marker.sourceRange selects source, duration describes playback/display. Whole milliseconds are required by this editor projection. Clip.volume is decibels (-60..20, 0 original). Linear timeRemapping is {kind:'linear',rate:2,mode:'constant'}, with duration matching the rounded source span/rate. BGM can use durationPolicy:'timeline'. Nonlinear speed and multiple overlay tracks are unsupported. Caption visibility is the caption Track's hidden field. Caption style is its style map. Handle structural links explicitly when moving/deleting; there is no implicit cascade.
 
@@ -1639,7 +1657,7 @@ function createMedeoTool(options) {
 				document,
 				baseVersion,
 				entityState,
-				loadEntityAsset: options.loadEntityAsset ? (entity) => options.loadEntityAsset(input.doc_id, entity) : void 0,
+				loadEntityAsset: options.loadEntityAsset ? (entity, asset) => options.loadEntityAsset(input.doc_id, entity, asset) : void 0,
 				writeEntityAsset: options.writeEntityAsset ? (entity, content) => options.writeEntityAsset(input.doc_id, entity, content) : void 0,
 				script: input.script,
 				...input.inputs !== void 0 ? { inputs: input.inputs } : {},