@mengine/medeo-tool 1.2.1-alpha.9 → 1.3.1-alpha.8

package/dist/{script-session-CHyIUBkO.mjs → script-session-C2uQHYt4.mjs}

@@ -1,4 +1,4 @@
-import { SchemaValidator, SemanticEditor, createEditSandbox, effectiveVideoClipDurationMs, fromVideoDocument, solveVideoDocument, speedOf } from "@mengine/medeo-client";
+import { SchemaValidator, SemanticEditor, assertCanonicalEditorResources, createEditSandbox, effectiveVideoClipDurationMs, ensureEditorFoundation, fromVideoDocument, importMediaAsset, readDocumentAudioScript, solveVideoDocument, speedOf } from "@mengine/medeo-client";
 //#region src/document/compact-projection.ts
 const DEFAULT_TEXT_PREVIEW_LENGTH = 24;
 /** Kind tag shown in the first column (`video_clip` → `clip`). */
@@ -149,7 +149,10 @@ function isSequenceFields(value) {
 	return "coordinateSpace" in value && value.coordinateSpace !== void 0;
 }
 function isKnownSequenceKind(kind) {
-	return kind === "video" || kind === "audio" || kind === "voice" || kind === "image" || kind === "caption" || kind === "axvideo";
+	return isMediaAssetVariantKind(kind) || kind === "caption" || kind === "axvideo";
+}
+function isMediaAssetVariantKind(kind) {
+	return kind === "video" || kind === "image" || kind === "audio" || kind === "voice";
 }
 function isKnownEntityKind(kind) {
 	return isKnownSequenceKind(kind) || isKnownNonSequenceKind(kind);
@@ -177,15 +180,281 @@ function createId(value, label) {
 	return value;
 }
 //#endregion
+//#region ../medeo-dsl/src/json-values.ts
+const nativeObjectConstructorSource = Function.prototype.toString.call(Object);
+function isJsonObject(value) {
+	return isJsonValue(value, /* @__PURE__ */ new Set()) && !Array.isArray(value) && value !== null;
+}
+function isJsonValue(value, ancestors) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value !== "object") return false;
+	if (!Array.isArray(value) && !isPlainObject(value)) return false;
+	if (ancestors.has(value)) return false;
+	ancestors.add(value);
+	const valid = Array.isArray(value) ? value.every((item) => isJsonValue(item, ancestors)) : Object.values(value).every((item) => isJsonValue(item, ancestors));
+	ancestors.delete(value);
+	return valid;
+}
+/** Recognize an ordinary object from any VM realm without admitting class instances. */
+function isPlainObject(value) {
+	try {
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype === null) return true;
+		if (Object.getPrototypeOf(prototype) !== null) return false;
+		const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
+		return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === nativeObjectConstructorSource;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region ../medeo-dsl/src/composition.ts
+/** Assembly fails explicitly when declared bases cannot provide valid, unambiguous content. */
+var ScriptCompositionError = class extends Error {
+	code;
+	entityId;
+	constructor(code, entityId, message) {
+		super(message);
+		this.code = code;
+		this.entityId = entityId;
+		this.name = "ScriptCompositionError";
+	}
+};
+/** Direct base IDs are structural fields, never ordinary Relation endpoints. */
+function variantBaseEntityIds(entity) {
+	if (!Object.hasOwn(entity.payload, "baseEntityIds")) return [];
+	const ids = entity.payload.baseEntityIds;
+	if (!Array.isArray(ids) || ids.length === 0 || !ids.every((id) => typeof id === "string" && id.trim() === id && id.length > 0) || new Set(ids).size !== ids.length) throw new ScriptCompositionError("invalid_bases", entity.entityId, `Entity "${entity.entityId}" requires non-empty, unique baseEntityIds`);
+	return ids.map(createEntityId);
+}
+/** Validate all base providers before applying explicit own fields; ordering cannot resolve ambiguity. */
+function assembleEntityContent(rows, entityId) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const row of rows.entities) {
+		if (byId.has(row.entityId)) throw new ScriptCompositionError("composition_ambiguous", row.entityId, `duplicate entity id "${row.entityId}"`);
+		byId.set(row.entityId, row);
+	}
+	const active = /* @__PURE__ */ new Set();
+	const cache = /* @__PURE__ */ new Map();
+	const visit = (id) => {
+		const cached = cache.get(id);
+		if (cached !== void 0) return cached;
+		if (active.has(id)) throw new ScriptCompositionError("composition_cycle", id, `Cyclic baseEntityIds at "${id}"`);
+		const row = byId.get(id);
+		if (row === void 0) throw new ScriptCompositionError("composition_dangling", id, `Missing base entity "${id}" in this document`);
+		if (!isJsonObject(row.payload) || Object.hasOwn(row.payload, "entityId") || Object.hasOwn(row.payload, "entityKind")) throw new ScriptCompositionError("invalid_bases", id, `Entity "${id}" requires JSON own fields without reserved identity fields`);
+		active.add(id);
+		const inherited = {};
+		const providers = /* @__PURE__ */ new Map();
+		for (const baseId of variantBaseEntityIds(row)) {
+			const base = visit(baseId);
+			for (const [field, value] of Object.entries(base.payload)) {
+				if (field === "baseEntityIds") continue;
+				const previous = providers.get(field);
+				if (previous !== void 0) throw new ScriptCompositionError("field_conflict", id, `Entity "${id}" field "${field}" conflicts between bases "${previous}" and "${baseId}"; own fields cannot resolve base ambiguity`);
+				providers.set(field, baseId);
+				Object.defineProperty(inherited, field, {
+					value,
+					enumerable: true,
+					configurable: true,
+					writable: true
+				});
+			}
+		}
+		const assembled = {
+			...row,
+			payload: JSON.parse(JSON.stringify({
+				...inherited,
+				...row.payload
+			}))
+		};
+		active.delete(id);
+		cache.set(id, assembled);
+		return assembled;
+	};
+	return visit(entityId);
+}
+/** Resolve a field's declaring entity after validating the entire composition. */
+function resolveEntityFieldOwner(rows, entityId, field) {
+	assembleEntityContent(rows, entityId);
+	const byId = new Map(rows.entities.map((row) => [row.entityId, row]));
+	const find = (id) => {
+		const row = byId.get(id);
+		if (Object.hasOwn(row.payload, field)) return id;
+		if (field === "baseEntityIds") return void 0;
+		for (const baseId of variantBaseEntityIds(row)) {
+			const owner = find(baseId);
+			if (owner !== void 0) return owner;
+		}
+	};
+	return find(entityId) ?? entityId;
+}
+/** Patch assembled fields without copying inherited fields into the variant's stored payload. */
+function updateEntityFields(rows, entityId, fields) {
+	assembleEntityContent(rows, entityId);
+	if (!isJsonObject(fields) || Object.hasOwn(fields, "entityId") || Object.hasOwn(fields, "entityKind")) throw new ScriptCompositionError("invalid_bases", entityId, "Field updates require JSON without reserved identity fields");
+	const updates = /* @__PURE__ */ new Map();
+	for (const [field, value] of Object.entries(fields)) {
+		const ownerId = resolveEntityFieldOwner(rows, entityId, field);
+		const owner = updates.get(ownerId) ?? rows.entities.find((row) => row.entityId === ownerId);
+		updates.set(ownerId, {
+			...owner,
+			payload: {
+				...owner.payload,
+				[field]: value
+			}
+		});
+	}
+	return [...updates.values()].map((row) => JSON.parse(JSON.stringify(row)));
+}
+/** Find the actual AudioScript text owner through direct variant bases. */
+function findComposedAudioScript(rows, variantEntityId, variantKind) {
+	const variant = requireEntityKind(rows, variantEntityId, variantKind);
+	assembleEntityContent(rows, variantEntityId);
+	const sources = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (row) => {
+		for (const id of variantBaseEntityIds(row)) {
+			if (seen.has(id)) continue;
+			seen.add(id);
+			const base = rows.entities.find((candidate) => candidate.entityId === id);
+			if (base.entityKind === "audio-script") sources.set(id, assembleEntityContent(rows, id));
+			else visit(base);
+		}
+	};
+	visit(variant);
+	if (sources.size !== 1) throw new ScriptCompositionError(sources.size === 0 ? "composition_missing" : "composition_ambiguous", variantEntityId, `${variantKind} "${variantEntityId}" baseEntityIds must resolve one AudioScript text owner, got ${sources.size}`);
+	return [...sources.values()][0];
+}
+function scriptSegments(script) {
+	const segments = script.payload.segments;
+	if (!Array.isArray(segments)) throw new ScriptCompositionError("composition_dangling", script.entityId, `AudioScript "${script.entityId}" requires segments`);
+	if (!segments.every(isScriptSegment) || new Set(segments.map((s) => s.segmentId)).size !== segments.length) throw new ScriptCompositionError("invalid_script", script.entityId, "AudioScript requires valid segments with unique local segmentId and text");
+	return segments;
+}
+function isScriptSegment(value) {
+	if (typeof value !== "object" || value == null || Array.isArray(value)) return false;
+	const segment = value;
+	return typeof segment.segmentId === "string" && segment.segmentId.trim() !== "" && typeof segment.text === "string" && (segment.language === void 0 || typeof segment.language === "string");
+}
+/** Assemble selected text after base-field validation and explicit variant overrides. */
+function assembleCaptionContent(rows, captionEntityId) {
+	requireEntityKind(rows, captionEntityId, "caption");
+	const caption = assembleEntityContent(rows, captionEntityId);
+	const script = findComposedAudioScript(rows, captionEntityId, "caption");
+	const segments = selectAudioScriptSegments({
+		...script,
+		payload: caption.payload
+	}, captionSelections(caption));
+	return {
+		caption,
+		audioScript: script,
+		segments,
+		text: segments.map((segment) => segment.text).join("")
+	};
+}
+/**
+* Assemble the complete Phonetic Script content for TTS: the composed
+* AudioScript's base text plus the variant's own phoneme and prosody fields.
+*/
+function assemblePhoneticScriptContent(rows, phoneticScriptEntityId) {
+	requireEntityKind(rows, phoneticScriptEntityId, "phonetic-script");
+	const phoneticScript = assembleEntityContent(rows, phoneticScriptEntityId);
+	const audioScript = findComposedAudioScript(rows, phoneticScriptEntityId, "phonetic-script");
+	const segments = scriptSegments({
+		...audioScript,
+		payload: phoneticScript.payload
+	});
+	return {
+		phoneticScript,
+		audioScript,
+		segments,
+		text: segments.map((segment) => segment.text).join("")
+	};
+}
+function captionSelections(caption) {
+	const selections = caption.payload.selections;
+	if (!Array.isArray(selections) || selections.length === 0) throw new ScriptCompositionError("empty_selection", caption.entityId, `Caption "${caption.entityId}" requires a non-empty segment selection into its AudioScript`);
+	if (!selections.every(isSegmentSelection)) throw new ScriptCompositionError("invalid_selection", caption.entityId, "Caption selections require a segmentId and optional textRange");
+	return selections;
+}
+function isSegmentSelection(value) {
+	return typeof value === "object" && value != null && !Array.isArray(value) && typeof value.segmentId === "string" && value.segmentId.trim() !== "" && Object.keys(value).every((key) => key === "segmentId" || key === "textRange");
+}
+/** Select source text without creating another authoritative text field. */
+function selectAudioScriptSegments(script, selections) {
+	if (!Array.isArray(selections) || selections.length === 0 || !selections.every(isSegmentSelection) || new Set(selections.map((s) => s.segmentId)).size !== selections.length) throw new ScriptCompositionError("invalid_selection", script.entityId, "Caption selections must be non-empty and name unique source segments");
+	const bySegmentId = new Map(scriptSegments(script).map((segment) => [segment.segmentId, segment]));
+	const selected = selections.map((selection) => {
+		const segment = bySegmentId.get(selection.segmentId);
+		if (segment === void 0) throw new ScriptCompositionError("unknown_segment", script.entityId, `Caption selection "${selection.segmentId}" does not name a segment of AudioScript "${script.entityId}"`);
+		if (selection.textRange === void 0) return segment;
+		const range = selection.textRange;
+		const points = Array.from(segment.text);
+		if (typeof range !== "object" || range === null || !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end <= range.start || range.end > points.length || Object.keys(range).some((key) => key !== "start" && key !== "end")) throw new ScriptCompositionError("invalid_selection", script.entityId, "Caption textRange must be a non-empty half-open Unicode code-point range within its source segment");
+		return {
+			...segment,
+			text: points.slice(range.start, range.end).join("")
+		};
+	});
+	if (!selected.map((segment) => segment.text).join("").trim()) throw new ScriptCompositionError("empty_selection", script.entityId, "Caption selection must contain visible source text");
+	return selected;
+}
+function requireEntityKind(rows, entityIdValue, entityKind) {
+	const entity = rows.entities.find((candidate) => candidate.entityId === entityIdValue);
+	if (entity === void 0) throw new ScriptCompositionError("composition_dangling", entityIdValue, `Entity "${entityIdValue}" does not exist`);
+	if (entity.entityKind !== entityKind) throw new ScriptCompositionError("composition_dangling", entityIdValue, `Entity "${entityIdValue}" must have kind "${entityKind}", got "${entity.entityKind}"`);
+	return entity;
+}
+//#endregion
+//#region ../medeo-dsl/src/rows.ts
+function entityToRow(entity) {
+	const { entityId, entityKind, ...payload } = entity;
+	if (!isJsonObject(payload)) throw new Error(`Entity "${entityId}" payload must contain only JSON values`);
+	return {
+		entityId,
+		entityKind,
+		payload
+	};
+}
+//#endregion
 //#region ../medeo-dsl/src/invariants.ts
+/**
+* Media variants own their Asset identity directly: a `physical-asset`
+* Relation may not bind them. Caption text is composed domain content, so
+* Captions do not bind Physical Assets either; the Relation vocabulary stays
+* open for future physical pipeline semantics.
+*/
+function validateMediaAssetIdentity(entity, index) {
+	return [...index.relationsOf(entity)].filter((relation) => relation.kind === "physical-asset").map(() => ({
+		code: "media_physical_asset_forbidden",
+		entityId: entity.entityId,
+		message: `Media entity "${entity.entityId}" owns its Asset identity; remove its physical-asset Relation`
+	}));
+}
 /** Validates one complete set of entities and its authoritative Relation rows. */
 function validateEntityRelationSet(entityRefs, index, options) {
 	const { entities, issues } = collectRelatedEntities(entityRefs, index);
 	const entityIds = new Set(entities.map((entity) => entity.entityId));
+	const rows = {
+		entities: entities.map((entity) => entityToRow(entity.current())),
+		relations: []
+	};
+	for (const entity of entities) try {
+		assembleEntityContent(rows, entity.entityId);
+	} catch (error) {
+		issues.push({
+			code: "invalid_variant_composition",
+			entityId: entity.entityId,
+			message: error instanceof Error ? error.message : "Invalid variant composition"
+		});
+	}
 	for (const entity of entities) {
 		const current = entity.current();
 		const entityIssues = validateEntity(entity, entityIds);
 		issues.push(...entityIssues);
+		if (isMediaAssetVariantKind(current.entityKind)) issues.push(...validateMediaAssetIdentity(entity, index));
 		if (entityIssues.some((issue) => issue.code === "invalid_entity_payload")) continue;
 		if (current.entityKind === "sequence-marker") {
 			const marker = entity;
@@ -201,7 +470,8 @@ function validateEntityRelationSet(entityRefs, index, options) {
 			issues.push(...validateClipPlacement(entity, index));
 		}
 		if (current.entityKind === "axvideo") issues.push(...validateAXVideoAdmission(entity, index));
-		if (current.entityKind === "caption") issues.push(...validateCaptionAsset(entity, index));
+		if (current.entityKind === "caption") issues.push(...validateCaptionComposition(entity, index, entities));
+		if (current.entityKind === "phonetic-script") issues.push(...validatePhoneticComposition(entity, index, entities));
 		issues.push(...validateSequenceComposition(entity));
 	}
 	issues.push(...validateClipAnchorCycles(entities, index));
@@ -213,7 +483,39 @@ function validateMarkerUse(marker, index) {
 	const axVideoEdges = ofKind(relations, "axvideo-marker");
 	const contentEdges = ofKind(relations, "marker-content");
 	const timelineEdges = ofKind(relations, "marker-timeline");
+	const scriptEdges = ofKind(relations, "audio-script-marker");
 	const issues = [];
+	if (scriptEdges.length > 0) {
+		if (clipEdges.length + axVideoEdges.length + contentEdges.length + timelineEdges.length > 0) issues.push({
+			code: "marker_container_xor",
+			entityId: marker.entityId,
+			message: "An AudioScript annotation Marker must not carry Clip, AXVideo, content, or Timeline relations"
+		});
+		const ranges = marker.current().segmentRanges;
+		if (!ranges?.length) issues.push({
+			code: "invalid_entity_payload",
+			entityId: marker.entityId,
+			message: "An AudioScript annotation Marker requires segmentRanges"
+		});
+		for (const relation of scriptEdges) {
+			const script = relation.other(marker)?.deref()?.current();
+			if (script?.entityKind !== "audio-script") continue;
+			const segments = script.segments;
+			if (!Array.isArray(segments)) continue;
+			const segmentIds = new Set(segments.map((segment) => segment.segmentId));
+			if (ranges?.some((range) => !segmentIds.has(range.segmentId))) issues.push({
+				code: "invalid_entity_payload",
+				entityId: marker.entityId,
+				message: "Annotation segmentRanges must name segments of the related AudioScript"
+			});
+		}
+		return issues;
+	}
+	if (marker.current().segmentRanges !== void 0) issues.push({
+		code: "invalid_entity_payload",
+		entityId: marker.entityId,
+		message: "segmentRanges belongs to an AudioScript annotation Marker, not a display Marker"
+	});
 	if (clipEdges.length + axVideoEdges.length !== 1) issues.push({
 		code: "marker_container_xor",
 		entityId: marker.entityId,
@@ -272,25 +574,35 @@ function validateAXVideoAdmission(axVideo, index) {
 		message: "AXVideo must have exactly one live AXVideo-Marker Relation"
 	}];
 }
-function validateCaptionAsset(caption, index) {
-	const assets = ofKind([...index.relationsOf(caption)], "physical-asset").map((relation) => relation.other(caption)?.deref()?.current()).filter((entity) => entity?.entityKind === "asset");
-	if (assets.length > 0) {
-		const captionText = caption.current().text;
-		if (!assets.some((asset) => {
-			const inline = asset.inline;
-			return isRecord(inline) && inline.mediaType === "text/plain" && inline.text !== captionText;
-		})) return [];
-		return [{
-			code: "caption_inline_asset_mismatch",
-			entityId: caption.entityId,
-			message: "Caption text must match the text/plain inline Physical Asset"
-		}];
+/** Validate a Caption against the complete entity set, including its directly held bases. */
+function validateCaptionComposition(caption, index, entities = []) {
+	return validateVariantComposition(caption, index, entities, "caption");
+}
+function validatePhoneticComposition(phonetic, index, entities = []) {
+	return validateVariantComposition(phonetic, index, entities, "phonetic-script");
+}
+function validateVariantComposition(variant, index, entities, kind) {
+	const issues = [];
+	if (kind === "caption" && ofKind([...index.relationsOf(variant)], "physical-asset").length > 0) issues.push({
+		code: "caption_physical_asset_forbidden",
+		entityId: variant.entityId,
+		message: "Caption text is composed from its AudioScript; Caption must not bind a Physical Asset"
+	});
+	const rows = {
+		entities: collectRelatedEntities([...entities, variant], index).entities.map((ref) => entityToRow(ref.current())),
+		relations: []
+	};
+	try {
+		if (kind === "caption") assembleCaptionContent(rows, variant.entityId);
+		else assemblePhoneticScriptContent(rows, variant.entityId);
+	} catch (error) {
+		issues.push({
+			code: kind === "caption" ? "caption_composition_required" : "phonetic_script_composition_required",
+			entityId: variant.entityId,
+			message: error instanceof Error ? error.message : "Invalid variant composition"
+		});
 	}
-	return [{
-		code: "caption_asset_required",
-		entityId: caption.entityId,
-		message: "Caption must have a Physical Asset Relation"
-	}];
+	return issues;
 }
 function validateClipPlacement(clip, index) {
 	const marker = ofKind([...index.relationsOf(clip)], "clip-marker")[0]?.other(clip)?.deref();
@@ -316,10 +628,10 @@ function validateClipPlacement(clip, index) {
 		const content = ofKind([...index.relationsOf(marker)], "marker-content")[0]?.other(marker)?.deref()?.current();
 		const track = ofKind([...index.relationsOf(clip)], "track-clip")[0]?.other(clip)?.deref()?.current();
 		const trackRole = track?.entityKind === "track" ? track.role : void 0;
-		if (content?.entityKind !== "audio" || trackRole !== "bgm" || !hasOrder) issues.push({
+		if (content?.entityKind !== "audio" || trackRole !== "bgm" || !hasOrder && !hasTarget) issues.push({
 			code: "timeline_duration_policy_invalid",
 			entityId: marker.entityId,
-			message: "Marker durationPolicy \"timeline\" is only valid for ordered Audio Clips on the bgm Track"
+			message: "Marker durationPolicy \"timeline\" is only valid for ordered or absolutely placed Audio Clips on the bgm Track"
 		});
 	}
 	return issues;
@@ -418,6 +730,18 @@ function validateKnownEntityPayload(entity) {
 	const value = entity;
 	const problems = [];
 	if (value.lifecycle !== void 0 && !isRecord(value.lifecycle)) problems.push("lifecycle must be an object when present");
+	if (entity.entityKind === "audio-script" || entity.entityKind === "phonetic-script") {
+		for (const key of [
+			"extent",
+			"sampling",
+			"coordinateSpace",
+			"sourceRange",
+			"targetRange",
+			"duration",
+			"startMs",
+			"endMs"
+		]) if (Object.hasOwn(value, key)) problems.push(`${key} is not intrinsic script data; assign an external annotation Marker`);
+	}
 	switch (entity.entityKind) {
 		case "track":
 			validateOptionalField(value, "hidden", "boolean", problems);
@@ -429,11 +753,13 @@ function validateKnownEntityPayload(entity) {
 		case "voice":
 		case "caption":
 			validateSequencePayload(value, "bounded", "native", problems);
+			if (entity.entityKind !== "caption") validateMediaAssetFields(value, problems);
 			if (entity.entityKind === "voice") validateVoicePayload(value, problems);
 			if (entity.entityKind === "caption") validateCaptionPayload(value, problems);
 			break;
 		case "image":
 			validateSequencePayload(value, "unbounded", "constant", problems);
+			validateMediaAssetFields(value, problems);
 			break;
 		case "axvideo":
 			validateSequencePayload(value, "bounded", "derived", problems);
@@ -442,9 +768,11 @@ function validateKnownEntityPayload(entity) {
 			validateMarkerPayload(value, problems);
 			break;
 		case "audio-script":
-		case "phonetic-script":
 			validateScriptPayload(value, problems);
 			break;
+		case "phonetic-script":
+			validatePhoneticScriptPayload(value, problems);
+			break;
 		case "timeline":
 		case "viewport": break;
 		case "clip":
@@ -481,22 +809,58 @@ function validateMarkerPayload(value, problems) {
 	} else if (duration.mode !== "from-source") problems.push("duration.mode must be \"from-source\" or \"fixed\"");
 	if (value.anchorOffset === void 0 && Object.hasOwn(value, "anchorOffset")) problems.push("anchorOffset cannot be undefined when present");
 	if (value.durationPolicy !== void 0 && value.durationPolicy !== "timeline") problems.push("durationPolicy must be \"timeline\" when present");
+	if (value.segmentRanges !== void 0) validateSegmentRanges(value.segmentRanges, problems);
+}
+/** Annotation Marker time values are directly assigned facts; no cross-references are allowed. */
+function validateSegmentRanges(value, problems) {
+	if (!Array.isArray(value)) {
+		problems.push("segmentRanges must be an array when present");
+		return;
+	}
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, entry] of value.entries()) {
+		if (!isRecord(entry)) {
+			problems.push(`segmentRanges[${index}] must be an object`);
+			continue;
+		}
+		if (typeof entry.segmentId !== "string") problems.push(`segmentRanges[${index}].segmentId must be a string`);
+		else if (seen.has(entry.segmentId)) problems.push(`segmentRanges[${index}].segmentId must be unique within the Marker`);
+		else seen.add(entry.segmentId);
+		for (const key of ["startMs", "endMs"]) {
+			const point = entry[key];
+			if (typeof point !== "number" || !Number.isFinite(point)) problems.push(`segmentRanges[${index}].${key} must be a finite number`);
+		}
+		if (typeof entry.startMs === "number" && Number.isFinite(entry.startMs) && typeof entry.endMs === "number" && Number.isFinite(entry.endMs) && entry.startMs > entry.endMs) problems.push(`segmentRanges[${index}].startMs must not exceed segmentRanges[${index}].endMs`);
+	}
 }
 function validateAssetPayload(value, problems) {
+	validateExternalLocator(value, problems);
+	validateStorageKey(value, problems);
+	if (value.inline !== void 0) problems.push("inline is not a physical location; text is domain content owned by its AudioScript");
+}
+/**
+* Media variants own their Asset locator directly: `external` is required and
+* textual domain content is owned by AudioScript; the physical-location
+* vocabularies cannot mix.
+*/
+function validateMediaAssetFields(value, problems) {
+	if (value.external === void 0) problems.push("external is required; media variants own their Asset identity");
+	else validateExternalLocator(value, problems);
+	validateStorageKey(value, problems);
+	if (value.inline !== void 0) problems.push("media variants use external locators, not inline domain text");
+}
+function validateExternalLocator(value, problems) {
 	const external = value.external;
-	if (external !== void 0) if (!isRecord(external)) problems.push("external must be an object when present");
-	else {
-		if (external.system !== "memota" && external.system !== "memota-speech") problems.push("external.system must be \"memota\" or \"memota-speech\"");
-		if (typeof external.key !== "string" || external.key.trim() === "") problems.push("external.key must be a non-empty string");
+	if (external === void 0) return;
+	if (!isRecord(external)) {
+		problems.push("external must be an object when present");
+		return;
 	}
+	if (external.system !== "memota" && external.system !== "memota-speech") problems.push("external.system must be \"memota\" or \"memota-speech\"");
+	if (typeof external.key !== "string" || external.key.trim() === "") problems.push("external.key must be a non-empty string");
+}
+function validateStorageKey(value, problems) {
 	if (value.storageKey !== void 0 && (typeof value.storageKey !== "string" || value.storageKey.trim() === "")) problems.push("storageKey must be a non-empty string when present");
-	const inline = value.inline;
-	if (inline !== void 0) if (!isRecord(inline)) problems.push("inline must be an object when present");
-	else {
-		if (inline.mediaType !== "text/plain") problems.push("inline.mediaType must be \"text/plain\"");
-		if (typeof inline.text !== "string") problems.push("inline.text must be a string");
-	}
-	if (external !== void 0 && inline !== void 0) problems.push("Asset must not combine external and inline physical locations");
 }
 function validateVoicePayload(value, problems) {
 	const voice = value.voice;
@@ -510,7 +874,26 @@ function validateVoicePayload(value, problems) {
 	if (voice.name !== void 0 && typeof voice.name !== "string") problems.push("voice.name must be a string when present");
 }
 function validateCaptionPayload(value, problems) {
-	if (value.text !== void 0 && typeof value.text !== "string") problems.push("text must be a string when present");
+	const selections = value.selections;
+	if (!Array.isArray(selections)) problems.push("selections must be a non-empty array of AudioScript segment selections");
+	else {
+		if (selections.length === 0) problems.push("selections must name at least one AudioScript segment");
+		const seen = /* @__PURE__ */ new Set();
+		for (const [index, selection] of selections.entries()) {
+			if (!isRecord(selection)) {
+				problems.push(`selections[${index}] must be an object`);
+				continue;
+			}
+			if (typeof selection.segmentId !== "string" || selection.segmentId.trim() === "") problems.push(`selections[${index}].segmentId must be a string`);
+			else if (seen.has(selection.segmentId)) problems.push(`selections[${index}].segmentId must be unique within the Caption`);
+			else seen.add(selection.segmentId);
+			if (Object.keys(selection).some((key) => key !== "segmentId" && key !== "textRange")) problems.push(`selections[${index}] may only contain segmentId and textRange`);
+			if (selection.textRange !== void 0) {
+				const range = selection.textRange;
+				if (!isRecord(range) || !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end <= range.start || Object.keys(range).some((key) => key !== "start" && key !== "end")) problems.push(`selections[${index}].textRange must be a non-empty half-open code-point range`);
+			}
+		}
+	}
 	const style = value.style;
 	if (style === void 0) return;
 	if (!isRecord(style)) {
@@ -545,6 +928,12 @@ function validateRange(value, path, required, problems) {
 	if (!Object.hasOwn(value, "start") || value.start === void 0) problems.push(`${path}.start is required`);
 	if (!Object.hasOwn(value, "end") || value.end === void 0) problems.push(`${path}.end is required`);
 }
+/** Phonetic variants store pronunciation fields only; base text stays in the AudioScript. */
+function validatePhoneticScriptPayload(value, problems) {
+	if (value.segments !== void 0) validateScriptPayload(value, problems);
+	if (value.phonemeScript !== void 0 && (typeof value.phonemeScript !== "string" || value.phonemeScript.trim() === "")) problems.push("phonemeScript must be a non-empty string when present");
+	if (value.prosody !== void 0 && !isRecord(value.prosody)) problems.push("prosody must be an object when present");
+}
 function validateScriptPayload(value, problems) {
 	if (!Array.isArray(value.segments)) {
 		problems.push("segments must be an array");
@@ -555,6 +944,15 @@ function validateScriptPayload(value, problems) {
 			problems.push(`segments[${index}] must be an object`);
 			continue;
 		}
+		for (const key of [
+			"startMs",
+			"endMs",
+			"start_ms",
+			"end_ms",
+			"sourceRange",
+			"targetRange",
+			"duration"
+		]) if (Object.hasOwn(segment, key)) problems.push(`segments[${index}].${key} is timing; attach an AudioScript annotation Marker instead`);
 		if (typeof segment.segmentId !== "string") problems.push(`segments[${index}].segmentId must be a string`);
 		if (typeof segment.text !== "string") problems.push(`segments[${index}].text must be a string`);
 		if (segment.language !== void 0 && typeof segment.language !== "string") problems.push(`segments[${index}].language must be a string when present`);
@@ -578,6 +976,7 @@ function visitPeerEntityIdPaths(value, entityKind, parentPath, ancestors, paths)
 	if (Array.isArray(value)) for (const [index, item] of value.entries()) visitPeerEntityIdPaths(item, entityKind, `${parentPath}[${index}]`, ancestors, paths);
 	else for (const [key, child] of Object.entries(value)) {
 		const path = parentPath.length === 0 ? key : `${parentPath}.${key}`;
+		if (parentPath.length === 0 && key === "baseEntityIds") continue;
 		if (!(parentPath.length === 0 && key === "entityId") && !isOwnedLocalIdPath(entityKind, path) && isEntityIdFieldName(key)) paths.push(path);
 		visitPeerEntityIdPaths(child, entityKind, path, ancestors, paths);
 	}
@@ -597,7 +996,7 @@ function visitPeerEntityValues(value, entityKind, ownEntityId, entityIds, path,
 	ancestors.add(value);
 	if (Array.isArray(value)) for (const [index, item] of value.entries()) visitPeerEntityValues(item, entityKind, ownEntityId, entityIds, `${path}[${index}]`, ancestors, paths);
 	else for (const [key, child] of Object.entries(value)) {
-		if (path.length === 0 && (key === "entityId" || key === "entityKind")) continue;
+		if (path.length === 0 && (key === "entityId" || key === "entityKind" || key === "baseEntityIds")) continue;
 		visitPeerEntityValues(child, entityKind, ownEntityId, entityIds, path.length === 0 ? key : `${path}.${key}`, ancestors, paths);
 	}
 	ancestors.delete(value);
@@ -613,15 +1012,27 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 		"axvideo"
 	].includes(entityKind) && /^(?:sampling|coordinateSpace|coordinateSpace\.unit|extent\.kind)$/.test(path)) return true;
 	if (entityKind === "sequence-marker" && /^(?:durationPolicy|duration\.mode|timeRemapping\.(?:kind|mode))$/.test(path)) return true;
-	if (entityKind === "asset" && /^(?:external\.(?:system|key)|storageKey|inline\.(?:mediaType|text))$/.test(path)) return true;
+	if (entityKind === "sequence-marker" && /^segmentRanges\[\d+\]\.segmentId$/.test(path)) return true;
+	if (entityKind === "asset" && /^(?:external\.(?:system|key)|storageKey)$/.test(path)) return true;
+	if (isMediaAssetVariantKind(entityKind) && /^(?:external\.(?:system|key)|storageKey)$/.test(path)) return true;
 	if (entityKind === "voice" && /^voice\.(?:system|key|name)$/.test(path)) return true;
-	if (entityKind === "caption" && (path === "text" || path.startsWith("style."))) return true;
-	if ((entityKind === "audio-script" || entityKind === "phonetic-script") && /^segments\[\d+\]\.(?:segmentId|text|language)$/.test(path)) return true;
+	if (entityKind === "caption" && (path.startsWith("style.") || /^selections\[\d+\]\.segmentId$/.test(path))) return true;
+	if ([
+		"audio-script",
+		"caption",
+		"phonetic-script"
+	].includes(entityKind) && /^segments\[\d+\]\.(?:segmentId|text|language)$/.test(path)) return true;
 	return false;
 }
 function isOwnedLocalIdPath(entityKind, path) {
 	if (path === "lifecycle.actorId") return true;
-	if ((entityKind === "audio-script" || entityKind === "phonetic-script") && /^segments\[\d+\]\.segmentId$/.test(path)) return true;
+	if ([
+		"audio-script",
+		"caption",
+		"phonetic-script"
+	].includes(entityKind) && /^segments\[\d+\]\.segmentId$/.test(path)) return true;
+	if (entityKind === "caption" && /^selections\[\d+\]\.segmentId$/.test(path)) return true;
+	if (entityKind === "sequence-marker" && /^segmentRanges\[\d+\]\.segmentId$/.test(path)) return true;
 	if (entityKind === "asset" && /^(?:tracks\[\d+\]\.trackId|renditions\[\d+\]\.renditionId)$/.test(path)) return true;
 	return false;
 }
@@ -676,35 +1087,6 @@ function ofKind(relations, kind) {
 	return relations.filter((relation) => relation.kind === kind);
 }
 //#endregion
-//#region ../medeo-dsl/src/json-values.ts
-const nativeObjectConstructorSource = Function.prototype.toString.call(Object);
-function isJsonObject(value) {
-	return isJsonValue(value, /* @__PURE__ */ new Set()) && !Array.isArray(value) && value !== null;
-}
-function isJsonValue(value, ancestors) {
-	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
-	if (typeof value === "number") return Number.isFinite(value);
-	if (typeof value !== "object") return false;
-	if (!Array.isArray(value) && !isPlainObject(value)) return false;
-	if (ancestors.has(value)) return false;
-	ancestors.add(value);
-	const valid = Array.isArray(value) ? value.every((item) => isJsonValue(item, ancestors)) : Object.values(value).every((item) => isJsonValue(item, ancestors));
-	ancestors.delete(value);
-	return valid;
-}
-/** Recognize an ordinary object from any VM realm without admitting class instances. */
-function isPlainObject(value) {
-	try {
-		const prototype = Object.getPrototypeOf(value);
-		if (prototype === null) return true;
-		if (Object.getPrototypeOf(prototype) !== null) return false;
-		const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
-		return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === nativeObjectConstructorSource;
-	} catch {
-		return false;
-	}
-}
-//#endregion
 //#region ../medeo-dsl/src/relation-specs.ts
 const timelineTrackRelationSpec = emptySpec("timeline-track", "timeline", "track");
 const trackClipRelationSpec = emptySpec("track-clip", "track", "clip");
@@ -727,8 +1109,6 @@ const generatedRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => endpoints.every((endpoint) => isGeneratedMedia(endpoint.current())),
 	validateMetadata: isEmptyMetadata
 });
-const phoneticScriptProvenanceRelationSpec = metadataSpec("phonetic-script-provenance", "phonetic-script", "audio-script", isSegmentAlignmentMetadata);
-const captionProvenanceRelationSpec = metadataSpec("caption-provenance", "caption", "audio-script", isSegmentAlignmentMetadata);
 const captionAlignmentRelationSpec = Object.freeze({
 	kind: "caption-alignment",
 	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["caption"]), new Set(["audio", "voice"])),
@@ -740,13 +1120,31 @@ const clipAnchorRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => endpoints[0].current().entityKind === "clip" && endpoints[1].current().entityKind === "clip",
 	validateMetadata: isEmptyMetadata
 });
-/** `audio-script-render(output, script)` means endpoint 0 was rendered from endpoint 1. */
-const audioScriptRenderRelationSpec = Object.freeze({
-	kind: "audio-script-render",
-	validateEndpoints: (endpoints) => {
-		const outputKind = endpoints[0].current().entityKind;
-		return (outputKind === "audio" || outputKind === "voice") && endpoints[1].current().entityKind === "audio-script";
-	},
+/** Voice is generated from PhoneticScript; kinds determine roles regardless of endpoint positions. */
+const phoneticScriptRenderRelationSpec = Object.freeze({
+	kind: "phonetic-script-render",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["voice"]), new Set(["phonetic-script"])),
+	validateMetadata: isEmptyMetadata
+});
+/** AudioScript was transcribed from Audio, Video, or recorded Voice; kinds determine roles. */
+const audioScriptSourceRelationSpec = Object.freeze({
+	kind: "audio-script-source",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set([
+		"audio",
+		"video",
+		"voice"
+	])),
+	validateMetadata: isEmptyMetadata
+});
+/**
+* `audio-script-marker(script, marker)` attaches an annotation Sequence Marker
+* whose `segmentRanges` hold directly assigned per-Segment time values. The
+* script keeps no Sequence and no Clip admission; annotation Markers cannot
+* enter Clip/AXVideo use chains (enforced by the marker-use invariant).
+*/
+const audioScriptMarkerRelationSpec = Object.freeze({
+	kind: "audio-script-marker",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set(["sequence-marker"])),
 	validateMetadata: isEmptyMetadata
 });
 /** Built-in kinds are reserved; callers may add specs only under new names. */
@@ -759,11 +1157,11 @@ const builtInRelationSpecs = Object.freeze([
 	markerTimelineRelationSpec,
 	physicalAssetRelationSpec,
 	generatedRelationSpec,
-	phoneticScriptProvenanceRelationSpec,
-	captionProvenanceRelationSpec,
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
-	audioScriptRenderRelationSpec
+	phoneticScriptRenderRelationSpec,
+	audioScriptSourceRelationSpec,
+	audioScriptMarkerRelationSpec
 ]);
 function emptySpec(kind, a, b) {
 	return metadataSpec(kind, a, b, isEmptyMetadata);
@@ -801,9 +1199,6 @@ function isAssetBinding(value) {
 	const orderingKey = /(order|ordinal|position|rank|index|z[_-]?index)/i;
 	return Object.keys(value).every((key) => !orderingKey.test(key));
 }
-function isSegmentAlignmentMetadata(value) {
-	return isJsonObject(value) && Object.hasOwn(value, "segmentAlignment");
-}
 function isCaptionAlignmentMetadata(value) {
 	return isJsonObject(value) && Object.hasOwn(value, "alignment");
 }
@@ -860,7 +1255,7 @@ var BiRelationIndex = class {
 	byRelationId = /* @__PURE__ */ new Map();
 	link(input) {
 		if (input.spec.kind === "generated") throw new Error("Author generated Relations with linkGenerated({ output, input })");
-		if (input.spec.kind === "clip-anchor" || input.spec.kind === "audio-script-render") throw new Error(`Author ordered ${input.spec.kind} Relations with the dedicated role-named method`);
+		if (input.spec.kind === "clip-anchor" || input.spec.kind === "phonetic-script-render" || input.spec.kind === "audio-script-source") throw new Error(`Author ordered ${input.spec.kind} Relations with the dedicated role-named method`);
 		return this.linkValidated(input);
 	}
 	/** Author `generated(output, input)` without exposing positional arguments. */
@@ -883,12 +1278,22 @@ var BiRelationIndex = class {
 			trace: input.trace
 		});
 	}
-	/** Author `audio-script-render(output, script)` without exposing positional arguments. */
-	linkAudioScriptRender(input) {
+	/** Author `phonetic-script-render(output, phoneticScript)` without exposing positional arguments. */
+	linkPhoneticScriptRender(input) {
 		return this.linkValidated({
 			relationId: input.relationId,
-			spec: audioScriptRenderRelationSpec,
-			endpoints: [input.output, input.script],
+			spec: phoneticScriptRenderRelationSpec,
+			endpoints: [input.output, input.phoneticScript],
+			metadata: {},
+			trace: input.trace
+		});
+	}
+	/** Author `audio-script-source(script, source)` without exposing positional arguments. */
+	linkAudioScriptSource(input) {
+		return this.linkValidated({
+			relationId: input.relationId,
+			spec: audioScriptSourceRelationSpec,
+			endpoints: [input.script, input.source],
 			metadata: {},
 			trace: input.trace
 		});
@@ -979,7 +1384,13 @@ function decodeEntityRelationRows(rows, options) {
 	const entitiesById = /* @__PURE__ */ new Map();
 	const extensionEntityKinds = new Set(options.entityKinds ?? []);
 	for (const row of rows.entities) {
-		const entity = decodeEntityRow(row, extensionEntityKinds, issues);
+		let entity = decodeEntityRow(row, extensionEntityKinds, issues);
+		if (entity != null) try {
+			entity = decodeEntityRow(assembleEntityContent(rows, row.entityId), extensionEntityKinds, issues);
+		} catch (error) {
+			issues.push(errorMessage(error));
+			continue;
+		}
 		if (entity == null) continue;
 		const ref = createEntityRef(entity);
 		if (entitiesById.has(ref.entityId)) {
@@ -1112,17 +1523,6 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
-//#region ../medeo-dsl/src/rows.ts
-function entityToRow(entity) {
-	const { entityId, entityKind, ...payload } = entity;
-	if (!isJsonObject(payload)) throw new Error(`Entity "${entityId}" payload must contain only JSON values`);
-	return {
-		entityId,
-		entityKind,
-		payload
-	};
-}
-//#endregion
 //#region src/entity/entity-sandbox.ts
 const ASSET_SOURCE_KEY = "external";
 const MEMOTA_SYSTEM = "memota";
@@ -1139,6 +1539,7 @@ var EntitySandbox = class {
 	constructor(options) {
 		this.original = cloneSnapshot(options.state ?? {
 			revision: 0,
+			audioScriptEntityId: null,
 			entities: [],
 			relations: []
 		});
@@ -1155,6 +1556,20 @@ var EntitySandbox = class {
 	getCommands() {
 		return this.commands;
 	}
+	/** Host-owned fixed structure is journaled through the same CAS graph as model edits. */
+	ensureFoundation(timelinePayload = {}) {
+		const foundation = ensureEditorFoundation(toDslRows(this.state), this.idFactory, timelinePayload);
+		this.appendResourceRows(foundation.rows);
+	}
+	get audioScriptEntityId() {
+		return this.state.audioScriptEntityId;
+	}
+	setDocumentAudioScript(audioScriptEntityId) {
+		this.record({
+			kind: "set-document-audio-script",
+			audioScriptEntityId
+		});
+	}
 	rollbackTo(index) {
 		if (!Number.isInteger(index) || index < 0 || index > this.commands.length) throw new Error(`rollbackTo: entity checkpoint index ${index} is past journal length ${this.commands.length}`);
 		const prefix = this.commands.slice(0, index);
@@ -1165,7 +1580,13 @@ var EntitySandbox = class {
 		this.onTruncate?.(index);
 	}
 	buildPlan() {
-		decodeEntityRelationRows(toDslRows(this.state), numericMarkerComparators);
+		const rows = toDslRows(this.state);
+		decodeEntityRelationRows(rows, numericMarkerComparators);
+		assertCanonicalEditorResources(rows);
+		readDocumentAudioScript({
+			rows,
+			audioScriptEntityId: this.state.audioScriptEntityId
+		});
 		const currentEntityIds = new Set(this.state.entities.map((entity) => entity.entity_id));
 		const currentRelationIds = new Set(this.state.relations.map((relation) => relation.relation_id));
 		return {
@@ -1179,6 +1600,9 @@ var EntitySandbox = class {
 	renderPreview() {
 		const lines = [`Entity plan: base_revision=${this.original.revision} commands=${this.commands.length} entities=${this.state.entities.length} relations=${this.state.relations.length}`];
 		for (const command of this.commands) switch (command.kind) {
+			case "set-document-audio-script":
+				lines.push(`~ document audioScriptEntityId=${command.audioScriptEntityId}`);
+				break;
 			case "create-entity":
 				lines.push(`+ entity ${command.entity.entity_id} kind=${command.entity.entity_kind}`);
 				break;
@@ -1198,21 +1622,67 @@ var EntitySandbox = class {
 		}
 		return lines.join("\n");
 	}
+	assembledEntity(entity) {
+		const assembled = assembleEntityContent(toDslRows(this.state), createEntityId(entity.entity_id));
+		return {
+			...clone(entity),
+			payload: assembled.payload
+		};
+	}
 	buildEntityFacade() {
 		return {
-			list: () => clone(this.state.entities),
+			list: () => this.state.entities.map((entity) => this.assembledEntity(entity)),
 			get: (entityId) => {
 				const entity = this.state.entities.find((candidate) => candidate.entity_id === entityId);
-				return entity == null ? null : clone(entity);
+				return entity == null ? null : this.assembledEntity(entity);
 			},
 			findByAssetId: (assetId) => {
 				assertTrimmed(assetId, "assetId");
-				return clone(this.state.entities.filter((entity) => entity.entity_kind === "asset" && isImportedMemotaAsset(entity.payload, assetId)));
+				return clone(this.state.entities.map((entity) => this.assembledEntity(entity)).filter((entity) => isMediaAssetVariantKind(entity.entity_kind) && isImportedMemotaAsset(entity.payload, assetId)));
+			},
+			readCaptionContent: (entityId) => {
+				const assembled = assembleCaptionContent(toDslRows(this.state), createEntityId(entityId));
+				return clone({
+					audio_script_entity_id: assembled.audioScript.entityId,
+					text: assembled.text,
+					segments: assembled.segments.map((segment) => ({ ...segment }))
+				});
+			},
+			readPhoneticScriptContent: (entityId) => {
+				const assembled = assemblePhoneticScriptContent(toDslRows(this.state), createEntityId(entityId));
+				const own = assembled.phoneticScript.payload;
+				return clone({
+					audio_script_entity_id: assembled.audioScript.entityId,
+					text: assembled.text,
+					segments: assembled.segments.map((segment) => ({ ...segment })),
+					...typeof own.phonemeScript === "string" ? { phonemeScript: own.phonemeScript } : {},
+					...isJsonObject(own.prosody) ? { prosody: clone(own.prosody) } : {}
+				});
 			},
 			create: (input) => this.createEntity(input),
-			update: (input) => this.updateEntity(input),
+			update: (input) => {
+				assertTrimmed(input.entity_id, "entity_id");
+				if (!this.state.entities.some((entity) => entity.entity_id === input.entity_id)) throw new Error(`Entity id "${input.entity_id}" does not exist`);
+				const updates = updateEntityFields(toDslRows(this.state), createEntityId(input.entity_id), input.payload);
+				for (const row of updates) this.replaceOwnedPayload({
+					entity_id: row.entityId,
+					payload: row.payload
+				});
+			},
+			declareFields: (input) => {
+				const current = this.state.entities.find((entity) => entity.entity_id === input.entity_id);
+				if (current === void 0) throw new Error(`Unknown entity "${input.entity_id}"`);
+				assembleEntityContent(toDslRows(this.state), createEntityId(input.entity_id));
+				this.replaceOwnedPayload({
+					entity_id: input.entity_id,
+					payload: {
+						...current.payload,
+						...input.payload
+					}
+				});
+			},
 			delete: (input) => this.deleteEntity(input),
-			importAsset: (input) => this.importAsset(input)
+			ensureMedia: (fact) => this.ensureMedia(fact)
 		};
 	}
 	buildRelationFacade() {
@@ -1226,7 +1696,8 @@ var EntitySandbox = class {
 			link: (input) => this.link(input),
 			linkGenerated: (input) => this.linkGenerated(input),
 			linkClipAnchor: (input) => this.linkClipAnchor(input),
-			linkAudioScriptRender: (input) => this.linkAudioScriptRender(input),
+			linkPhoneticScriptRender: (input) => this.linkPhoneticScriptRender(input),
+			linkAudioScriptSource: (input) => this.linkAudioScriptSource(input),
 			unlink: (input) => this.unlinkRelation(input)
 		};
 	}
@@ -1234,6 +1705,21 @@ var EntitySandbox = class {
 		if (!isKnownEntityKind(input.entity_kind)) throw new Error(`Unknown or extension Entity kind "${String(input.entity_kind)}"`);
 		const payload = clone(input.payload);
 		if (!isJsonObject(payload)) throw new Error("Entity payload must contain only JSON values");
+		if (input.entity_kind === "timeline" || input.entity_kind === "track") {
+			const matches = this.state.entities.filter((entity) => entity.entity_kind === input.entity_kind && (input.entity_kind === "timeline" || entity.payload.role === payload.role));
+			if (matches.length > 1) throw new Error(`Ambiguous editor ${input.entity_kind}; resolve existing identities`);
+			if (matches[0] !== void 0) return this.reuseEntity(matches[0], input, payload);
+		}
+		const external = payload.external;
+		if (isMediaAssetVariantKind(input.entity_kind) && isJsonObject(external) && (external.system === "memota" || external.system === "memota-speech") && typeof external.key === "string") {
+			const matches = this.state.entities.filter((entity) => isMediaAssetVariantKind(entity.entity_kind) && isJsonObject(entity.payload.external) && entity.payload.external.system === external.system && entity.payload.external.key === external.key);
+			if (matches.length > 1) throw new Error(`Ambiguous Asset bindings for ${external.key}`);
+			const existing = matches[0];
+			if (existing !== void 0) {
+				if (existing.entity_kind !== input.entity_kind) throw new Error(`Asset kind conflicts for ${external.key}; cannot change ${existing.entity_kind} to ${input.entity_kind}`);
+				return this.reuseEntity(existing, input, payload);
+			}
+		}
 		const entityId = input.entity_id ?? this.idFactory("entity");
 		assertTrimmed(entityId, "entity_id");
 		const entity = {
@@ -1252,7 +1738,21 @@ var EntitySandbox = class {
 		});
 		return entityId;
 	}
-	updateEntity(input) {
+	reuseEntity(existing, input, payload) {
+		if (input.entity_id !== void 0 && input.entity_id !== existing.entity_id) throw new Error(`Entity already exists; reuse ${existing.entity_id}`);
+		for (const [key, value] of Object.entries(payload)) if (existing.payload[key] !== void 0 && !sameJson(existing.payload[key], value)) throw new Error(`Resource facts conflict for ${existing.entity_id}: ${key}`);
+		const merged = {
+			...existing.payload,
+			...payload
+		};
+		if (!sameJson(existing.payload, merged)) this.replaceOwnedPayload({
+			entity_id: existing.entity_id,
+			payload: merged
+		});
+		return existing.entity_id;
+	}
+	/** Host persistence adapter; never exposed as the DSL field update operation. */
+	replaceOwnedPayload(input) {
 		assertTrimmed(input.entity_id, "entity_id");
 		const payload = clone(input.payload);
 		if (!isJsonObject(payload)) throw new Error("Entity payload must contain only JSON values");
@@ -1269,21 +1769,42 @@ var EntitySandbox = class {
 			entity_id: input.entity_id
 		});
 	}
-	importAsset(input) {
-		assertTrimmed(input.asset_id, "asset_id");
-		const payload = input.payload === void 0 ? {} : clone(input.payload);
-		if (!isJsonObject(payload)) throw new Error("Asset payload must contain only JSON values");
-		return this.createEntity({
-			...input.entity_id !== void 0 ? { entity_id: input.entity_id } : {},
-			entity_kind: "asset",
-			payload: {
-				...payload,
-				[ASSET_SOURCE_KEY]: {
-					system: MEMOTA_SYSTEM,
-					key: input.asset_id
-				}
-			}
-		});
+	ensureMedia(fact) {
+		const checkpoint = this.commandCount;
+		try {
+			const imported = importMediaAsset(toDslRows(this.state), fact, this.idFactory);
+			this.appendResourceRows(imported.rows);
+			return { contentEntityId: imported.contentEntityId };
+		} catch (error) {
+			this.rollbackTo(checkpoint);
+			throw error;
+		}
+	}
+	appendResourceRows(rows) {
+		for (const row of rows.entities) {
+			const existing = this.state.entities.find((entity) => entity.entity_id === row.entityId);
+			if (existing === void 0) this.createEntity({
+				entity_id: row.entityId,
+				entity_kind: row.entityKind,
+				payload: row.payload
+			});
+			else if (!sameJson(existing.payload, row.payload)) this.replaceOwnedPayload({
+				entity_id: row.entityId,
+				payload: clone(row.payload)
+			});
+		}
+		for (const row of rows.relations) {
+			if (this.state.relations.some((relation) => relation.relation_id === row.relationId)) continue;
+			if (row.relationKind !== "timeline-track") throw new Error(`Unexpected resource Relation ${row.relationKind}`);
+			this.link({
+				relation_id: row.relationId,
+				relation_kind: row.relationKind,
+				endpoint_0_entity_id: row.endpoint0EntityId,
+				endpoint_1_entity_id: row.endpoint1EntityId,
+				metadata: clone(row.metadata),
+				trace: clone(row.trace)
+			});
+		}
 	}
 	link(input) {
 		if (input.relation_kind === "generated") throw new Error("Author generated Relations with relations.linkGenerated({ output_entity_id, input_entity_id })");
@@ -1346,19 +1867,40 @@ var EntitySandbox = class {
 		});
 		return relation.relation_id;
 	}
-	linkAudioScriptRender(input) {
+	linkPhoneticScriptRender(input) {
 		const relation = this.relationFromInput({
 			...input.relation_id !== void 0 ? { relation_id: input.relation_id } : {},
 			endpoint_0_entity_id: input.output_entity_id,
-			endpoint_1_entity_id: input.script_entity_id,
+			endpoint_1_entity_id: input.phonetic_script_entity_id,
 			metadata: {},
 			...input.trace !== void 0 ? { trace: input.trace } : {}
-		}, "audio-script-render");
+		}, "phonetic-script-render");
 		const [output, script] = this.refsFor(relation);
-		new BiRelationIndex().linkAudioScriptRender({
+		new BiRelationIndex().linkPhoneticScriptRender({
 			relationId: createRelationId(relation.relation_id),
 			output,
+			phoneticScript: script,
+			trace: relation.trace
+		});
+		this.record({
+			kind: "link-relation",
+			relation
+		});
+		return relation.relation_id;
+	}
+	linkAudioScriptSource(input) {
+		const relation = this.relationFromInput({
+			...input.relation_id !== void 0 ? { relation_id: input.relation_id } : {},
+			endpoint_0_entity_id: input.script_entity_id,
+			endpoint_1_entity_id: input.source_entity_id,
+			metadata: {},
+			...input.trace !== void 0 ? { trace: input.trace } : {}
+		}, "audio-script-source");
+		const [script, source] = this.refsFor(relation);
+		new BiRelationIndex().linkAudioScriptSource({
+			relationId: createRelationId(relation.relation_id),
 			script,
+			source,
 			trace: relation.trace
 		});
 		this.record({
@@ -1407,6 +1949,13 @@ var EntitySandbox = class {
 	}
 	apply(command, enforceIdentity) {
 		switch (command.kind) {
+			case "set-document-audio-script":
+				readDocumentAudioScript({
+					rows: toDslRows(this.state),
+					audioScriptEntityId: command.audioScriptEntityId
+				});
+				this.state.audioScriptEntityId = command.audioScriptEntityId;
+				return;
 			case "create-entity": {
 				if (enforceIdentity && this.state.entities.some((entity) => entity.entity_id === command.entity.entity_id)) throw new Error(`Entity id "${command.entity.entity_id}" already exists`);
 				const original = this.original.entities.find((entity) => entity.entity_id === command.entity.entity_id);
@@ -1426,6 +1975,7 @@ var EntitySandbox = class {
 				return;
 			}
 			case "delete-entity": {
+				if (this.state.audioScriptEntityId === command.entity_id) throw new Error("Clear or switch the document AudioScript association before deleting its entity");
 				const index = this.state.entities.findIndex((entity) => entity.entity_id === command.entity_id);
 				if (index < 0) throw new Error(`Entity id "${command.entity_id}" does not exist`);
 				const incidentRelationIds = this.state.relations.filter((relation) => relation.endpoint_0_entity_id === command.entity_id || relation.endpoint_1_entity_id === command.entity_id).map((relation) => relation.relation_id).sort();
@@ -1452,7 +2002,7 @@ var EntitySandbox = class {
 };
 function isImportedMemotaAsset(payload, assetId) {
 	const external = payload[ASSET_SOURCE_KEY];
-	return external != null && !Array.isArray(external) && typeof external === "object" && external.system === MEMOTA_SYSTEM && external.key === assetId;
+	return external != null && !Array.isArray(external) && typeof external === "object" && (external.system === MEMOTA_SYSTEM || external.system === "memota-speech") && external.key === assetId;
 }
 function toDslEntity(entity) {
 	return {
@@ -1484,6 +2034,13 @@ function cloneSnapshot(state) {
 function clone(value) {
 	return structuredClone(value);
 }
+function sameJson(left, right) {
+	if (left === right) return true;
+	if (Array.isArray(left) && Array.isArray(right)) return left.length === right.length && left.every((value, index) => sameJson(value, right[index]));
+	if (!isJsonObject(left) || !isJsonObject(right)) return false;
+	const keys = Object.keys(left);
+	return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && sameJson(left[key], right[key]));
+}
 function assertTrimmed(value, label) {
 	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) throw new Error(`${label} must be a non-empty trimmed string`);
 }
@@ -1836,6 +2393,6 @@ function replayJournalSync(adapter, journal) {
 	}
 }
 //#endregion
-export { collectAffectedPartIds as a, createRelationId as i, EntitySandbox as n, renderPreview as o, createEntityId as r, renderCompactProjection as s, EditSandboxSession as t };
+export { createRelationId as a, renderPreview as c, createEntityId as i, renderCompactProjection as l, EntitySandbox as n, isMediaAssetVariantKind as o, toDslRows as r, collectAffectedPartIds as s, EditSandboxSession as t };
 
-//# sourceMappingURL=script-session-CHyIUBkO.mjs.map
+//# sourceMappingURL=script-session-C2uQHYt4.mjs.map