@mengine/medeo-tool 2.0.1-alpha.6 → 2.0.1-alpha.8

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { c as isMediaAssetVariantKind, i as businessState, o as createEntityId, s as createRelationId, t as EntitySandbox } from "./entity-sandbox-DSFbfybl.mjs";
-import { LoroEntityDocument, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, base64ToBytes, bytesToBase64, compileEntityRows, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, replayJournal, solveVideoDocument, speedOf, toVideoDocument } from "@mengine/medeo-client";
+import { c as isMediaAssetVariantKind, i as businessState, o as createEntityId, s as createRelationId, t as EntitySandbox } from "./entity-sandbox-CzaUmSsS.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";
 //#region src/document/compact-projection.ts
@@ -79,7 +79,7 @@ function renderCompactProjection(document, options) {
 			rows.push(`${tag} ${partId} ${lane} [${abs},${abs + dur}) ${attrs}`);
 		}
 	}
-	return [`# draft=${document.meta.draft_id ?? ""} v=${document.meta.version ?? 0} duration=${solved.durationMs} parts=${totalParts} shown=${rows.length}`, ...rows].join("\n");
+	return [`# draft=${options?.docId ?? ""} v=${options?.revision ?? 0} duration=${solved.durationMs} parts=${totalParts} shown=${rows.length}`, ...rows].join("\n");
 }
 //#endregion
 //#region src/sandbox/preview.ts
@@ -132,8 +132,12 @@ function collectFromValue(value, ids) {
 * Render a ChangePlan preview: header + rows for journal-affected parts only.
 * Empty journal → empty `onlyPartIds` (header alone), matching the T2 contract.
 */
-function renderPreview(document, journal) {
-	return renderCompactProjection(document, { onlyPartIds: journal.length === 0 ? /* @__PURE__ */ new Set() : collectAffectedPartIds(journal) });
+function renderPreview(document, journal, identity) {
+	const onlyPartIds = journal.length === 0 ? /* @__PURE__ */ new Set() : collectAffectedPartIds(journal);
+	return renderCompactProjection(document, {
+		...identity,
+		onlyPartIds
+	});
 }
 //#endregion
 //#region src/sandbox/node-host.ts
@@ -165,6 +169,7 @@ function runEditScript(options) {
 		let timer;
 		const worker = new Worker(workerEntryUrl, {
 			workerData: {
+				docId: options.docId,
 				document: options.document,
 				script: options.script,
 				inputs: options.inputs,
@@ -275,7 +280,7 @@ function runEditScript(options) {
 					ok: true,
 					plan: {
 						plan_kind: message.planKind,
-						doc_id: options.document.meta.draft_id ?? "",
+						doc_id: options.docId,
 						base_version: options.baseVersion,
 						ops: ops.slice(),
 						...message.loroUpdate ? { loro_update: message.loroUpdate } : {},
@@ -437,6 +442,7 @@ const KNOWN_RELATION_KINDS = [
 	"caption-alignment",
 	"clip-anchor",
 	"phonetic-script-render",
+	"voice-timbre",
 	"audio-script-source",
 	"audio-script-marker"
 ];
@@ -816,8 +822,10 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  };",
 	"  clip: JsonObject;",
 	"  video: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  /** Every playable sound, including video original audio and synthesized voiceovers. */",
 	"  audio: BoundedNativeSequencePayload & MediaAssetPayload;",
-	"  voice: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  /** A timbre identity, never playable content; the rendered take is an `audio` entity. */",
+	"  voice: VoiceIdentityPayload;",
 	"  image: UnboundedConstantSequencePayload & MediaAssetPayload;",
 	"  'sequence-marker': JsonObject & {",
 	"    sourceRange: {",
@@ -945,6 +953,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'caption-alignment'",
 	"  | 'clip-anchor'",
 	"  | 'phonetic-script-render'",
+	"  | 'voice-timbre'",
 	"  | 'audio-script-source'",
 	"  | 'audio-script-marker';",
 	"interface LinkRelationBase {",
@@ -985,10 +994,17 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  text: string;",
 	"  language?: string;",
 	"};",
-	"/** Stored own fields; a variant may obtain required content fields from its declared bases. */",
+	"/**",
+	" * Stored own fields; a variant may obtain required content fields from its",
+	" * declared bases.",
+	" *",
+	" * Caption and Audio may also be declared resource-only: the ASR transcript and",
+	" * the synthesized voiceover are attached by the host, which then fills in the",
+	" * remaining factual fields.",
+	" */",
 	"export type StoredEntityPayload<K extends KnownEntityKind> =",
 	"  | EntityPayloadByKind[K]",
-	"  | (K extends 'caption' | 'voice' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never)",
+	"  | (K extends 'caption' | 'audio' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never)",
 	"  | (JsonObject &",
 	"      Partial<EntityPayloadByKind[K]> & {",
 	"        baseEntityIds: string[];",
@@ -1009,6 +1025,14 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  entity_id: string;",
 	"  payload: JsonObject;",
 	"}",
+	"/** The voice-library timbre a synthesized Audio was rendered with. */",
+	"export type VoiceIdentityPayload = JsonObject & {",
+	"  voice: {",
+	"    system: 'voice-library';",
+	"    key: string;",
+	"    name?: string;",
+	"  };",
+	"};",
 	"export declare const entities: BusinessEntityFacade;",
 	"export declare const relations: BusinessRelationFacade;",
 	"/** Resolve this Entity's attached resource through the host; await before using an uninitialized Caption or Voice. */",
@@ -1049,13 +1073,13 @@ Variants directly hold baseEntityIds. Assembly validates every base before apply
 
 Generation tools return resource references. An asset id may be passed in an entity's external:{system:'memota',key:assetId}; it 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 payload:{external:{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 external reference. After awaiting, discover ALL resource Captions with entities.list filtered by entity_kind and payload.external.key, inspect each singular selection/extent, 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 owns exactly one selection object ({segmentId,textRange?}), never an array or the legacy selections field. It selects one script segment or a contiguous substring, and owns only that selection's intrinsic timing and style; segmentId is a stable script-local identity, not an entity reference or transient array index; selection textRange is a half-open code-point range and can split display text without rewriting the script. PhoneticScript owns pronunciation/prosody; Voice is generated from it and related by phonetic-script-render(voice,phoneticScript). Speech and caption occupy separate Clips. Subtitles normally accompany sound; use source media or generate Voice from PhoneticScript when the request requires narration. Do not fabricate a sound resource.
+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 owns exactly one selection object ({segmentId,textRange?}), never an array or the legacy selections field. It selects one script segment or a contiguous substring, and owns only that selection's intrinsic timing and style; segmentId is a stable script-local identity, not an entity reference or transient array index; 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 a Voice with external:{system:'memota-speech',key:speechId}, then await rgetAssetFromEntity(voiceId) before linking its placement. The host supplies full extent and optional voice-library identity, and assembles physical storage facts internally. Read the visible fields through entities.get; never invent them or use a Speech ID as a Memota media ID. TTS Voice still requires its real PhoneticScript relation; resource loading does not invent script content.
+For Speech resources, create an Audio with external:{system:'memota-speech',key:speechId}, then await rgetAssetFromEntity(audioId) before linking its placement. The host supplies full extent 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/Voice 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 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.
 
-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 Voice, caption for Caption, bgm for Audio. Inspect factual media extents; never invent duration. 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). Image is unbounded/constant. 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.
+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. Inspect factual media extents; never invent duration. 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). Image is unbounded/constant. 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.
 
 checkpoint returns an opaque token valid only in this execution. rollbackTo restores that point and invalidates later checkpoints. Returned read snapshots and inputs are not writable document authorities. Use only the declarations below.
 `.trim();
@@ -1218,7 +1242,7 @@ async function commitPlan(doc, plan, options) {
 * integrity throws are not wrapped.
 */
 async function commitPlanPreflight(doc, plan) {
-	const scratch = createPlainMemoryAdapter(doc.snapshot());
+	const scratch = createPlainMemoryAdapter(doc.snapshot(), { readOnly: doc.isEntityDocument() });
 	for (let index = 0; index < plan.ops.length; index++) {
 		const entry = plan.ops[index];
 		if (entry == null) continue;
@@ -1410,13 +1434,13 @@ function createMedeoTool(options) {
 		const existing = documents.get(docId);
 		if (existing != null) return await existing;
 		const created = (async () => {
-			return await getOrCreateDocument(new MengineHttpClient({
+			return await openDocument(new MengineHttpClient({
 				docId,
 				httpOrigin: requiredContext(options.httpOrigin, docId, "httpOrigin"),
 				...options.authToken !== void 0 ? { authToken: () => optionalContext(options.authToken, docId) } : {},
 				...options.userId !== void 0 ? { userId: () => optionalContext(options.userId, docId) } : {},
 				...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {}
-			}), docId, optionalContext(options.peerId, docId));
+			}), optionalContext(options.peerId, docId));
 		})();
 		documents.set(docId, created);
 		try {
@@ -1456,36 +1480,14 @@ function createMedeoTool(options) {
 			if (documentTails.get(docId) === tail) documentTails.delete(docId);
 		}
 	}
-	async function getOrCreateDocument(client, docId, peerId) {
-		try {
-			return await ManualSyncDoc.open({
-				client,
-				...peerId !== void 0 ? { peerId } : {}
-			});
-		} catch (error) {
-			if (!(error instanceof MengineHttpRequestError) || error.status !== 404) throw error;
-			if (options.loadInitialDraft === void 0) throw error;
-		}
-		const document = toVideoDocument(await options.loadInitialDraft(docId));
-		if (Object.keys(document.part_library ?? {}).length > 0) throw new Error("Legacy content cannot bootstrap a Loro entity project");
-		const seed = createMirrorVideoDocument(document, {
-			...peerId !== void 0 ? { peerId } : {},
-			origin: "mengine.medeo_tool.bootstrap"
-		});
-		const foundation = ensureEditorFoundation({
-			entities: [],
-			relations: []
-		});
-		const entities = LoroEntityDocument.create(foundation.rows, {
-			timelineEntityId: foundation.timelineEntityId,
-			audioScriptEntityId: foundation.audioScriptEntityId
-		});
-		seed.import(entities.doc.export({ mode: "snapshot" }));
-		try {
-			await client.bootstrapSnapshot(seed.export({ mode: "snapshot" }));
-		} catch (error) {
-			if (!(error instanceof MengineHttpRequestError) || error.status !== 400) throw error;
-		}
+	/**
+	* Open an existing Mengine document. Creation belongs to Director, which
+	* initializes every project's document (`POST .../initialize`) before any
+	* agent edit; Mengine's `bootstrap` is the internal Legacy-migration route
+	* and is deliberately absent from the client SDK. A 404 here is a real
+	* missing document, not something this tool may paper over.
+	*/
+	async function openDocument(client, peerId) {
 		return await ManualSyncDoc.open({
 			client,
 			...peerId !== void 0 ? { peerId } : {}
@@ -1657,6 +1659,7 @@ function createMedeoTool(options) {
 			const document = doc.snapshot();
 			const baseVersion = encodeDocVersionMark(doc.versionMark());
 			const result = await runEditScript({
+				docId: input.doc_id,
 				document,
 				baseVersion,
 				entityState,
@@ -1797,13 +1800,15 @@ async function materializeResources(options, resources) {
 	const client = new EntityHttpClient(options);
 	const state = await client.fetchState();
 	let resourceKey = "";
+	let mintOrdinal = 0;
 	const sandbox = new EntitySandbox({
 		state,
-		idFactory: (prefix) => stableId(prefix, options.docId, resourceKey)
+		idFactory: (prefix) => stableId(prefix, options.docId, resourceKey, String(mintOrdinal++))
 	});
 	const ids = [];
 	for (const resource of resources) {
 		resourceKey = `${resource.kind}:${resource.assetId}`;
+		mintOrdinal = 0;
 		if (resource.kind !== "caption") {
 			ids.push(sandbox.entities.ensureMedia(resource).contentEntityId);
 			continue;