@mengine/medeo-client 1.2.1-alpha.0 → 1.2.1-alpha.10

package/dist/{document-49OdvviW.js → document-CC9M0bf9.js}

@@ -1,3 +1,4 @@
+import { u as volumeSchema } from "./shared-iWnU2osE.js";
 import { Mirror, schema } from "loro-mirror";
 import { z } from "zod";
 import { LoroDoc } from "loro-crdt";
@@ -114,7 +115,7 @@ const speechPart = schema.LoroMap({
 	voice: schema.String().transform(jsonTransform()),
 	caption_ids: schema.String().transform(jsonTransform())
 }, { required: false });
-const captionStyle = schema.LoroMap({
+const captionStyle$1 = schema.LoroMap({
 	font_id: schema.String({ required: false }),
 	font_size: schema.Number({ required: false }),
 	font_color: schema.String({ required: false }),
@@ -132,7 +133,7 @@ const captionPart = schema.LoroMap({
 	speech_part_id: schema.String(),
 	text: schema.String(),
 	start_ms: schema.Number(),
-	style: captionStyle
+	style: captionStyle$1
 }, {
 	required: false,
 	mergeableMapChildContainers: true
@@ -210,6 +211,8 @@ function recordEntries(record) {
 //#endregion
 //#region src/document/types.ts
 const VIDEO_DOCUMENT_SCHEMA_VERSION = "video-document/v0";
+/** A server-derived compatibility view, never an editor write authority. */
+const ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION = "video-document/entity-projection-v1";
 /** The linear speed multiplier of a `speed_shift`, defaulting to 1 (original). */
 function speedOf(speedShift) {
 	const speed = speedShift?.config?.linear?.speed;
@@ -547,7 +550,10 @@ function solveVideoDocument(document) {
 	const doc = videoDocumentToTimelineDoc(document);
 	let counter = 0;
 	const derivedFillerPartIds = /* @__PURE__ */ new Set();
-	cascadeAfterVideoClipChanges(doc, () => {
+	if (document.meta.schema_version === "video-document/entity-projection-v1") {
+		for (const track of document.tracks ?? []) if (track.items?.some((item) => item.time_position.mode === "sequential" || item.time_position.mode === "anchored" && !Number.isSafeInteger(item.fallback_abs_ms))) throw new Error("An entity timeline projection must contain resolved placement facts");
+		recalculateTimelineDuration(doc);
+	} else cascadeAfterVideoClipChanges(doc, () => {
 		const partId = `empty_${counter++}`;
 		derivedFillerPartIds.add(partId);
 		return { partId };
@@ -851,7 +857,7 @@ const partUnionSchema = z.union([
 	].filter((k) => p[k] != null).length === 1;
 }, { message: "A part_library value must have exactly one of video_clip / speech / caption / bgm" });
 const videoDocumentMetaSchema = z.object({
-	schema_version: z.literal(VIDEO_DOCUMENT_SCHEMA_VERSION),
+	schema_version: z.enum([VIDEO_DOCUMENT_SCHEMA_VERSION, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION]),
 	draft_id: z.string().optional(),
 	project_id: z.string().optional(),
 	owner_id: z.string().optional(),
@@ -1483,6 +1489,1462 @@ function emptyLaneTracks() {
 	}));
 }
 //#endregion
+//#region ../medeo-dsl/src/entities.ts
+function hasSequence(entity) {
+	if (isKnownNonSequenceKind(entity.entityKind) || isReservedEntityKind(entity.entityKind)) return false;
+	return isSequenceFields(entity);
+}
+function isSequenceFields(value) {
+	if (!isRecord$1(value)) return false;
+	const extent = value.extent;
+	if (!isRecord$1(extent) || !("start" in extent) || extent.start === void 0) return false;
+	if (extent.kind === "bounded" && (!("end" in extent) || extent.end === void 0)) return false;
+	if (extent.kind === "unbounded" && "end" in extent) return false;
+	if (extent.kind !== "bounded" && extent.kind !== "unbounded") return false;
+	if (value.sampling !== "native" && value.sampling !== "constant" && value.sampling !== "derived") return false;
+	return "coordinateSpace" in value && value.coordinateSpace !== void 0;
+}
+function isKnownSequenceKind(kind) {
+	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);
+}
+function isReservedEntityKind(kind) {
+	const normalized = kind.toLowerCase().replaceAll("-", "").replaceAll("_", "");
+	return normalized === "speech" || normalized === "videodocument";
+}
+function isKnownNonSequenceKind(kind) {
+	return kind === "timeline" || kind === "track" || kind === "clip" || kind === "asset" || kind === "sequence-marker" || kind === "viewport" || kind === "audio-script" || kind === "phonetic-script";
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value != null && !Array.isArray(value);
+}
+//#endregion
+//#region ../medeo-dsl/src/ids.ts
+function createEntityId(value) {
+	return createId(value, "EntityId");
+}
+function createRelationId(value) {
+	return createId(value, "RelationId");
+}
+function createId(value, label) {
+	if (value.length === 0 || value.trim() !== value) throw new Error(`${label} must be a non-empty trimmed string`);
+	return value;
+}
+//#endregion
+//#region ../medeo-dsl/src/invariants.ts
+/**
+* Media variants own their Asset identity directly: a `physical-asset`
+* Relation may not bind them. Caption inline text (and other non-media
+* Sequence entities) keep their Asset binding.
+*/
+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));
+	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;
+			issues.push(...validateMarkerUse(entity, index));
+			issues.push(...validateMarkerRanges(marker, {
+				source: (left, right) => options.compareMarkerPoints(marker, "source", left, right),
+				target: (left, right) => options.compareMarkerPoints(marker, "target", left, right)
+			}));
+			issues.push(...validateMarkerSourceBounds(marker, index, (left, right) => options.compareMarkerPoints(marker, "source", left, right)));
+		}
+		if (current.entityKind === "clip") {
+			issues.push(...validateClipAdmission(entity, index));
+			issues.push(...validateClipPlacement(entity, index));
+		}
+		if (current.entityKind === "axvideo") issues.push(...validateAXVideoAdmission(entity, index));
+		if (current.entityKind === "caption") issues.push(...validateCaptionAsset(entity, index));
+		issues.push(...validateSequenceComposition(entity));
+	}
+	issues.push(...validateClipAnchorCycles(entities, index));
+	return issues;
+}
+function validateMarkerUse(marker, index) {
+	const relations = [...index.relationsOf(marker)];
+	const clipEdges = ofKind(relations, "clip-marker");
+	const axVideoEdges = ofKind(relations, "axvideo-marker");
+	const contentEdges = ofKind(relations, "marker-content");
+	const timelineEdges = ofKind(relations, "marker-timeline");
+	const issues = [];
+	if (clipEdges.length + axVideoEdges.length !== 1) issues.push({
+		code: "marker_container_xor",
+		entityId: marker.entityId,
+		message: "Sequence Marker must have exactly one Clip XOR AXVideo container relation"
+	});
+	if (contentEdges.length + timelineEdges.length !== 1) issues.push({
+		code: "marker_content_xor",
+		entityId: marker.entityId,
+		message: "Sequence Marker must have exactly one Sequence content XOR Timeline relation"
+	});
+	if (clipEdges.length === 1 && timelineEdges.length === 1 || axVideoEdges.length === 1 && contentEdges.length === 1) issues.push({
+		code: "marker_pair_mismatch",
+		entityId: marker.entityId,
+		message: "Only Clip+Content or AXVideo+Timeline Marker relation pairs are valid"
+	});
+	return issues;
+}
+function validateClipAdmission(clip, index) {
+	const markerEdges = ofKind([...index.relationsOf(clip)], "clip-marker");
+	if (markerEdges.length !== 1) return [{
+		code: "clip_marker_cardinality",
+		entityId: clip.entityId,
+		message: "Clip must have exactly one authoritative Clip-Marker Relation"
+	}];
+	const marker = markerEdges[0]?.other(clip)?.deref();
+	if (marker == null) return [{
+		code: "clip_content_cardinality",
+		entityId: clip.entityId,
+		message: "Clip must resolve one live Sequence Marker and one content Relation"
+	}];
+	const contentEdges = ofKind([...index.relationsOf(marker)], "marker-content");
+	if (contentEdges.length !== 1) return [{
+		code: "clip_content_cardinality",
+		entityId: clip.entityId,
+		message: "Clip Marker must resolve exactly one content Relation"
+	}];
+	const content = contentEdges[0]?.other(marker)?.deref()?.current();
+	if (content == null) return [{
+		code: "clip_content_cardinality",
+		entityId: clip.entityId,
+		message: "Clip Marker content Relation must resolve one live entity"
+	}];
+	if (!hasSequence(content)) return [{
+		code: "clip_content_not_sequence",
+		entityId: clip.entityId,
+		message: `Clip Marker resolves to non-Sequence entity "${content.entityId}"`
+	}];
+	return [];
+}
+function validateAXVideoAdmission(axVideo, index) {
+	const markerEdges = ofKind([...index.relationsOf(axVideo)], "axvideo-marker");
+	if (markerEdges.length === 1 && markerEdges[0]?.other(axVideo)?.deref() != null) return [];
+	return [{
+		code: "axvideo_marker_cardinality",
+		entityId: axVideo.entityId,
+		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"
+		}];
+	}
+	return [{
+		code: "caption_asset_required",
+		entityId: caption.entityId,
+		message: "Caption must have a Physical Asset Relation"
+	}];
+}
+function validateClipPlacement(clip, index) {
+	const marker = ofKind([...index.relationsOf(clip)], "clip-marker")[0]?.other(clip)?.deref();
+	if (marker?.current().entityKind !== "sequence-marker") return [];
+	const markerValue = marker.current();
+	const anchors = ofKind([...index.relationsOf(clip)], "clip-anchor").filter((relation) => relation.endpoints[0].deref() === clip);
+	const hasOrder = clip.current().order !== void 0;
+	const hasTarget = markerValue.targetRange !== void 0;
+	const hasAnchorOffset = markerValue.anchorOffset !== void 0;
+	const issues = [];
+	if (anchors.length > 1) issues.push({
+		code: "clip_anchor_cardinality",
+		entityId: clip.entityId,
+		message: "A Clip may follow at most one host Clip"
+	});
+	const hasAnchor = anchors.length === 1;
+	if (hasAnchor && (!hasAnchorOffset || hasOrder || hasTarget) || !hasAnchor && (hasAnchorOffset || Number(hasOrder) + Number(hasTarget) !== 1)) issues.push({
+		code: "clip_placement_invalid",
+		entityId: clip.entityId,
+		message: "Clip placement must be exactly one of Clip.order, Marker.targetRange, or clip-anchor with Marker.anchorOffset"
+	});
+	if (markerValue.durationPolicy === "timeline") {
+		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({
+			code: "timeline_duration_policy_invalid",
+			entityId: marker.entityId,
+			message: "Marker durationPolicy \"timeline\" is only valid for ordered Audio Clips on the bgm Track"
+		});
+	}
+	return issues;
+}
+function validateClipAnchorCycles(entities, index) {
+	const hostByChild = /* @__PURE__ */ new Map();
+	for (const entity of entities) {
+		if (entity.current().entityKind !== "clip") continue;
+		for (const relation of ofKind([...index.relationsOf(entity)], "clip-anchor")) {
+			if (relation.endpoints[0].deref() !== entity) continue;
+			const host = relation.endpoints[1].deref();
+			if (host != null) hostByChild.set(entity.entityId, host.entityId);
+		}
+	}
+	const issues = [];
+	for (const child of hostByChild.keys()) {
+		const seen = /* @__PURE__ */ new Set();
+		let current = child;
+		while (current !== void 0 && !seen.has(current)) {
+			seen.add(current);
+			current = hostByChild.get(current);
+		}
+		if (current === void 0) continue;
+		issues.push({
+			code: "clip_anchor_cycle",
+			entityId: child,
+			message: "clip-anchor Relations must form an acyclic dependency graph"
+		});
+	}
+	return issues;
+}
+function validateMarkerRanges(marker, compare) {
+	const current = marker.current();
+	const issues = [];
+	if (!(compare.source(current.sourceRange.start, current.sourceRange.end) < 0)) issues.push({
+		code: "marker_source_range_empty",
+		entityId: marker.entityId,
+		message: "Sequence Marker sourceRange must be a non-empty half-open interval"
+	});
+	if (current.targetRange != null && !(compare.target(current.targetRange.start, current.targetRange.end) < 0)) issues.push({
+		code: "marker_target_range_empty",
+		entityId: marker.entityId,
+		message: "Sequence Marker targetRange must be a non-empty half-open interval"
+	});
+	return issues;
+}
+function validateMarkerSourceBounds(marker, index, compare) {
+	const contentEdges = ofKind([...index.relationsOf(marker)], "marker-content");
+	if (contentEdges.length !== 1) return [];
+	const content = contentEdges[0]?.other(marker)?.deref()?.current();
+	if (content == null || !hasSequence(content)) return [];
+	const sourceRange = marker.current().sourceRange;
+	const startVsExtent = compare(sourceRange.start, content.extent.start);
+	const endVsExtent = content.extent.kind === "bounded" ? compare(sourceRange.end, content.extent.end) : void 0;
+	if (!Number.isNaN(startVsExtent) && startVsExtent >= 0 && (endVsExtent == null || !Number.isNaN(endVsExtent) && endVsExtent <= 0)) return [];
+	return [{
+		code: "marker_source_out_of_bounds",
+		entityId: marker.entityId,
+		message: `Sequence Marker sourceRange must stay within content "${content.entityId}" extent`
+	}];
+}
+function validateSequenceComposition(entity) {
+	const current = entity.current();
+	const expected = expectedSequenceShape(current.entityKind);
+	if (expected == null) return [];
+	if (hasSequence(current) && current.extent.kind === expected.extent && current.sampling === expected.sampling) return [];
+	return [{
+		code: "invalid_sequence_composition",
+		entityId: current.entityId,
+		message: `${current.entityKind} must compose ${expected.extent} / ${expected.sampling} Sequence semantics`
+	}];
+}
+function validateEntity(entity, entityIds = /* @__PURE__ */ new Set()) {
+	const current = entity.current();
+	const issues = [];
+	if (isReservedEntityKind(current.entityKind)) issues.push({
+		code: "forbidden_entity_kind",
+		entityId: current.entityId,
+		message: `Entity kind "${current.entityKind}" is explicitly outside the Medeo DSL`
+	});
+	for (const problem of validateKnownEntityPayload(current)) issues.push({
+		code: "invalid_entity_payload",
+		entityId: current.entityId,
+		message: `Entity "${current.entityKind}" ${problem}`
+	});
+	const peerIdPaths = [...collectPeerEntityIdPaths(current, current.entityKind), ...collectPeerEntityValuePaths(current, current.entityKind, current.entityId, entityIds)];
+	const uniquePeerIdPaths = [...new Set(peerIdPaths)].sort();
+	if (uniquePeerIdPaths.length > 0) issues.push({
+		code: "peer_entity_id_field",
+		entityId: current.entityId,
+		message: `Entity embeds forbidden peer-ID field/value path(s): ${uniquePeerIdPaths.join(", ")}`
+	});
+	return issues;
+}
+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");
+	switch (entity.entityKind) {
+		case "track":
+			validateOptionalField(value, "hidden", "boolean", problems);
+			validateOptionalField(value, "role", "string", problems);
+			validateOptionalFiniteNumber(value, "order", problems);
+			break;
+		case "video":
+		case "audio":
+		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);
+			break;
+		case "sequence-marker":
+			validateMarkerPayload(value, problems);
+			break;
+		case "audio-script":
+		case "phonetic-script":
+			validateScriptPayload(value, problems);
+			break;
+		case "timeline":
+		case "viewport": break;
+		case "clip":
+			validateOptionalFiniteNumber(value, "order", problems);
+			validateOptionalFiniteNumber(value, "volume", problems);
+			if (typeof value.volume === "number" && (value.volume < -60 || value.volume > 20)) problems.push("volume must be decibels between -60 and 20");
+			break;
+		case "asset":
+			validateAssetPayload(value, problems);
+			break;
+		default: break;
+	}
+	return problems;
+}
+function validateSequencePayload(value, expectedExtent, expectedSampling, problems) {
+	const extent = value.extent;
+	if (!isRecord(extent)) problems.push("extent must be an object");
+	else {
+		if (extent.kind !== expectedExtent) problems.push(`extent.kind must be "${expectedExtent}"`);
+		if (!Object.hasOwn(extent, "start") || extent.start === void 0) problems.push("extent.start is required");
+		if (expectedExtent === "bounded" && (!Object.hasOwn(extent, "end") || extent.end === void 0)) problems.push("extent.end is required for bounded sequences");
+		if (expectedExtent === "unbounded" && Object.hasOwn(extent, "end")) problems.push("extent.end is forbidden for unbounded sequences");
+	}
+	if (value.sampling !== expectedSampling) problems.push(`sampling must be "${expectedSampling}"`);
+	if (!Object.hasOwn(value, "coordinateSpace") || value.coordinateSpace === void 0) problems.push("coordinateSpace is required");
+}
+function validateMarkerPayload(value, problems) {
+	validateRange(value.sourceRange, "sourceRange", true, problems);
+	if (Object.hasOwn(value, "targetRange") && value.targetRange !== void 0) validateRange(value.targetRange, "targetRange", true, problems);
+	const duration = value.duration;
+	if (!isRecord(duration)) problems.push("duration must be an object");
+	else if (duration.mode === "fixed") {
+		if (!Object.hasOwn(duration, "value") || duration.value === void 0) problems.push("duration.value is required when duration.mode is \"fixed\"");
+	} 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");
+}
+function validateAssetPayload(value, problems) {
+	validateExternalLocator(value, problems);
+	validateStorageKey(value, problems);
+	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 (value.external !== void 0 && value.inline !== void 0) problems.push("Asset must not combine external and inline physical locations");
+}
+/**
+* Media variants own their Asset locator directly: `external` is required and
+* inline text stays an Asset-kind-only value so the two 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("inline is an Asset-kind field; media variants use external");
+}
+function validateExternalLocator(value, problems) {
+	const external = value.external;
+	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");
+}
+function validateVoicePayload(value, problems) {
+	const voice = value.voice;
+	if (voice === void 0) return;
+	if (!isRecord(voice)) {
+		problems.push("voice must be an object when present");
+		return;
+	}
+	if (voice.system !== "voice-library") problems.push("voice.system must be \"voice-library\"");
+	if (typeof voice.key !== "string" || voice.key.trim() === "") problems.push("voice.key must be a non-empty string");
+	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 style = value.style;
+	if (style === void 0) return;
+	if (!isRecord(style)) {
+		problems.push("style must be an object when present");
+		return;
+	}
+	const font = style.font;
+	if (font !== void 0) if (!isRecord(font)) problems.push("style.font must be an object when present");
+	else {
+		if (font.system !== "font-library") problems.push("style.font.system must be \"font-library\"");
+		if (typeof font.key !== "string" || font.key.trim() === "") problems.push("style.font.key must be a non-empty string");
+	}
+	for (const key of [
+		"fontSize",
+		"fontWeight",
+		"entranceAnimationDurationMs",
+		"strokeWidth",
+		"positionX",
+		"positionY"
+	]) validateOptionalFiniteNumber(style, key, problems, `style.${key}`);
+	for (const key of [
+		"fontColor",
+		"entranceAnimation",
+		"strokeColor"
+	]) if (style[key] !== void 0 && typeof style[key] !== "string") problems.push(`style.${key} must be a string`);
+}
+function validateRange(value, path, required, problems) {
+	if (!isRecord(value)) {
+		if (required) problems.push(`${path} must be an object`);
+		return;
+	}
+	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`);
+}
+function validateScriptPayload(value, problems) {
+	if (!Array.isArray(value.segments)) {
+		problems.push("segments must be an array");
+		return;
+	}
+	for (const [index, segment] of value.segments.entries()) {
+		if (!isRecord(segment)) {
+			problems.push(`segments[${index}] must be an object`);
+			continue;
+		}
+		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`);
+	}
+}
+function validateOptionalField(value, key, expectedType, problems) {
+	if (value[key] !== void 0 && typeof value[key] !== expectedType) problems.push(`${key} must be a ${expectedType} when present`);
+}
+function validateOptionalFiniteNumber(value, key, problems, label = key) {
+	if (value[key] !== void 0 && (typeof value[key] !== "number" || !Number.isFinite(value[key]))) problems.push(`${label} must be a finite number when present`);
+}
+function collectPeerEntityIdPaths(value, entityKind) {
+	const paths = [];
+	visitPeerEntityIdPaths(value, entityKind, "", /* @__PURE__ */ new Set(), paths);
+	return paths;
+}
+function visitPeerEntityIdPaths(value, entityKind, parentPath, ancestors, paths) {
+	if (typeof value !== "object" || value == null) return;
+	if (ancestors.has(value)) return;
+	ancestors.add(value);
+	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 === "entityId") && !isOwnedLocalIdPath(entityKind, path) && isEntityIdFieldName(key)) paths.push(path);
+		visitPeerEntityIdPaths(child, entityKind, path, ancestors, paths);
+	}
+	ancestors.delete(value);
+}
+function collectPeerEntityValuePaths(value, entityKind, ownEntityId, entityIds) {
+	const paths = [];
+	visitPeerEntityValues(value, entityKind, ownEntityId, entityIds, "", /* @__PURE__ */ new Set(), paths);
+	return paths;
+}
+function visitPeerEntityValues(value, entityKind, ownEntityId, entityIds, path, ancestors, paths) {
+	if (typeof value === "string") {
+		if (value !== ownEntityId && entityIds.has(value) && !isOwnedLocalEntityValuePath(entityKind, path)) paths.push(path);
+		return;
+	}
+	if (typeof value !== "object" || value == null || ancestors.has(value)) return;
+	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;
+		visitPeerEntityValues(child, entityKind, ownEntityId, entityIds, path.length === 0 ? key : `${path}.${key}`, ancestors, paths);
+	}
+	ancestors.delete(value);
+}
+function isOwnedLocalEntityValuePath(entityKind, path) {
+	if (entityKind === "track" && path === "role") return true;
+	if ([
+		"video",
+		"audio",
+		"voice",
+		"image",
+		"caption",
+		"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 (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;
+	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 (entityKind === "asset" && /^(?:tracks\[\d+\]\.trackId|renditions\[\d+\]\.renditionId)$/.test(path)) return true;
+	return false;
+}
+function isEntityIdFieldName(key) {
+	return key.endsWith("Id") || key.endsWith("Ids") || key.endsWith("ID") || key.endsWith("IDs") || /_ids?$/i.test(key);
+}
+function isRecord(value) {
+	return typeof value === "object" && value != null && !Array.isArray(value);
+}
+function collectRelatedEntities(entityRefs, index) {
+	const byId = /* @__PURE__ */ new Map();
+	const queue = [...entityRefs];
+	const issues = [];
+	while (queue.length > 0) {
+		const entity = queue.shift();
+		if (entity == null) continue;
+		const existing = byId.get(entity.entityId);
+		if (existing != null) {
+			if (existing !== entity) issues.push({
+				code: "duplicate_entity_id",
+				entityId: entity.entityId,
+				message: `Entity id "${entity.entityId}" has more than one live EntityRef`
+			});
+			continue;
+		}
+		byId.set(entity.entityId, entity);
+		for (const relation of index.relationsOf(entity)) for (const endpoint of relation.endpoints) {
+			const ref = endpoint.deref();
+			if (ref != null && !byId.has(ref.entityId)) queue.push(ref);
+		}
+	}
+	return {
+		entities: [...byId.values()],
+		issues
+	};
+}
+function expectedSequenceShape(kind) {
+	if (kind === "video" || kind === "audio" || kind === "voice" || kind === "caption") return {
+		extent: "bounded",
+		sampling: "native"
+	};
+	if (kind === "image") return {
+		extent: "unbounded",
+		sampling: "constant"
+	};
+	if (kind === "axvideo") return {
+		extent: "bounded",
+		sampling: "derived"
+	};
+}
+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");
+const clipMarkerRelationSpec = emptySpec("clip-marker", "clip", "sequence-marker");
+const axVideoMarkerRelationSpec = emptySpec("axvideo-marker", "axvideo", "sequence-marker");
+const markerTimelineRelationSpec = emptySpec("marker-timeline", "sequence-marker", "timeline");
+const markerContentRelationSpec = Object.freeze({
+	kind: "marker-content",
+	validateEndpoints: (endpoints) => hasMarkerAndSequence(endpoints),
+	validateMetadata: isEmptyMetadata
+});
+const physicalAssetRelationSpec = Object.freeze({
+	kind: "physical-asset",
+	validateEndpoints: (endpoints) => hasAssetAndSequence(endpoints),
+	validateMetadata: isAssetBinding
+});
+/** `generated(output, input)` means endpoint 0 was generated from endpoint 1. */
+const generatedRelationSpec = Object.freeze({
+	kind: "generated",
+	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"])),
+	validateMetadata: isCaptionAlignmentMetadata
+});
+/** `clip-anchor(child, host)` means endpoint 0 follows endpoint 1. */
+const clipAnchorRelationSpec = Object.freeze({
+	kind: "clip-anchor",
+	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";
+	},
+	validateMetadata: isEmptyMetadata
+});
+/** Built-in kinds are reserved; callers may add specs only under new names. */
+const builtInRelationSpecs = Object.freeze([
+	timelineTrackRelationSpec,
+	trackClipRelationSpec,
+	clipMarkerRelationSpec,
+	markerContentRelationSpec,
+	axVideoMarkerRelationSpec,
+	markerTimelineRelationSpec,
+	physicalAssetRelationSpec,
+	generatedRelationSpec,
+	phoneticScriptProvenanceRelationSpec,
+	captionProvenanceRelationSpec,
+	captionAlignmentRelationSpec,
+	clipAnchorRelationSpec,
+	audioScriptRenderRelationSpec
+]);
+function emptySpec(kind, a, b) {
+	return metadataSpec(kind, a, b, isEmptyMetadata);
+}
+function metadataSpec(kind, a, b, validateMetadata) {
+	return Object.freeze({
+		kind,
+		validateEndpoints: (endpoints) => hasKinds(endpoints, new Set([a]), new Set([b])),
+		validateMetadata
+	});
+}
+function hasKinds(endpoints, aKinds, bKinds) {
+	const first = endpoints[0].current().entityKind;
+	const second = endpoints[1].current().entityKind;
+	return aKinds.has(first) && bKinds.has(second) || aKinds.has(second) && bKinds.has(first);
+}
+function hasMarkerAndSequence(endpoints) {
+	const first = endpoints[0].current();
+	const second = endpoints[1].current();
+	return first.entityKind === "sequence-marker" && hasSequence(second) || second.entityKind === "sequence-marker" && hasSequence(first);
+}
+function hasAssetAndSequence(endpoints) {
+	const first = endpoints[0].current();
+	const second = endpoints[1].current();
+	return first.entityKind === "asset" && hasSequence(second) || second.entityKind === "asset" && hasSequence(first);
+}
+function isGeneratedMedia(entity) {
+	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio" || entity.entityKind === "voice";
+}
+function isEmptyMetadata(value) {
+	return isJsonObject(value) && Object.keys(value).length === 0;
+}
+function isAssetBinding(value) {
+	if (!isJsonObject(value)) return false;
+	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");
+}
+//#endregion
+//#region ../medeo-dsl/src/relations.ts
+function createEntityRef(entity) {
+	return {
+		entityId: entity.entityId,
+		current: () => entity
+	};
+}
+//#endregion
+//#region ../medeo-dsl/src/relation-index.ts
+var RelationEdge = class {
+	relationId;
+	kind;
+	metadata;
+	trace;
+	endpoints;
+	constructor(relationId, kind, endpoints, metadata, trace) {
+		this.relationId = relationId;
+		this.kind = kind;
+		this.metadata = metadata;
+		this.trace = trace;
+		this.endpoints = [new WeakRef(endpoints[0]), new WeakRef(endpoints[1])];
+	}
+	other(entity) {
+		const first = this.endpoints[0].deref();
+		const second = this.endpoints[1].deref();
+		if (first === entity) return this.endpoints[1];
+		if (second === entity) return this.endpoints[0];
+	}
+	toRow() {
+		const first = this.endpoints[0].deref();
+		const second = this.endpoints[1].deref();
+		if (first == null || second == null) return void 0;
+		return {
+			relationId: this.relationId,
+			endpoint0EntityId: first.entityId,
+			endpoint1EntityId: second.entityId,
+			relationKind: this.kind,
+			metadata: this.metadata,
+			trace: this.trace
+		};
+	}
+	isStale() {
+		return this.endpoints[0].deref() == null || this.endpoints[1].deref() == null;
+	}
+};
+/** Endpoint-agnostic secondary index. Relation rows remain the persistence authority. */
+var BiRelationIndex = class {
+	byEntity = /* @__PURE__ */ new WeakMap();
+	canonicalRefs = /* @__PURE__ */ new Map();
+	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`);
+		return this.linkValidated(input);
+	}
+	/** Author `generated(output, input)` without exposing positional arguments. */
+	linkGenerated(input) {
+		return this.linkValidated({
+			relationId: input.relationId,
+			spec: generatedRelationSpec,
+			endpoints: [input.output, input.input],
+			metadata: {},
+			trace: input.trace
+		});
+	}
+	/** Author `clip-anchor(child, host)` without exposing positional arguments. */
+	linkClipAnchor(input) {
+		return this.linkValidated({
+			relationId: input.relationId,
+			spec: clipAnchorRelationSpec,
+			endpoints: [input.child, input.host],
+			metadata: {},
+			trace: input.trace
+		});
+	}
+	/** Author `audio-script-render(output, script)` without exposing positional arguments. */
+	linkAudioScriptRender(input) {
+		return this.linkValidated({
+			relationId: input.relationId,
+			spec: audioScriptRenderRelationSpec,
+			endpoints: [input.output, input.script],
+			metadata: {},
+			trace: input.trace
+		});
+	}
+	/**
+	* Rehydrate a persisted row after resolving its spec and endpoint refs.
+	*
+	* This is a storage-boundary escape hatch, not an authoring API: persisted
+	* positions already are the semantic assertion made by their relation kind.
+	*/
+	linkRuntime(input) {
+		return this.linkValidated(input);
+	}
+	linkValidated(input) {
+		const [first, second] = input.endpoints;
+		if (first.entityId === second.entityId) throw new Error("A Relation cannot connect an entity to itself");
+		this.assertRelationIdAvailable(input.relationId);
+		const builtInSpec = builtInSpecByKind.get(input.spec.kind);
+		if (builtInSpec != null && builtInSpec !== input.spec) throw new Error(`Relation kind "${input.spec.kind}" must use its built-in specification`);
+		if (isForbiddenAuthoritativeRelation(input.spec.kind, input.endpoints)) throw new Error("A direct Clip-Content Relation is derived-only and cannot be authoritative");
+		if (!input.spec.validateEndpoints(input.endpoints)) throw new Error(`Relation "${input.spec.kind}" received invalid endpoints`);
+		if (!input.spec.validateMetadata(input.metadata)) throw new Error(`Relation "${input.spec.kind}" received invalid metadata`);
+		this.assertCanonicalRefAvailable(first);
+		this.assertCanonicalRefAvailable(second);
+		const relation = new RelationEdge(input.relationId, input.spec.kind, input.endpoints, input.metadata, input.trace ?? {});
+		this.rememberCanonicalRef(first);
+		this.rememberCanonicalRef(second);
+		this.add(first, relation);
+		this.add(second, relation);
+		this.byRelationId.set(input.relationId, new WeakRef(relation));
+		return relation;
+	}
+	relationsOf(entity) {
+		this.registerCanonicalRef(entity);
+		const relations = this.byEntity.get(entity);
+		if (relations == null) return /* @__PURE__ */ new Set();
+		for (const relation of relations) if (relation instanceof RelationEdge && relation.isStale()) this.unlink(relation);
+		return new Set(relations);
+	}
+	unlink(relation) {
+		for (const endpoint of relation.endpoints) {
+			const ref = endpoint.deref();
+			if (ref != null) this.byEntity.get(ref)?.delete(relation);
+		}
+		if (this.byRelationId.get(relation.relationId)?.deref() === relation) this.byRelationId.delete(relation.relationId);
+	}
+	add(entity, relation) {
+		const relations = this.byEntity.get(entity) ?? /* @__PURE__ */ new Set();
+		relations.add(relation);
+		this.byEntity.set(entity, relations);
+	}
+	registerCanonicalRef(entity) {
+		this.assertCanonicalRefAvailable(entity);
+		this.rememberCanonicalRef(entity);
+	}
+	assertCanonicalRefAvailable(entity) {
+		const existing = this.canonicalRefs.get(entity.entityId)?.deref();
+		if (existing != null && existing !== entity) throw new Error(`Entity "${entity.entityId}" already has a live canonical EntityRef`);
+	}
+	rememberCanonicalRef(entity) {
+		this.canonicalRefs.set(entity.entityId, new WeakRef(entity));
+	}
+	assertRelationIdAvailable(relationId) {
+		if (this.byRelationId.get(relationId)?.deref() != null) throw new Error(`Relation id "${relationId}" already exists`);
+		this.byRelationId.delete(relationId);
+	}
+};
+const builtInSpecByKind = new Map(builtInRelationSpecs.map((spec) => [spec.kind, spec]));
+function isForbiddenAuthoritativeRelation(kind, endpoints) {
+	if (kind === "clip-content") return true;
+	const first = endpoints[0].current();
+	const second = endpoints[1].current();
+	return first.entityKind === "clip" && hasSequence(second) || second.entityKind === "clip" && hasSequence(first);
+}
+//#endregion
+//#region ../medeo-dsl/src/entity-relation-rows.ts
+var InvalidEntityRelationRowsError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`Invalid Medeo entity/relation rows:\n- ${issues.join("\n- ")}`);
+		this.issues = issues;
+		this.name = "InvalidEntityRelationRowsError";
+	}
+};
+/** Decodes database rows into flat entities and validates the complete relation set. */
+function decodeEntityRelationRows(rows, options) {
+	const issues = [];
+	const entitiesById = /* @__PURE__ */ new Map();
+	const extensionEntityKinds = new Set(options.entityKinds ?? []);
+	for (const row of rows.entities) {
+		const entity = decodeEntityRow(row, extensionEntityKinds, issues);
+		if (entity == null) continue;
+		const ref = createEntityRef(entity);
+		if (entitiesById.has(ref.entityId)) {
+			issues.push(`duplicate entity id "${ref.entityId}"`);
+			continue;
+		}
+		entitiesById.set(ref.entityId, ref);
+	}
+	const specsByKind = collectRelationSpecs(options.relationSpecs ?? [], issues);
+	const relationIndex = new BiRelationIndex();
+	const relations = [];
+	const relationIds = /* @__PURE__ */ new Set();
+	for (const row of rows.relations) {
+		let relationId;
+		try {
+			relationId = createRelationId(row.relationId);
+		} catch (error) {
+			issues.push(errorMessage(error));
+			continue;
+		}
+		if (relationIds.has(relationId)) {
+			issues.push(`duplicate relation id "${relationId}"`);
+			continue;
+		}
+		relationIds.add(relationId);
+		if (!isTrimmedNonEmpty(row.relationKind)) {
+			issues.push(`relation "${relationId}" has an empty or untrimmed kind`);
+			continue;
+		}
+		const spec = specsByKind.get(row.relationKind);
+		if (spec == null) {
+			issues.push(`relation "${relationId}" has no registered spec for kind "${row.relationKind}"`);
+			continue;
+		}
+		let endpoint0EntityId;
+		let endpoint1EntityId;
+		try {
+			endpoint0EntityId = createEntityId(row.endpoint0EntityId);
+			endpoint1EntityId = createEntityId(row.endpoint1EntityId);
+		} catch (error) {
+			issues.push(errorMessage(error));
+			continue;
+		}
+		const endpoint0 = entitiesById.get(endpoint0EntityId);
+		const endpoint1 = entitiesById.get(endpoint1EntityId);
+		if (endpoint0 == null || endpoint1 == null) {
+			const missing = [endpoint0 == null ? endpoint0EntityId : void 0, endpoint1 == null ? endpoint1EntityId : void 0].filter((value) => value != null).join(", ");
+			issues.push(`relation "${relationId}" references missing entity id(s): ${missing}`);
+			continue;
+		}
+		if (!isJsonObject(row.metadata) || !isJsonObject(row.trace)) {
+			issues.push(`relation "${relationId}" metadata and trace must contain only JSON values`);
+			continue;
+		}
+		try {
+			relations.push(relationIndex.linkRuntime({
+				relationId,
+				spec,
+				endpoints: [endpoint0, endpoint1],
+				metadata: row.metadata,
+				trace: row.trace
+			}));
+		} catch (error) {
+			issues.push(errorMessage(error));
+		}
+	}
+	if (issues.length === 0) for (const issue of validateEntityRelationSet([...entitiesById.values()], relationIndex, options)) issues.push(`${issue.code}: ${issue.message}`);
+	if (issues.length > 0) throw new InvalidEntityRelationRowsError(issues);
+	return {
+		entitiesById,
+		relationIndex,
+		relations
+	};
+}
+function decodeEntityRow(row, extensionEntityKinds, issues) {
+	let entityId;
+	try {
+		entityId = createEntityId(row.entityId);
+	} catch (error) {
+		issues.push(errorMessage(error));
+		return;
+	}
+	if (!isTrimmedNonEmpty(row.entityKind)) {
+		issues.push(`entity "${entityId}" has an empty or untrimmed kind`);
+		return;
+	}
+	if (isReservedEntityKind(row.entityKind)) {
+		issues.push(`entity "${entityId}" uses reserved kind "${row.entityKind}"`);
+		return;
+	}
+	if (!isKnownEntityKind(row.entityKind) && !extensionEntityKinds.has(row.entityKind)) {
+		issues.push(`entity "${entityId}" has unregistered extension kind "${row.entityKind}"`);
+		return;
+	}
+	if (!isJsonObject(row.payload)) {
+		issues.push(`entity "${entityId}" payload must contain only JSON values`);
+		return;
+	}
+	const reserved = ["entityId", "entityKind"].filter((key) => Object.hasOwn(row.payload, key));
+	if (reserved.length > 0) {
+		issues.push(`entity "${entityId}" payload contains reserved field(s): ${reserved.join(", ")}`);
+		return;
+	}
+	return {
+		...row.payload,
+		entityId,
+		entityKind: row.entityKind
+	};
+}
+function collectRelationSpecs(extensionSpecs, issues) {
+	const specs = /* @__PURE__ */ new Map();
+	for (const spec of builtInRelationSpecs) specs.set(spec.kind, spec);
+	for (const spec of extensionSpecs) {
+		if (!isTrimmedNonEmpty(spec.kind)) {
+			issues.push("extension relation spec has an empty or untrimmed kind");
+			continue;
+		}
+		if (specs.has(spec.kind)) {
+			issues.push(`relation spec kind "${spec.kind}" is already registered`);
+			continue;
+		}
+		specs.set(spec.kind, spec);
+	}
+	return specs;
+}
+function isTrimmedNonEmpty(value) {
+	return value.length > 0 && value.trim() === value;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/document/entity-projection-values.ts
+/** A graph cannot be represented faithfully by the compatibility reader. */
+var EntityTimelineProjectionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EntityTimelineProjectionError";
+	}
+};
+function fail(message) {
+	throw new EntityTimelineProjectionError(message);
+}
+function object(value) {
+	return value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function finite(value, label) {
+	if (typeof value !== "number" || !Number.isFinite(value)) fail(`${label} must be finite`);
+	return value;
+}
+function positive(value, label) {
+	const result = finite(value, label);
+	if (result <= 0) fail(`${label} must be positive`);
+	return result;
+}
+function milliseconds(value, label) {
+	const result = finite(value, label);
+	if (!Number.isSafeInteger(result) || result < 0) fail(`${label} must be non-negative whole milliseconds`);
+	return result;
+}
+function range(value, label) {
+	if (!object(value)) fail(`${label} must be a numeric range`);
+	const start = finite(value.start, `${label}.start`);
+	const end = finite(value.end, `${label}.end`);
+	if (start >= end) fail(`${label} must be non-empty`);
+	return {
+		start,
+		end
+	};
+}
+//#endregion
+//#region src/document/entity-timeline-layout.ts
+/** Validated graph lookup shared by the compatibility layout and projection. */
+var EntityProjectionGraph = class {
+	rows;
+	entities;
+	timeline;
+	constructor(rows) {
+		this.rows = rows;
+		decodeEntityRelationRows(rows, { compareMarkerPoints: (_marker, _range, left, right) => finite(left, "range point") - finite(right, "range point") });
+		this.entities = new Map(rows.entities.map((row) => [String(row.entityId), row]));
+		const roots = rows.entities.filter((row) => row.entityKind === "timeline");
+		if (roots.length !== 1) fail("compatibility projection requires exactly one Timeline");
+		this.timeline = roots[0];
+	}
+	entity(id, kind) {
+		const row = this.entities.get(id);
+		if (row === void 0 || kind !== void 0 && row.entityKind !== kind) fail(`Expected ${kind ?? "Entity"} ${id}`);
+		return row;
+	}
+	adjacent(id, kind) {
+		return [...new Set(this.rows.relations.filter((row) => row.relationKind === kind && (row.endpoint0EntityId === id || row.endpoint1EntityId === id)).map((row) => row.endpoint0EntityId === id ? row.endpoint1EntityId : row.endpoint0EntityId))].map((entityId) => this.entity(entityId));
+	}
+	one(id, relation, kind) {
+		const values = this.adjacent(id, relation);
+		if (values.length !== 1 || kind !== void 0 && values[0]?.entityKind !== kind) fail(`entity ${id} requires exactly one ${relation}${kind === void 0 ? "" : ` to ${kind}`}`);
+		return values[0];
+	}
+};
+const roleOrder = {
+	caption: 0,
+	video_clip: 1,
+	speech: 2,
+	bgm: 3
+};
+/**
+* Resolve only entity-owned placement facts. This does not choose new anchors,
+* manufacture clips, or mutate a graph while reading. Write-side operations
+* must express any detach/reparent/overlap decision in their entity plan.
+*/
+function resolveEntityTimelineLayout(rows) {
+	return resolveGraphLayout(new EntityProjectionGraph(rows));
+}
+function resolveGraphLayout(graph) {
+	const facts = /* @__PURE__ */ new Map();
+	const seenRoles = /* @__PURE__ */ new Set();
+	const tracks = graph.adjacent(graph.timeline.entityId, "timeline-track").map((track) => {
+		const role = track.payload.role;
+		if (track.entityKind !== "track" || typeof role !== "string" || !Object.hasOwn(roleOrder, role)) fail(`unsupported compatibility Track role on ${track.entityId}`);
+		if (seenRoles.has(role)) fail(`The compatibility editor supports only one ${role} Track`);
+		seenRoles.add(role);
+		const typedRole = role;
+		if (track.payload.hidden !== void 0 && typeof track.payload.hidden !== "boolean") fail("Track hidden must be boolean");
+		const order = track.payload.order === void 0 ? roleOrder[typedRole] : finite(track.payload.order, "Track order");
+		const trackFacts = graph.adjacent(track.entityId, "track-clip").map((clip) => {
+			if (clip.entityKind !== "clip" || graph.adjacent(clip.entityId, "track-clip").length !== 1) fail(`Clip ${clip.entityId} must belong to exactly one Track`);
+			const marker = graph.one(clip.entityId, "clip-marker", "sequence-marker");
+			const content = graph.one(marker.entityId, "marker-content");
+			if (!(typedRole === "video_clip" ? ["image", "video"] : typedRole === "speech" ? ["voice"] : typedRole === "caption" ? ["caption"] : ["audio"]).includes(content.entityKind)) fail(`unsupported compatibility content kind ${content.entityKind} on ${typedRole} Track`);
+			const space = content.payload.coordinateSpace;
+			if (space !== "ms" && space !== "milliseconds" && (!object(space) || space.unit !== "ms" && space.unit !== "milliseconds")) fail(`media ${content.entityId} must state millisecond coordinates for this reader`);
+			const source = range(marker.payload.sourceRange, "sourceRange");
+			const durationFact = marker.payload.duration;
+			if (!object(durationFact)) fail(`Marker ${marker.entityId} requires duration`);
+			const duration = positive(durationFact.mode === "from-source" ? source.end - source.start : durationFact.value, "duration");
+			if (!Number.isSafeInteger(duration)) fail("Compatibility duration must be whole milliseconds");
+			const fillTimeline = marker.payload.durationPolicy === "timeline";
+			if (marker.payload.durationPolicy !== void 0 && (!fillTimeline || typedRole !== "bgm")) fail("durationPolicy is only supported for timeline-filling background Audio");
+			const anchors = graph.rows.relations.filter((row) => row.relationKind === "clip-anchor" && row.endpoint0EntityId === clip.entityId);
+			if (anchors.length > 1) fail(`Clip ${clip.entityId} has multiple anchors`);
+			const target = marker.payload.targetRange === void 0 ? void 0 : range(marker.payload.targetRange, "targetRange");
+			const anchorId = anchors[0]?.endpoint1EntityId;
+			let mode;
+			let absoluteStart;
+			let anchorOffset;
+			let clipOrder;
+			if (anchorId !== void 0) {
+				if (target !== void 0) fail(`Anchored Marker ${marker.entityId} cannot also have targetRange`);
+				mode = "anchored";
+				anchorOffset = milliseconds(marker.payload.anchorOffset, "anchorOffset");
+			} else {
+				if (marker.payload.anchorOffset !== void 0) fail(`Marker ${marker.entityId} has anchorOffset without a clip-anchor Relation`);
+				if (target !== void 0) {
+					mode = "absolute";
+					absoluteStart = milliseconds(target.start, "target start");
+					milliseconds(target.end, "target end");
+					if (Math.abs(target.end - target.start - duration) > 1e-6) fail(`Marker ${marker.entityId} targetRange must match its effective duration`);
+				} else {
+					mode = "sequential";
+					if (clip.payload.order === void 0) fail(`Clip ${clip.entityId} has no placement: targetRange or explicit order is required`);
+					clipOrder = finite(clip.payload.order, "Clip order");
+				}
+			}
+			const fact = {
+				clip,
+				marker,
+				content,
+				trackId: track.entityId,
+				role: typedRole,
+				duration,
+				mode,
+				order: clipOrder,
+				absoluteStart,
+				anchorId,
+				anchorOffset,
+				fillTimeline
+			};
+			facts.set(clip.entityId, fact);
+			return fact;
+		});
+		if (typedRole === "bgm" && trackFacts.length > 1) fail("The compatibility editor supports only one background Audio Clip");
+		const sequential = trackFacts.filter((fact) => fact.mode === "sequential").sort((left, right) => left.order - right.order);
+		if (new Set(sequential.map((fact) => fact.order)).size !== sequential.length) fail("sequential Clips must have distinct order values");
+		sequential.forEach((fact, index) => {
+			fact.predecessor = sequential[index - 1]?.clip.entityId;
+		});
+		return {
+			entityId: String(track.entityId),
+			role: typedRole,
+			order,
+			hidden: track.payload.hidden === true,
+			trackFacts
+		};
+	});
+	tracks.sort((left, right) => left.order - right.order || left.entityId.localeCompare(right.entityId));
+	const resolved = /* @__PURE__ */ new Map();
+	const visiting = /* @__PURE__ */ new Set();
+	const resolve = (id) => {
+		const cached = resolved.get(id);
+		if (cached !== void 0) return cached;
+		if (visiting.has(id)) fail(`Cyclic Clip placement dependency at ${id}`);
+		visiting.add(id);
+		const fact = facts.get(id);
+		if (fact === void 0) fail(`Placement refers to unplaced Clip ${id}`);
+		let start = fact.absoluteStart ?? 0;
+		if (fact.mode === "anchored") {
+			const host = resolve(fact.anchorId);
+			if (fact.role === "speech" && facts.get(host.clipEntityId).role !== "video_clip") fail("An anchored Voice must use a visual Clip as its host");
+			start = host.start + fact.anchorOffset;
+		} else if (fact.predecessor !== void 0) {
+			const prior = resolve(fact.predecessor);
+			start = prior.start + prior.duration;
+		}
+		milliseconds(start + fact.duration, "Clip end");
+		const result = {
+			clipEntityId: id,
+			markerEntityId: fact.marker.entityId,
+			contentEntityId: fact.content.entityId,
+			trackEntityId: fact.trackId,
+			start: milliseconds(start, "Clip start"),
+			duration: fact.duration,
+			mode: fact.mode,
+			...fact.anchorId === void 0 ? {} : {
+				anchorClipEntityId: fact.anchorId,
+				anchorOffset: fact.anchorOffset
+			}
+		};
+		visiting.delete(id);
+		resolved.set(id, result);
+		return result;
+	};
+	for (const id of facts.keys()) resolve(id);
+	const durationMs = Math.max(0, ...[...resolved.values()].filter((clip) => facts.get(clip.clipEntityId).role !== "bgm").map((clip) => clip.start + clip.duration));
+	for (const [id, fact] of facts) if (fact.fillTimeline) {
+		const clip = resolved.get(id);
+		if (clip.start !== 0) fail("Timeline-filling BGM must start at zero");
+		resolved.set(id, {
+			...clip,
+			duration: durationMs
+		});
+	}
+	return {
+		durationMs,
+		clips: resolved,
+		tracks: tracks.map(({ trackFacts, ...track }) => ({
+			...track,
+			clips: trackFacts.map((fact) => resolved.get(fact.clip.entityId)).sort((left, right) => left.start - right.start || left.clipEntityId.localeCompare(right.clipEntityId))
+		}))
+	};
+}
+//#endregion
+//#region src/document/entity-projection.ts
+/**
+* One-way compatibility view over the Entity graph. A legacy part is never
+* consulted as an editing fact. Peer IDs appear only in this derived read
+* contract, reconstructed from relations; they are not stored in payloads.
+*/
+function projectEntityTimeline(rows, meta) {
+	const graph = new EntityProjectionGraph(rows);
+	const layout = resolveGraphLayout(graph);
+	for (const track of layout.tracks) {
+		if (track.role !== "video_clip") continue;
+		for (let index = 1; index < track.clips.length; index += 1) {
+			const previous = track.clips[index - 1];
+			if (track.clips[index].start < previous.start + previous.duration) fail("Overlapping visual Clips require an explicit overlay adapter; the current editor supports one visual lane");
+		}
+	}
+	const parts = {};
+	for (const track of layout.tracks) for (const placement of track.clips) {
+		const clip = graph.entity(placement.clipEntityId, "clip");
+		const marker = graph.entity(placement.markerEntityId, "sequence-marker");
+		const content = graph.entity(placement.contentEntityId);
+		const volume = volumeSchema.safeParse(clip.payload.volume ?? 0);
+		if (!volume.success) fail("Clip volume must be decibels between -60 and 20");
+		if (track.role === "video_clip") {
+			const asset = mediaAssetFacts(graph, content);
+			const source = range(marker.payload.sourceRange, "sourceRange");
+			const external = externalLocator(asset, "memota");
+			const speed = videoSpeed(content, marker, placement);
+			parts[clip.entityId] = { video_clip: {
+				id: clip.entityId,
+				kind: "video_clip",
+				origin_media_id: external.key,
+				play_in: content.entityKind === "image" && speed === void 0 ? 0 : source.start,
+				play_out: content.entityKind === "image" && speed === void 0 ? placement.duration : source.end,
+				volume: volume.data,
+				...speed === void 0 ? {} : { speed_shift: speed }
+			} };
+		} else if (track.role === "speech") {
+			const asset = mediaAssetFacts(graph, content);
+			requireUntrimmedAudio(content, marker, placement);
+			const external = externalLocator(asset, "memota-speech");
+			const script = graph.one(content.entityId, "audio-script-render", "audio-script");
+			const voice = content.payload.voice;
+			if (voice !== void 0 && (!object(voice) || voice.system !== "voice-library" || typeof voice.key !== "string")) fail("Voice must use an explicit voice-library locator");
+			const captionIds = layout.tracks.flatMap((candidate) => candidate.role === "caption" ? candidate.clips.filter((caption) => caption.anchorClipEntityId === clip.entityId).map((caption) => caption.clipEntityId) : []);
+			parts[clip.entityId] = { speech: {
+				id: clip.entityId,
+				kind: "speech",
+				media_duration_ms: placement.duration,
+				audio_storage_key: storageKey(asset),
+				origin_speech_id: external.key,
+				audio_script: scriptText(script),
+				volume: volume.data,
+				voice: object(voice) ? {
+					id: typeof voice.key === "string" ? voice.key : void 0,
+					name: typeof voice.name === "string" ? voice.name : void 0
+				} : void 0,
+				caption_ids: captionIds
+			} };
+		} else if (track.role === "caption") {
+			const text = content.payload.text;
+			if (typeof text !== "string") fail("Caption " + content.entityId + " requires its text");
+			const asset = graph.one(content.entityId, "physical-asset", "asset");
+			const inline = asset.payload.inline;
+			if (inline !== void 0 && (!object(inline) || inline.mediaType !== "text/plain" || inline.text !== text)) fail("Inline Caption Asset and Caption text must agree");
+			if (inline === void 0 && !object(asset.payload.external)) fail("Caption Asset must identify physical text or contain actual inline text");
+			if (placement.anchorClipEntityId === void 0) fail("Caption placement requires an explicit voice Clip anchor");
+			const anchor = layout.clips.get(placement.anchorClipEntityId);
+			if (anchor === void 0 || graph.entity(anchor.contentEntityId).entityKind !== "voice") fail("Caption anchor must resolve a placed Voice");
+			if (graph.one(content.entityId, "caption-alignment").entityId !== anchor.contentEntityId) fail("Caption alignment must agree with its placed Voice");
+			const script = graph.one(content.entityId, "caption-provenance", "audio-script");
+			if (graph.one(anchor.contentEntityId, "audio-script-render", "audio-script").entityId !== script.entityId) fail("Caption provenance must agree with the Voice AudioScript");
+			if (marker.payload.timeRemapping !== void 0) fail("Caption timeRemapping is not supported by this reader");
+			const style = captionStyle(content.payload.style);
+			parts[clip.entityId] = { caption: {
+				id: clip.entityId,
+				kind: "caption",
+				text,
+				speech_part_id: placement.anchorClipEntityId,
+				start_ms: placement.anchorOffset,
+				initial_duration_ms: placement.duration,
+				...style === void 0 ? {} : { style }
+			} };
+		} else {
+			const asset = mediaAssetFacts(graph, content);
+			const external = externalLocator(asset, "memota");
+			if (marker.payload.durationPolicy !== "timeline") fail("Background Audio requires an explicit timeline-fill durationPolicy");
+			if (marker.payload.timeRemapping !== void 0) fail("BGM timeRemapping is not supported by this reader");
+			const source = range(marker.payload.sourceRange, "sourceRange");
+			const extent = content.payload.extent;
+			if (!object(extent) || extent.start !== source.start || extent.end !== source.end) fail("Background Audio compatibility requires the complete source");
+			parts[clip.entityId] = { bgm: {
+				id: clip.entityId,
+				kind: "bgm",
+				audio_storage_key: storageKey(asset),
+				origin_media_id: external.key,
+				volume: volume.data
+			} };
+		}
+	}
+	const document = {
+		meta: {
+			...structuredClone(meta),
+			schema_version: ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION
+		},
+		timeline: graph.timeline.payload.unit_time_ms === void 0 ? void 0 : { unit_time_ms: positive(graph.timeline.payload.unit_time_ms, "unit_time_ms") },
+		tracks: layout.tracks.map((track) => ({
+			id: track.entityId,
+			parts_kind: track.role,
+			is_hidden: track.hidden,
+			items: track.clips.map((clip) => clip.mode === "anchored" ? {
+				part_id: clip.clipEntityId,
+				time_position: {
+					mode: "anchored",
+					anchorPartId: clip.anchorClipEntityId,
+					offsetMs: clip.anchorOffset
+				},
+				fallback_abs_ms: clip.start
+			} : {
+				part_id: clip.clipEntityId,
+				time_position: {
+					mode: "absolute",
+					offsetMs: clip.start
+				}
+			})
+		})),
+		part_library: parts
+	};
+	assertValidVideoDocument(document);
+	return document;
+}
+/**
+* Media facts are read from the variant itself: a media variant owns its
+* Asset identity and carries `external`/`storageKey` directly. Dual-entity
+* media graphs are rejected instead of being resolved through a legacy
+* `physical-asset` binding.
+*/
+function mediaAssetFacts(graph, content) {
+	if (graph.adjacent(content.entityId, "physical-asset").length > 0) fail("Media " + content.entityId + " owns its Asset identity; remove its physical-asset Relation");
+	if (!object(content.payload.external)) fail("Media " + content.entityId + " must carry its own Asset external identity");
+	return {
+		entityId: String(content.entityId),
+		payload: content.payload
+	};
+}
+function externalLocator(asset, system) {
+	const value = asset.payload.external;
+	if (!object(value) || value.system !== system || typeof value.key !== "string" || value.key.trim() === "") fail("Asset " + asset.entityId + " requires an explicit " + system + " external key");
+	return { key: value.key };
+}
+function storageKey(asset) {
+	if (typeof asset.payload.storageKey !== "string" || asset.payload.storageKey.trim() === "") fail("Asset " + asset.entityId + " requires its factual storageKey");
+	return asset.payload.storageKey;
+}
+function scriptText(script) {
+	const segments = script.payload.segments;
+	if (!Array.isArray(segments)) fail("AudioScript requires segments");
+	return segments.map((segment) => {
+		if (!object(segment) || typeof segment.text !== "string") fail("AudioScript segment requires text");
+		return segment.text;
+	}).join("");
+}
+function captionStyle(value) {
+	if (value === void 0) return void 0;
+	if (!object(value)) fail("Caption style must be an object");
+	const { font, ...owned } = structuredClone(value);
+	const fields = {
+		fontSize: "font_size",
+		fontColor: "font_color",
+		fontWeight: "font_weight",
+		entranceAnimation: "entrance_animation",
+		entranceAnimationDurationMs: "entrance_animation_duration_ms",
+		strokeColor: "stroke_color",
+		strokeWidth: "stroke_width",
+		positionX: "position_x",
+		positionY: "position_y"
+	};
+	const style = {};
+	for (const [key, field] of Object.entries(owned)) {
+		if (!Object.hasOwn(fields, key)) fail("Unsupported Caption style field " + key);
+		style[fields[key]] = field;
+	}
+	if (font !== void 0) {
+		if (!object(font) || font.system !== "font-library" || typeof font.key !== "string") fail("Caption font requires a font-library locator");
+		return {
+			...style,
+			font_id: font.key
+		};
+	}
+	return style;
+}
+function requireUntrimmedAudio(content, marker, placement) {
+	const source = range(marker.payload.sourceRange, "sourceRange");
+	const extent = content.payload.extent;
+	if (!object(extent) || extent.start !== source.start || extent.end !== source.end || placement.duration !== source.end - source.start || marker.payload.timeRemapping !== void 0) fail("Voice compatibility requires the complete, unremapped take");
+}
+function videoSpeed(content, marker, placement) {
+	const remapping = marker.payload.timeRemapping;
+	if (content.entityKind === "image" && remapping === void 0) return void 0;
+	const source = range(marker.payload.sourceRange, "sourceRange");
+	if (remapping !== void 0) {
+		if (!object(remapping) || remapping.kind !== "linear") fail("unsupported timeRemapping on " + marker.entityId);
+		if (Object.keys(remapping).some((key) => key !== "kind" && key !== "rate" && key !== "mode")) fail("Unsupported linear timeRemapping fields");
+		const rate = positive(remapping.rate, "linear remapping rate");
+		if (Math.round((source.end - source.start) / rate) !== placement.duration) fail("timeRemapping on " + marker.entityId + " must agree with Marker duration");
+		if (remapping.mode !== void 0 && typeof remapping.mode !== "string") fail("Linear remapping mode must be a string");
+		return {
+			category: "linear",
+			mode: typeof remapping.mode === "string" ? remapping.mode : "constant",
+			config: { linear: { speed: rate } }
+		};
+	}
+	const rate = (source.end - source.start) / placement.duration;
+	return rate === 1 ? void 0 : {
+		category: "linear",
+		mode: "constant",
+		config: { linear: { speed: rate } }
+	};
+}
+//#endregion
 //#region src/document/mirror-read.ts
 /**
 * Project the mirror state (`VideoDocumentDraft`) into the authoritative
@@ -1510,7 +2972,7 @@ function readVideoDocumentFromDraft(draft) {
 	const meta = draft.meta;
 	return {
 		meta: {
-			schema_version: VIDEO_DOCUMENT_SCHEMA_VERSION,
+			schema_version: meta?.schema_version === "video-document/entity-projection-v1" ? ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION : VIDEO_DOCUMENT_SCHEMA_VERSION,
 			draft_id: emptyToUndefined(meta?.draft_id),
 			project_id: emptyToUndefined(meta?.project_id),
 			owner_id: emptyToUndefined(meta?.owner_id),
@@ -1591,6 +3053,7 @@ var MirrorVideoDocumentAdapter = class {
 	* skips the commit — matching the prior "empty op leaves no audit" behavior.
 	*/
 	transact(edit, audit) {
+		if (this.snapshot().meta.schema_version === "video-document/entity-projection-v1") throw new Error("Entity timeline projections are read-only; edit the Medeo entities instead");
 		this.mirror.setState((draft) => {
 			edit(draft);
 		}, {
@@ -1621,6 +3084,33 @@ function createMirrorVideoDocument(document, options = {}) {
 function createMirrorVideoDocumentAdapter(document, options) {
 	return new MirrorVideoDocumentAdapter(createMirrorVideoDocument(document, options));
 }
+/** Host-only replacement of a derived view, retaining the existing Loro history. */
+function applyEntityTimelineProjection(doc, projection, entityRevision) {
+	if (projection.meta.schema_version !== "video-document/entity-projection-v1") throw new Error("Expected an entity timeline projection");
+	if (!Number.isSafeInteger(entityRevision) || entityRevision < 1) throw new Error("Expected a positive entity revision");
+	assertValidVideoDocument(projection);
+	const from = doc.oplogVersion();
+	new Mirror({
+		doc,
+		schema: videoDocumentMirrorSchema
+	}).setState((draft) => writeVideoDocumentToDraft(draft, {
+		...projection,
+		meta: {
+			...projection.meta,
+			version: entityRevision
+		}
+	}), {
+		origin: "mengine.entity_projection",
+		message: JSON.stringify({
+			semantic_op: "EntityTimelineProjection",
+			entity_revision: entityRevision
+		})
+	});
+	return doc.export({
+		mode: "update",
+		from
+	});
+}
 /** Write a whole `VideoDocument` into a draft (seed a fresh doc / plain-memory state). */
 function writeVideoDocumentToDraft(draft, document) {
 	draft.meta = {
@@ -1747,6 +3237,7 @@ var PlainMemoryAdapter = class {
 	* no structural change — skip journal, matching mirror "no change, no commit".
 	*/
 	transact(edit, audit) {
+		if (this.state.meta?.schema_version === "video-document/entity-projection-v1") throw new Error("Entity timeline projections are read-only; edit the Medeo entities instead");
 		this.pendingIds = [];
 		try {
 			const next = produce(this.state, edit);
@@ -1767,4 +3258,4 @@ function createPlainMemoryAdapter(document, options) {
 	return new PlainMemoryAdapter(document, options);
 }
 //#endregion
-export { resolveSpeechOverlapByShiftingVideos as A, partUnionToDraft as B, solveVideoDocument as C, reassignSpeechesToVideoClipsByTime as D, fillMainTrackTimeGaps as E, safeDurationMs as F, videoDocumentMirrorSchema as H, DEFAULT_UNIT_TIME_MS as I, VIDEO_DOCUMENT_SCHEMA_VERSION as L, TIMELINE_SKELETON_DURATION_MS as M, isEmptyVideoClip as N, recalculateTimelineDuration as O, partDurationMs as P, effectiveVideoClipDurationMs as R, laneTrackId as S, arrangeMainTrackSeamlessly as T, base64ToBytes as U, recordEntries as V, bytesToBase64 as W, partUnionSchema as _, createMirrorVideoDocument as a, ensureLaneTrack as b, readVideoDocumentFromDraft as c, derivePositionFromAbs as d, fromVideoDocument as f, validateVideoDocument as g, assertValidVideoDocument as h, MirrorVideoDocumentAdapter as i, syncAggregatedClipsTimePosition as j, resolveAllSpeechOverlaps as k, buildInitialVideoDocument as l, VideoDocumentValidationError as m, createPlainMemoryAdapter as n, createMirrorVideoDocumentAdapter as o, toVideoDocument as p, generatePartId as r, writeVideoDocumentToDraft as s, PlainMemoryAdapter as t, buildSpeechHostMap as u, videoDocumentSchema as v, cascadeAfterVideoClipChanges as w, findLaneTrack as x, LANE_KINDS_IN_STACK_ORDER as y, speedOf as z };
+export { videoDocumentMirrorSchema as $, ensureLaneTrack as A, resolveSpeechOverlapByShiftingVideos as B, toVideoDocument as C, partUnionSchema as D, validateVideoDocument as E, arrangeMainTrackSeamlessly as F, safeDurationMs as G, TIMELINE_SKELETON_DURATION_MS as H, fillMainTrackTimeGaps as I, VIDEO_DOCUMENT_SCHEMA_VERSION as J, DEFAULT_UNIT_TIME_MS as K, reassignSpeechesToVideoClipsByTime as L, laneTrackId as M, solveVideoDocument as N, videoDocumentSchema as O, cascadeAfterVideoClipChanges as P, recordEntries as Q, recalculateTimelineDuration as R, fromVideoDocument as S, assertValidVideoDocument as T, isEmptyVideoClip as U, syncAggregatedClipsTimePosition as V, partDurationMs as W, speedOf as X, effectiveVideoClipDurationMs as Y, partUnionToDraft as Z, hasSequence as _, applyEntityTimelineProjection as a, buildSpeechHostMap as b, writeVideoDocumentToDraft as c, resolveEntityTimelineLayout as d, base64ToBytes as et, EntityTimelineProjectionError as f, createRelationId as g, createEntityId as h, MirrorVideoDocumentAdapter as i, findLaneTrack as j, LANE_KINDS_IN_STACK_ORDER as k, readVideoDocumentFromDraft as l, isJsonObject as m, createPlainMemoryAdapter as n, createMirrorVideoDocument as o, decodeEntityRelationRows as p, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as q, generatePartId as r, createMirrorVideoDocumentAdapter as s, PlainMemoryAdapter as t, bytesToBase64 as tt, projectEntityTimeline as u, isMediaAssetVariantKind as v, VideoDocumentValidationError as w, derivePositionFromAbs as x, buildInitialVideoDocument as y, resolveAllSpeechOverlaps as z };