@mengine/medeo-tool 1.4.1-alpha.5 → 2.0.1-alpha.10

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-DlmUSouB.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-Cf3AiSe7.mjs";
 import { JournalEntry, ManualSyncDoc, MediaAssetFact, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft } from "@mengine/medeo-client";
 
 //#region src/document/compact-projection.d.ts
@@ -11,6 +11,14 @@ import { JournalEntry, ManualSyncDoc, MediaAssetFact, PartIdFactory, SemanticOpN
  * `fromVideoDocument`.
  */
 interface CompactProjectionOptions {
+  /**
+   * Document identity for the header. Stated by the caller: the document
+   * content no longer carries its own id or revision (business metadata left
+   * the CRDT), and the model needs to know which draft this summary describes.
+   * Omitted values keep the header's fixed shape with the historical blanks.
+   */
+  docId?: string;
+  revision?: number;
   /** Only render these parts (header still reports the full timeline total). Default = all. */
   onlyPartIds?: ReadonlySet<string>;
   /** Caption text preview truncation length. Default 24. */
@@ -30,7 +38,10 @@ declare function collectAffectedPartIds(journal: readonly JournalEntry[]): Set<s
  * Render a ChangePlan preview: header + rows for journal-affected parts only.
  * Empty journal → empty `onlyPartIds` (header alone), matching the T2 contract.
  */
-declare function renderPreview(document: VideoDocument, journal: readonly JournalEntry[]): string;
+declare function renderPreview(document: VideoDocument, journal: readonly JournalEntry[], identity?: {
+  docId?: string;
+  revision?: number;
+}): string;
 //#endregion
 //#region src/entity/entity-asset.d.ts
 /** Immutable resource content resolved by the host for a document Entity. */
@@ -40,6 +51,8 @@ interface EntityAssetContent {
 }
 /** Host-only I/O. The sandbox supplies an Entity, never an arbitrary Asset query. */
 type EntityAssetLoader = (docId: string, entity: 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
 //#region src/entity/entity-sandbox.d.ts
 type DomainIdFactory = (prefix: 'entity' | 'relation') => string;
@@ -61,6 +74,12 @@ interface ChangePlan {
   logs: string[];
 }
 interface EditSandboxSessionOptions {
+  /**
+   * Document this session edits. Stated by the host: the document content no
+   * longer carries its own identity (business metadata left the CRDT), and a
+   * plan must name the document it will be committed against.
+   */
+  docId?: string;
   idFactory?: PartIdFactory;
   onEntry?: (entry: JournalEntry) => void;
   onLog?: (line: string) => void;
@@ -87,7 +106,10 @@ interface ConsoleShim {
  * injects loaders that break worker boot.
  */
 interface RunEditScriptOptions {
+  /** Document the plan will be committed against; stated by the host. */
+  docId: string;
   loadEntityAsset?: (entity: SandboxEntity) => Promise<EntityAssetContent>;
+  writeEntityAsset?: (entity: SandboxEntity, content: EntityAssetContent['content']) => Promise<EntityAssetContent>;
   document: VideoDocument;
   baseVersion: string;
   script: string;
@@ -376,13 +398,6 @@ interface CreateMedeoToolOptions {
   userId?: ContextualValue<string>;
   /** Stable agent peer id. Supply a host-scoped value so audit provenance is durable. */
   peerId?: ContextualValue<string>;
-  /**
-   * Load the authoritative legacy draft used to create a missing Mengine
-   * document. The tool owns the get-or-create flow: it first probes Mengine,
-   * converts this draft into a VideoDocument only on a 404, bootstraps the
-   * snapshot, and tolerates a concurrent creator winning the race.
-   */
-  loadInitialDraft?: (docId: string) => Promise<VideoDraft>;
   /**
    * Resolve factual generation lineage by external asset id after a confirmed
    * entity commit. Return every known generation record involving the given
@@ -395,6 +410,8 @@ interface CreateMedeoToolOptions {
   /** Assemble optional Caption artifacts by immutable entity ID; never exposed to scripts. */
   loadCaptionAssets?: CaptionAssetsLoader;
   loadEntityAsset?: EntityAssetLoader;
+  /** Program-side persistence for immutable AudioScript resources. */
+  writeEntityAsset?: EntityAssetWriter;
   fetchImpl?: typeof fetch;
   /** @deprecated ManualSyncDoc has no SSE or reconnect loop. */
   sseReconnectDelayMs?: number;
@@ -567,5 +584,5 @@ declare function materializeResources(options: EntityHttpClientOptions & {
   loadGenerationFacts?: GenerationFactsLoader;
 }, resources: readonly GeneratedResource[]): Promise<readonly string[]>;
 //#endregion
-export { type AssetGenerationFact, type AuthorableRelationKind, type BusinessEntityFacade, type BusinessRelationFacade, 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 EditSandboxSessionOptions, type EditScriptResult, type EntityAssetContent, type EntityAssetLoader, type EntityCommand, type EntityCommitResult, type EntityPlanState, type EntitySandboxCheckpoint, type EntityStoreSnapshot, type EntityUpdateInput, 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 RelationUpdateInput, type ResourceEntityKind, type RunEditScriptOptions, type SandboxEntity, type SandboxRelation, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, materializeResources, renderCompactProjection, renderPreview, runEditScript };
+export { type AssetGenerationFact, type AuthorableRelationKind, type BusinessEntityFacade, type BusinessRelationFacade, 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 EditSandboxSessionOptions, type EditScriptResult, type EntityAssetContent, type EntityAssetLoader, type EntityAssetWriter, type EntityCommand, type EntityCommitResult, type EntityPlanState, type EntitySandboxCheckpoint, type EntityStoreSnapshot, type EntityUpdateInput, 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 RelationUpdateInput, type ResourceEntityKind, type RunEditScriptOptions, type SandboxEntity, type SandboxRelation, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, materializeResources, renderCompactProjection, renderPreview, runEditScript };
 //# sourceMappingURL=index.d.mts.map

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-TaUVT3on.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 { a as createEntityId, i as businessState, o as createRelationId, s as isMediaAssetVariantKind, t as EntitySandbox } from "./entity-sandbox-BTR2cRl1.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,
@@ -214,11 +219,14 @@ function runEditScript(options) {
 				armTimeout();
 				return;
 			}
-			if (message.t === "entity-asset") {
+			if (message.t === "entity-asset" || message.t === "write-entity-asset") {
 				(async () => {
 					try {
-						if (!options.loadEntityAsset) throw new Error("Entity Asset loader is unavailable");
-						const result = await options.loadEntityAsset(message.entity);
+						const result = message.t === "write-entity-asset" ? await (options.writeEntityAsset ?? (() => {
+							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);
 						if (!settled) worker.postMessage({
 							t: "entity-asset-result",
 							requestId: message.requestId,
@@ -272,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 } : {},
@@ -338,7 +346,7 @@ function runEditScript(options) {
 async function assembleCaptionAssets(input) {
 	try {
 		const state = await input.client.fetchState();
-		const candidates = state.entities.filter((entity) => entity.entity_kind === "caption" && !state.relations.some((relation) => relation.relation_kind === "physical-asset" && (relation.endpoint_0_entity_id === entity.entity_id || relation.endpoint_1_entity_id === entity.entity_id)));
+		const candidates = state.entities.filter((entity) => entity.entity_kind === "caption" && !state.relations.some((relation) => relation.relation_kind === "from-asset" && (relation.endpoint_0_entity_id === entity.entity_id || relation.endpoint_1_entity_id === entity.entity_id)));
 		if (!candidates.length) return { status: "current" };
 		const ids = new Set(candidates.map((entity) => entity.entity_id));
 		const facts = await input.loadAssets(input.docId, [...ids]);
@@ -353,11 +361,8 @@ async function assembleCaptionAssets(input) {
 				continue;
 			}
 			bound.set(fact.captionEntityId, fact.assetId);
-			const matches = entities.filter((entity) => {
-				const external = entity.payload.external;
-				return external !== null && typeof external === "object" && !Array.isArray(external) && external.system === "memota" && external.key === fact.assetId;
-			});
-			if (matches.length > 1 || matches[0] && matches[0].entity_kind !== "asset") throw new Error(`Conflicting resource identity for Caption Asset ${fact.assetId}`);
+			const matches = entities.filter((entity) => entity.entity_kind === "asset" && entity.payload.system === "memota" && entity.payload.key === fact.assetId);
+			if (matches.length > 1) throw new Error(`Conflicting resource identity for Caption Asset ${fact.assetId}`);
 			let asset = matches[0];
 			if (asset && asset.payload.storageKey !== fact.storageKey) throw new Error(`Conflicting storage key for Caption Asset ${fact.assetId}`);
 			if (!asset) {
@@ -365,10 +370,8 @@ async function assembleCaptionAssets(input) {
 					entity_id: stableId$1("asset", fact.assetId),
 					entity_kind: "asset",
 					payload: {
-						external: {
-							system: "memota",
-							key: fact.assetId
-						},
+						system: "memota",
+						key: fact.assetId,
 						storageKey: fact.storageKey
 					}
 				};
@@ -377,7 +380,7 @@ async function assembleCaptionAssets(input) {
 			}
 			relations.push({
 				relation_id: stableId$1("relation", fact.captionEntityId, asset.entity_id),
-				relation_kind: "physical-asset",
+				relation_kind: "from-asset",
 				endpoint_0_entity_id: fact.captionEntityId,
 				endpoint_1_entity_id: asset.entity_id,
 				metadata: {},
@@ -429,11 +432,12 @@ const KNOWN_RELATION_KINDS = [
 	"marker-content",
 	"axvideo-marker",
 	"marker-timeline",
-	"physical-asset",
+	"from-asset",
 	"generated",
 	"caption-alignment",
 	"clip-anchor",
 	"phonetic-script-render",
+	"voice-timbre",
 	"audio-script-source",
 	"audio-script-marker"
 ];
@@ -738,25 +742,6 @@ function isRecord$1(value) {
 /** @generated by gen:sandbox-dts. DO NOT EDIT. */
 const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"/** @generated by gen:sandbox-dts. Entity-native editor contract; DO NOT EDIT. */",
-	"export interface BoundedDerivedSequencePayload extends JsonObject {",
-	"  extent: {",
-	"    kind: 'bounded';",
-	"    start: number;",
-	"    end: number;",
-	"  };",
-	"  sampling: 'derived';",
-	"  coordinateSpace: JsonValue;",
-	"}",
-	"export interface BoundedNativeSequencePayload extends JsonObject {",
-	"  /** Factual coordinates from recalled media metadata; never invent an end/duration. */",
-	"  extent: {",
-	"    kind: 'bounded';",
-	"    start: number;",
-	"    end: number;",
-	"  };",
-	"  sampling: 'native';",
-	"  coordinateSpace: JsonValue;",
-	"}",
 	"/** Business editing surface. Reads are assembled snapshots; writes preserve native operation intent. */",
 	"export interface BusinessEntityFacade {",
 	"  list(): SandboxEntity[];",
@@ -805,17 +790,20 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  content: JsonValue;",
 	"}",
 	"export interface EntityPayloadByKind {",
-	"  axvideo: BoundedDerivedSequencePayload;",
+	"  /** Its Timeline decides how long it runs, so it stores no length. */",
+	"  axvideo: JsonObject;",
 	"  timeline: JsonObject;",
 	"  track: JsonObject & {",
 	"    hidden?: boolean;",
 	"    role?: string;",
 	"  };",
 	"  clip: JsonObject;",
-	"  video: BoundedNativeSequencePayload & MediaAssetPayload;",
-	"  audio: BoundedNativeSequencePayload & MediaAssetPayload;",
-	"  voice: BoundedNativeSequencePayload & MediaAssetPayload;",
-	"  image: UnboundedConstantSequencePayload & MediaAssetPayload;",
+	"  video: OwnDurationPayload;",
+	"  /** Every playable sound, including video original audio and synthesized voiceovers. */",
+	"  audio: OwnDurationPayload;",
+	"  /** A timbre identity, never playable content; the rendered take is an `audio` entity. */",
+	"  voice: VoiceIdentityPayload;",
+	"  image: NoDurationPayload;",
 	"  'sequence-marker': JsonObject & {",
 	"    sourceRange: {",
 	"      start: number;",
@@ -852,7 +840,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    phonemeScript?: string;",
 	"    prosody?: JsonObject;",
 	"  };",
-	"  caption: BoundedNativeSequencePayload & {",
+	"  caption: OwnDurationPayload & {",
 	"    baseEntityIds: string[];",
 	"    selection: CaptionTextSelection;",
 	"    style?: JsonObject;",
@@ -942,6 +930,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'caption-alignment'",
 	"  | 'clip-anchor'",
 	"  | 'phonetic-script-render'",
+	"  | 'voice-timbre'",
 	"  | 'audio-script-source'",
 	"  | 'audio-script-marker';",
 	"interface LinkRelationBase {",
@@ -954,12 +943,18 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  relation_kind: KnownRelationKind;",
 	"  metadata?: JsonObject;",
 	"}",
-	"export type MediaAssetPayload = JsonObject & {",
-	"  external: {",
-	"    system: 'memota' | 'memota-speech';",
-	"    key: string;",
-	"  };",
-	"};",
+	"/** A still frame runs for as long as its use asks, so it states no length. */",
+	"export interface NoDurationPayload extends JsonObject {",
+	"  durationMs: null;",
+	"}",
+	"/**",
+	" * Content states how long it runs and nothing else: where it is taken from and",
+	" * where it lands both belong to its Sequence Marker.",
+	" */",
+	"export interface OwnDurationPayload extends JsonObject {",
+	"  /** Factual whole milliseconds from recalled media metadata; never invented. */",
+	"  durationMs: number;",
+	"}",
 	"export interface RelationUpdateInput {",
 	"  relation_id: string;",
 	"  changes: FieldChange[];",
@@ -982,22 +977,22 @@ 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' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never)",
+	"  // Resource-only: the host fills the factual fields after reading the Asset.",
+	"  | (K extends 'caption' | 'audio' ? Record<string, never> : never)",
 	"  | (JsonObject &",
 	"      Partial<EntityPayloadByKind[K]> & {",
 	"        baseEntityIds: string[];",
 	"      });",
-	"export interface UnboundedConstantSequencePayload extends JsonObject {",
-	"  extent: {",
-	"    kind: 'unbounded';",
-	"    start: number;",
-	"  };",
-	"  sampling: 'constant';",
-	"  coordinateSpace: JsonValue;",
-	"}",
 	"export interface UnlinkRelationInput {",
 	"  relation_id: string;",
 	"}",
@@ -1006,9 +1001,17 @@ 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. */",
+	"/** Resolve this Entity's attached resource through the host; await before using an uninitialized Caption or Voice. */",
 	"export declare function rgetAssetFromEntity(entityId: string): Promise<EntityAssetContent>;",
 	"export declare function checkpoint(): EntitySandboxCheckpoint;",
 	"export declare function rollbackTo(cp: EntitySandboxCheckpoint): void;",
@@ -1038,19 +1041,21 @@ The host supplies the current document. Do not invent or request a document id.
 
 Entity reads return assembled snapshots. Mutating returned objects has no persistence effect. Create declares own fields. Update requires a nonempty changes array and atomically applies its ordered operations to assembled fields, routing each to its declaring owner. DeclareFields explicitly establishes own fields or an override; it is not the normal way to edit inherited content. Deletion requires explicitly handling incident relations, variant references and protected project attachments; it never deletes external resources or cascades business entities.
 
-FieldChange paths start at payload for an entity, and at metadata or trace for a relation. Use strings for fields and {elementId:'...'} for list members, never numeric indices. Segment identity is segmentId; reference identity is the referenced id. set writes scalars or schema-declared atomic values, including complete sourceRange, targetRange, extent, duration, timeRemapping, selection, textRange and external. It cannot replace collaborative text, lists or maps. Edit text with text.splice (Unicode code-point index and deleteCount), and segments/segmentRanges with list.insert, list.move or list.remove. beforeElementId:null means append; moving before itself, duplicate identity or an absent anchor is an error. Unset removes optional fields only. Map fields are edited through leaf paths; initialize a new own map via declareFields. baseEntityIds is unordered composition membership: insert/remove are supported, moving bases cannot resolve field conflicts. Independent fields and list-item text edits retain native Loro identities.
+FieldChange paths start at payload for an entity, and at metadata or trace for a relation. Use strings for fields and {elementId:'...'} for list members, never numeric indices. Segment identity is segmentId; reference identity is the referenced id. set writes scalars or schema-declared atomic values, including complete sourceRange, targetRange, duration, timeRemapping, selection, textRange and external. It cannot replace collaborative text, lists or maps. Edit text with text.splice (Unicode code-point index and deleteCount), and segments/segmentRanges with list.insert, list.move or list.remove. beforeElementId:null means append; moving before itself, duplicate identity or an absent anchor is an error. Unset removes optional fields only. Map fields are edited through leaf paths; initialize a new own map via declareFields. baseEntityIds is unordered composition membership: insert/remove are supported, moving bases cannot resolve field conflicts. Independent fields and list-item text edits retain native Loro identities.
 
 Entities own data. Relations associate two existing entities; endpoint_0 and endpoint_1 retain their declared positions. Each relation kind defines direction and meaning; neither relation listing order nor endpoint storage order implies a global business order. Relations.update changes metadata/trace fields only; kind/endpoints require explicit unlink plus link with a new identity. Generated relations use generated(output,input). Ordinary associations do not implement composition.
 
 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 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.
+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.
+
+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.
 
-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.
+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.
 
-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. 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.
 
 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();
@@ -1213,7 +1218,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;
@@ -1405,13 +1410,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 {
@@ -1451,36 +1456,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 } : {}
@@ -1652,10 +1635,12 @@ function createMedeoTool(options) {
 			const document = doc.snapshot();
 			const baseVersion = encodeDocVersionMark(doc.versionMark());
 			const result = await runEditScript({
+				docId: input.doc_id,
 				document,
 				baseVersion,
 				entityState,
 				loadEntityAsset: options.loadEntityAsset ? (entity) => options.loadEntityAsset(input.doc_id, entity) : 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 } : {},
 				timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs ?? 3e4,
@@ -1791,20 +1776,24 @@ 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;
 		}
-		const existingCaptions = sandbox.entities.list().filter((row) => row.entity_kind === "caption" && row.payload.external?.key === resource.assetId);
+		const rows = sandbox.entities.list();
+		const assetRow = rows.find((row) => row.entity_kind === "asset" && row.payload.key === resource.assetId);
+		const existingCaptions = assetRow === void 0 ? [] : rows.filter((row) => row.entity_kind === "caption" && sandbox.entities.assetIdOf(row.entity_id) === assetRow.entity_id);
 		if (existingCaptions.length) {
-			if (existingCaptions.some((caption) => caption.payload.storageKey !== resource.storageKey)) throw new Error("Conflicting Caption resource identity");
+			if (assetRow?.payload.storageKey !== resource.storageKey) throw new Error("Conflicting Caption resource identity");
 			ids.push(...existingCaptions.map((caption) => caption.entity_id));
 			continue;
 		}
@@ -1825,6 +1814,11 @@ async function materializeResources(options, resources) {
 			entity_kind: "audio-script",
 			payload: { segments }
 		});
+		const captionAssetId = sandbox.entities.ensureAsset({
+			system: "memota",
+			key: resource.assetId,
+			storageKey: resource.storageKey
+		});
 		const ranges = resource.segments.map((segment, index) => ({
 			segmentId: segments[index].segmentId,
 			startMs: segment.startMs,
@@ -1837,22 +1831,16 @@ async function materializeResources(options, resources) {
 				entity_kind: "caption",
 				payload: {
 					baseEntityIds: [scriptId],
-					external: {
-						system: "memota",
-						key: resource.assetId
-					},
-					storageKey: resource.storageKey,
 					selection: { segmentId: range.segmentId },
 					segmentRanges: [range],
-					extent: {
-						kind: "bounded",
-						start: range.startMs,
-						end: range.endMs
-					},
-					sampling: "native",
-					coordinateSpace: "milliseconds"
+					durationMs: range.endMs - range.startMs
 				}
 			});
+			sandbox.relations.link({
+				relation_kind: "from-asset",
+				endpoint_0_entity_id: captionId,
+				endpoint_1_entity_id: captionAssetId
+			});
 			ids.push(captionId);
 		}
 		const markerId = sandbox.entities.create({