@mengine/medeo-client 2.0.1-alpha.27 → 2.0.1-alpha.29

package/dist/{document-BGYPKtJ3.js → document-B3RLmTzA.js}

@@ -1,9 +1,9 @@
 import { u as volumeSchema } from "./shared-iWnU2osE.js";
 import { Mirror, schema, validateSchema } from "loro-mirror";
 import { z } from "zod";
-import { LoroDoc, LoroMap, LoroMovableList, LoroText, UndoManager } from "loro-crdt";
 import { sha256 } from "@noble/hashes/sha2.js";
-import { bytesToHex } from "@noble/hashes/utils.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+import { LoroDoc, LoroMap, LoroMovableList, LoroText, UndoManager } from "loro-crdt";
 import { produce } from "immer";
 //#region src/client/base64.ts
 function bytesToBase64(bytes) {
@@ -1508,6 +1508,7 @@ const ENTITY_KINDS = Object.freeze({
 	]),
 	voice: Object.freeze(["Container", "IPBound"]),
 	"sequence-marker": Object.freeze([]),
+	script: Object.freeze(["SegmentText"]),
 	"audio-script": Object.freeze(["SegmentText", "MediaFile"]),
 	"phonetic-script": Object.freeze(["SegmentText", "MediaFile"]),
 	caption: Object.freeze([
@@ -1809,6 +1810,32 @@ function entityToRow(entity) {
 	};
 }
 //#endregion
+//#region ../medeo-dsl/src/script-content.ts
+/** Canonical text used to identify one immutable professional Script version. */
+function normalizeScriptText(text) {
+	return text.normalize("NFC").replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n").map((line) => line.trimEnd()).join("\n");
+}
+/** Preserve segment identity, boundaries and order while removing textual encoding noise. */
+function normalizeScriptSegments(segments) {
+	return segments.map(({ segmentId, text, language }) => ({
+		segmentId,
+		text: normalizeScriptText(text),
+		...language === void 0 ? {} : { language: language.normalize("NFC").trim() }
+	}));
+}
+/** Content identity: ordered canonical text with array boundaries, never local ids or language metadata. */
+function scriptContentHash(segments) {
+	return `sha256:${bytesToHex(sha256(utf8ToBytes(JSON.stringify(normalizeScriptSegments(segments).map((segment) => segment.text)))))}`;
+}
+//#endregion
+//#region ../medeo-dsl/src/script-revision.ts
+const HASH = /^sha256:[0-9a-f]{64}$/;
+function readScriptRevisionTrace(value) {
+	if (!isJsonObject(value)) return null;
+	if (Object.keys(value).length !== 4 || value.command !== "revise-script" || typeof value.editId !== "string" || value.editId.trim() !== value.editId || value.editId === "" || typeof value.sourceContentHash !== "string" || !HASH.test(value.sourceContentHash) || typeof value.resultContentHash !== "string" || !HASH.test(value.resultContentHash)) return null;
+	return value;
+}
+//#endregion
 //#region ../medeo-dsl/src/invariants.ts
 /** An entity is made from at most one Asset; two would leave its bytes ambiguous. */
 /** Validates one complete set of entities and its authoritative Relation rows. */
@@ -1848,6 +1875,38 @@ function validateEntityRelationSet(entityRefs, index) {
 		issues.push(...validateSequenceComposition(entity));
 	}
 	issues.push(...validateClipAnchorCycles(entities, index));
+	issues.push(...validateScriptRevisionRelations(entities, index));
+	return issues;
+}
+function validateScriptRevisionRelations(entities, index) {
+	const byId = new Map(entities.map((entity) => [entity.entityId, entity.current()]));
+	const seenRelations = /* @__PURE__ */ new Set();
+	const editIds = /* @__PURE__ */ new Set();
+	const parentCounts = /* @__PURE__ */ new Map();
+	const issues = [];
+	for (const entity of entities) for (const relation of index.relationsOf(entity)) {
+		const row = relation.toRow();
+		if (row == null || seenRelations.has(row.relationId)) continue;
+		seenRelations.add(row.relationId);
+		const result = byId.get(row.endpoint0EntityId);
+		const source = byId.get(row.endpoint1EntityId);
+		if (row.relationKind !== "derived-from" || result?.entityKind !== "script" || source?.entityKind !== "script") continue;
+		const trace = readScriptRevisionTrace(row.trace);
+		const invalid = trace == null || trace.resultContentHash !== result.contentHash || trace.sourceContentHash !== source.contentHash || trace.resultContentHash === trace.sourceContentHash || trace != null && editIds.has(trace.editId);
+		if (trace != null) editIds.add(trace.editId);
+		const parentCount = (parentCounts.get(row.endpoint0EntityId) ?? 0) + 1;
+		parentCounts.set(row.endpoint0EntityId, parentCount);
+		if (invalid) issues.push({
+			code: "invalid_script_revision",
+			entityId: row.endpoint0EntityId,
+			message: "Script revision requires one canonical revise-script trace matching distinct result and source text"
+		});
+		if (parentCount > 1) issues.push({
+			code: "invalid_script_revision",
+			entityId: row.endpoint0EntityId,
+			message: "A Script revision may name exactly one source Script"
+		});
+	}
 	return issues;
 }
 function validateMarkerUse(marker, index) {
@@ -2068,7 +2127,7 @@ 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") {
+	if (entity.entityKind === "script" || entity.entityKind === "audio-script" || entity.entityKind === "phonetic-script") {
 		for (const key of [
 			"durationMs",
 			"extent",
@@ -2109,6 +2168,9 @@ function validateKnownEntityPayload(entity) {
 		case "audio-script":
 			validateScriptPayload(value, problems);
 			break;
+		case "script":
+			validateProfessionalScriptPayload(value, problems);
+			break;
 		case "phonetic-script":
 			validatePhoneticScriptPayload(value, problems);
 			break;
@@ -2284,6 +2346,24 @@ function validateScriptPayload(value, problems) {
 		if (segment.language !== void 0 && typeof segment.language !== "string") problems.push(`segments[${index}].language must be a string when present`);
 	}
 }
+function validateProfessionalScriptPayload(value, problems) {
+	validateScriptPayload(value, problems);
+	if (!Array.isArray(value.segments) || !value.segments.every(isCompleteScriptSegment)) return;
+	const segments = value.segments;
+	if (segments.length === 0) problems.push("segments must contain at least one screenplay segment");
+	const ids = segments.map((segment) => segment.segmentId);
+	if (ids.some((id) => id.trim() === "")) problems.push("segmentId must be a non-empty trimmed string");
+	if (ids.some((id) => id.trim() !== id)) problems.push("segmentId must be a non-empty trimmed string");
+	if (new Set(ids).size !== ids.length) problems.push("segmentId must be unique within the Script");
+	const normalized = normalizeScriptSegments(segments);
+	if (normalized.some((segment) => segment.text === "")) problems.push("segment text must be non-empty after normalization");
+	if (segments.some((segment, index) => segment.text !== normalized[index].text)) problems.push("segment text must use canonical NFC, LF line endings, and trimmed line endings");
+	if (segments.some((segment, index) => segment.language !== normalized[index].language)) problems.push("segment language must be canonical NFC and trimmed when present");
+	if (typeof value.contentHash !== "string" || value.contentHash !== scriptContentHash(segments)) problems.push("contentHash must equal the SHA-256 of the canonical ordered segment texts");
+}
+function isCompleteScriptSegment(value) {
+	return isRecord(value) && typeof value.segmentId === "string" && typeof value.text === "string" && (value.language === void 0 || typeof value.language === "string");
+}
 function validateOptionalField(value, key, expectedType, problems) {
 	if (value[key] !== void 0 && typeof value[key] !== expectedType) problems.push(`${key} must be a ${expectedType} when present`);
 }
@@ -2342,6 +2422,7 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 	if (entityKind === "voice" && /^voice\.(?:system|key|name)$/.test(path)) return true;
 	if (entityKind === "caption" && (path.startsWith("style.") || path === "selection.segmentId")) return true;
 	if ([
+		"script",
 		"audio-script",
 		"caption",
 		"phonetic-script"
@@ -2351,6 +2432,7 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 function isOwnedLocalIdPath(entityKind, path) {
 	if (path === "lifecycle.actorId") return true;
 	if ([
+		"script",
 		"audio-script",
 		"caption",
 		"phonetic-script"
@@ -2495,7 +2577,7 @@ const toAssetRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => hasExactlyOneAsset(endpoints),
 	validateMetadata: isAssetBinding
 });
-/** Media a generated medium can be made from, and a transcript can be read off. */
+/** Media lineage, speech inputs, transcription sources, and immutable script revisions. */
 const MEDIA_VARIANT_KINDS = [
 	"video",
 	"image",
@@ -2517,7 +2599,7 @@ const derivedFromRelationSpec = Object.freeze({
 	kind: "derived-from",
 	ordered: true,
 	sequenced: false,
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(MEDIA_VARIANT_KINDS), new Set(MEDIA_VARIANT_KINDS)) || hasKinds(endpoints, new Set(["voiceover-recording"]), new Set(["phonetic-script"])) || hasKinds(endpoints, new Set(["audio-script"]), new Set(MEDIA_AUDIBLE_KINDS)),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(MEDIA_VARIANT_KINDS), new Set(MEDIA_VARIANT_KINDS)) || hasKinds(endpoints, new Set(["voiceover-recording"]), new Set(["phonetic-script"])) || hasKinds(endpoints, new Set(["video"]), new Set(["script"])) || hasKinds(endpoints, new Set(["script"]), new Set(["script"])) || hasKinds(endpoints, new Set(["audio-script"]), new Set(MEDIA_AUDIBLE_KINDS)) || hasKinds(endpoints, new Set(["audio-script"]), new Set(["audio-script"])),
 	validateMetadata: isEmptyMetadata
 });
 const captionAlignmentRelationSpec = Object.freeze({
@@ -2652,6 +2734,7 @@ var BiRelationIndex = class {
 	}
 	/** Author `derived-from(product, source)` without exposing positional arguments. */
 	linkDerivedFrom(input) {
+		if (input.product.current().entityKind === "script" && input.source.current().entityKind === "script") throw new Error("Script revision provenance is host-authored by reviseScript");
 		return this.linkValidated({
 			relationId: input.relationId,
 			spec: derivedFromRelationSpec,
@@ -2887,6 +2970,63 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
+//#region ../medeo-dsl/src/relation-transition.ts
+var InvalidEntityRelationTransitionError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`Invalid Medeo relation transition:\n- ${issues.join("\n- ")}`);
+		this.issues = issues;
+		this.name = "InvalidEntityRelationTransitionError";
+	}
+};
+/** Enforce relation fact identity while admitting a complete candidate view. */
+function validateEntityRelationTransition(before, candidate) {
+	const issues = [];
+	const previous = new Map(before.relations.map((row) => [row.relationId, row]));
+	const beforeEntities = new Map(before.entities.map((row) => [row.entityId, row]));
+	const candidateEntities = new Map(candidate.entities.map((row) => [row.entityId, row]));
+	const revisionEditIds = new Set(before.relations.filter((relation) => isScriptRevision(relation, beforeEntities)).map((relation) => readScriptRevisionTrace(relation.trace)?.editId).filter((editId) => editId !== void 0));
+	const revisionParents = /* @__PURE__ */ new Map();
+	for (const entity of before.entities) if (entity.entityKind === "script" && !candidateEntities.has(entity.entityId)) issues.push(`Script entity "${entity.entityId}" is immutable history and cannot be deleted or replaced`);
+	for (const relation of candidate.relations) {
+		if (isScriptRevision(relation, candidateEntities)) {
+			const count = (revisionParents.get(relation.endpoint0EntityId) ?? 0) + 1;
+			revisionParents.set(relation.endpoint0EntityId, count);
+			if (count > 1) issues.push(`Script "${relation.endpoint0EntityId}" may name only one revision source`);
+		}
+		const original = previous.get(relation.relationId);
+		if (original == null) {
+			if (relation.relationKind === "caption-alignment") issues.push(`new caption-alignment relation "${relation.relationId}" is forbidden`);
+			if (isScriptRevision(relation, candidateEntities)) {
+				const trace = readScriptRevisionTrace(relation.trace);
+				const result = candidateEntities.get(relation.endpoint0EntityId);
+				const source = candidateEntities.get(relation.endpoint1EntityId);
+				if (trace == null || beforeEntities.has(relation.endpoint0EntityId) || !beforeEntities.has(relation.endpoint1EntityId) || trace.resultContentHash !== result.payload.contentHash || trace.sourceContentHash !== source.payload.contentHash || trace.resultContentHash === trace.sourceContentHash || revisionEditIds.has(trace.editId)) issues.push(`Script revision relation "${relation.relationId}" must be one canonical new-result to existing-source edit`);
+				else revisionEditIds.add(trace.editId);
+			}
+			continue;
+		}
+		if (original.relationKind !== relation.relationKind || original.endpoint0EntityId !== relation.endpoint0EntityId || original.endpoint1EntityId !== relation.endpoint1EntityId) {
+			issues.push(`relation "${relation.relationId}" changed its kind or ordered endpoints`);
+			continue;
+		}
+		if (!sameJson(original.metadata, relation.metadata)) issues.push(`relation "${relation.relationId}" changed semantic metadata without a new identity`);
+		if (relation.relationKind === "caption-alignment" && !sameJson(original.trace, relation.trace)) issues.push(`legacy caption-alignment relation "${relation.relationId}" may only be carried unchanged or deleted`);
+		if (isScriptRevision(relation, candidateEntities) && !sameJson(original.trace, relation.trace)) issues.push(`Script revision relation "${relation.relationId}" trace is immutable`);
+	}
+	if (issues.length > 0) throw new InvalidEntityRelationTransitionError(issues);
+}
+function isScriptRevision(relation, entities) {
+	return relation.relationKind === "derived-from" && entities.get(relation.endpoint0EntityId)?.entityKind === "script" && entities.get(relation.endpoint1EntityId)?.entityKind === "script";
+}
+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 leftKeys = Object.keys(left);
+	return leftKeys.length === Object.keys(right).length && leftKeys.every((key) => Object.hasOwn(right, key) && sameJson(left[key], right[key]));
+}
+//#endregion
 //#region src/document/entity-projection-values.ts
 /** A graph cannot be represented faithfully by the compatibility reader. */
 var EntityTimelineProjectionError = class extends Error {
@@ -3003,7 +3143,7 @@ function resolveGraphLayout(graph) {
 			const held = graph.holds(clip.entityId);
 			if (held.length !== 1) fail(`Clip ${clip.entityId} must contain exactly one content entity`);
 			const content = held[0];
-			const expected = typedRole === "video_clip" ? ["image", "video"] : typedRole === "speech" ? ["voiceover-recording"] : typedRole === "caption" ? ["caption"] : ["audio"];
+			const expected = typedRole === "video_clip" ? ["image", "video"] : typedRole === "speech" ? ["voiceover-recording", "audio"] : typedRole === "caption" ? ["caption"] : ["audio"];
 			if (!expected.includes(content.entityKind)) fail(`${typedRole} Track accepts ${expected.join(" or ")}, got ${content.entityKind}`);
 			const inMs = milliseconds(marker.payload.inMs, "inMs");
 			const outMs = milliseconds(marker.payload.outMs, "outMs");
@@ -3153,12 +3293,12 @@ function projectEntityTimeline(rows) {
 		} else if (track.role === "speech") {
 			const asset = mediaAssetFacts(graph, content);
 			requireUntrimmedAudio(content, marker, placement);
-			const external = externalLocator(asset, "memota-speech");
-			const renderEdges = graph.madeFrom(content.entityId, "derived-from");
+			const synthesized = content.entityKind === "voiceover-recording";
+			const external = externalLocator(asset, synthesized ? "memota-speech" : "memota");
 			const timbreEdges = graph.adjacent(content.entityId, "voice-timbre");
-			const assembled = renderEdges.length > 0 || timbreEdges.length > 0 ? assemblePhoneticScriptContent(rows, graph.one(content.entityId, "derived-from", "phonetic-script", renderEdges).entityId) : void 0;
+			const assembled = synthesized ? assemblePhoneticScriptContent(rows, synthesizedPhoneticScript(graph, content).entityId) : void 0;
+			const transcript = synthesized ? void 0 : transcribedAudioScript(graph, content);
 			if (timbreEdges.length > 1) fail("A voiceover resolves at most one Voice identity");
-			const transcripts = graph.madeInto(content.entityId, "derived-from");
 			const voice = timbreEdges.length === 0 ? void 0 : graph.one(content.entityId, "voice-timbre", "voice").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) : []);
@@ -3168,7 +3308,8 @@ function projectEntityTimeline(rows) {
 				media_duration_ms: placement.duration,
 				audio_storage_key: storageKey(asset),
 				origin_speech_id: external.key,
-				audio_script: assembled?.text ?? (transcripts.length > 0 ? assembleScriptText(graph.one(content.entityId, "derived-from", "audio-script", transcripts)) : ""),
+				...synthesized ? {} : { origin_asset_system: "memota" },
+				audio_script: assembled?.text ?? (transcript === void 0 ? "" : assembleScriptText(transcript)),
 				volume: volume.data,
 				voice: object(voice) ? {
 					id: typeof voice.key === "string" ? voice.key : void 0,
@@ -3287,7 +3428,17 @@ function captionStyle(value) {
 }
 function requireUntrimmedAudio(content, marker, placement) {
 	const source = markerWindow(marker);
-	if (source.start !== 0 || content.payload.durationMs !== source.end || placement.duration !== source.end || marker.payload.rate !== void 0) fail("Voiceover compatibility requires the complete, unremapped take");
+	if (source.start !== 0 || content.payload.durationMs !== source.end || placement.duration !== source.end || marker.payload.rate !== void 0) fail("Speech compatibility requires the complete, unremapped take");
+}
+function synthesizedPhoneticScript(graph, content) {
+	const scripts = graph.rows.relations.filter((row) => row.relationKind === "derived-from" && row.endpoint0EntityId === content.entityId).map((row) => graph.entity(row.endpoint1EntityId)).filter((row) => row.entityKind === "phonetic-script");
+	if (scripts.length !== 1) fail("Synthesized Speech requires exactly one ordered PhoneticScript input");
+	return scripts[0];
+}
+function transcribedAudioScript(graph, content) {
+	const scripts = graph.rows.relations.filter((row) => row.relationKind === "derived-from" && row.endpoint1EntityId === content.entityId).map((row) => graph.entity(row.endpoint0EntityId)).filter((row) => row.entityKind === "audio-script");
+	if (scripts.length > 1) fail("Recorded Speech has ambiguous AudioScript transcripts");
+	return scripts[0];
 }
 /** The Marker's window, in the {start,end} shape this compatibility reader speaks. */
 function markerWindow(marker) {
@@ -3696,6 +3847,19 @@ function writeEntityOrder(doc, group, roots, token) {
 //#region src/entity-crdt/entity-document.ts
 const LORO_ENTITY_SCHEMA = "medeo.entities.loro.v1";
 const MATERIALIZE_ORIGIN = "medeo.materialize";
+/** Read persisted relation roots before current entity versions are projected. */
+function readEntityRelationRecords(doc) {
+	if (root(doc).get("schema") !== "medeo.entities.loro.v1") throw new Error("Document has no Loro entity state");
+	return relationRecords(doc).map(({ rootId, identity, map, deleted }) => ({
+		relationId: createRelationId(rootId),
+		relationKind: identity.kind,
+		endpoint0EntityId: createEntityId(identity.endpoints[0]),
+		endpoint1EntityId: createEntityId(identity.endpoints[1]),
+		metadata: requireMap(map, "metadata").toJSON(),
+		trace: requireMap(map, "trace").toJSON(),
+		deleted
+	}));
+}
 function hash(value) {
 	return bytesToHex(sha256(new TextEncoder().encode(canonicalJson(value))));
 }
@@ -3782,35 +3946,31 @@ function readEntityDocument(doc, allowSelectionConflicts = false) {
 			}
 		};
 	});
-	const relations = [];
-	for (const key of section(doc, "relations").keys().sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
-		const map = section(doc, "relations").get(key);
-		if (!(map instanceof LoroMap) || map.get("deleted") === true) continue;
-		const original = map.get("identity");
-		if (original.endpoints.some((id) => !ids.has(family(doc, id)))) continue;
-		const endpoints = original.endpoints.map((id) => currentId(doc, id, ids));
-		const relationId = equalJson(endpoints, original.endpoints) ? key : `relation_${hash([key, endpoints])}`;
-		relations.push({
-			relationId: createRelationId(relationId),
-			relationKind: original.kind,
+	const relations = activeRelationRecords(doc, ids).map(({ rootId, identity, map }) => {
+		const endpoints = identity.endpoints.map((id) => currentId(doc, id, ids));
+		return {
+			relationId: createRelationId(equalJson(endpoints, identity.endpoints) ? rootId : `relation_${hash([rootId, endpoints])}`),
+			relationKind: identity.kind,
 			endpoint0EntityId: createEntityId(endpoints[0]),
 			endpoint1EntityId: createEntityId(endpoints[1]),
 			metadata: requireMap(map, "metadata").toJSON(),
 			trace: requireMap(map, "trace").toJSON()
-		});
-	}
+		};
+	});
 	sortSequencedRelations(doc, relations);
 	const project = {};
 	for (const [key, value] of Object.entries(section(doc, "attachments").toJSON())) {
 		if (typeof value !== "string") throw new Error(`Invalid project attachment ${key}`);
 		project[key] = currentId(doc, value, ids);
 	}
+	const phoneticScriptSelections = readPhoneticScriptSelections(doc, ids);
 	const state = {
 		rows: {
 			entities,
 			relations
 		},
-		project
+		project,
+		...phoneticScriptSelections === void 0 ? {} : { phoneticScriptSelections }
 	};
 	if (!allowSelectionConflicts) for (const [key, id] of ids) {
 		const fingerprint = selectionFingerprint(state.rows, id);
@@ -3818,6 +3978,54 @@ function readEntityDocument(doc, allowSelectionConflicts = false) {
 	}
 	return state;
 }
+function readPhoneticScriptSelections(doc, ids) {
+	const native = root(doc).get("phoneticScriptSelections");
+	if (native === void 0) return void 0;
+	if (!(native instanceof LoroMap)) throw new Error("Invalid phonetic-script selector");
+	const selections = {};
+	for (const clipRoot of native.keys().sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
+		const phoneticScriptRoot = native.get(clipRoot);
+		if (typeof phoneticScriptRoot !== "string") throw new Error("Invalid phonetic-script selection");
+		const clipId = ids.get(clipRoot);
+		const phoneticScriptId = ids.get(phoneticScriptRoot);
+		if (clipId === void 0 || phoneticScriptId === void 0) continue;
+		if (workspace(doc, clipRoot).get("kind") !== "clip") throw new Error("Phonetic-script selection target must be a Clip");
+		if (workspace(doc, phoneticScriptRoot).get("kind") !== "phonetic-script") throw new Error("Phonetic-script selection value must be a PhoneticScript");
+		selections[clipRoot] = phoneticScriptId;
+	}
+	return Object.keys(selections).length === 0 ? void 0 : selections;
+}
+function relationRecords(doc) {
+	const records = [];
+	for (const rootId of section(doc, "relations").keys().sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
+		const map = section(doc, "relations").get(rootId);
+		if (!(map instanceof LoroMap)) throw new Error(`Invalid relation record ${rootId}`);
+		const value = map.get("identity");
+		if (!isJsonObject(value) || typeof value.kind !== "string" || !Array.isArray(value.endpoints) || value.endpoints.length !== 2 || !value.endpoints.every((endpoint) => typeof endpoint === "string")) throw new Error(`Invalid relation identity ${rootId}`);
+		records.push({
+			rootId,
+			identity: {
+				kind: value.kind,
+				endpoints: [value.endpoints[0], value.endpoints[1]]
+			},
+			map,
+			deleted: map.get("deleted") === true
+		});
+	}
+	return records;
+}
+function activeRelationRecords(doc, ids) {
+	const selector = root(doc).get("clipContentSelections");
+	if (selector !== void 0 && !(selector instanceof LoroMap)) throw new Error("Invalid clip-content selector");
+	return relationRecords(doc).filter(({ rootId, identity, deleted }) => {
+		if (deleted) return false;
+		if (!identity.endpoints.every((id) => ids.has(family(doc, id)))) return false;
+		if (identity.kind !== "contain" || selector === void 0 || workspace(doc, family(doc, identity.endpoints[0])).get("kind") !== "clip") return true;
+		const selected = selector.get(family(doc, identity.endpoints[0]));
+		if (selected !== void 0 && typeof selected !== "string") throw new Error("Invalid clip-content selection");
+		return selected === void 0 || selected === rootId;
+	});
+}
 /** Native editing containers survive domain version changes and merge independently. */
 var LoroEntityDocument = class LoroEntityDocument {
 	doc;
@@ -3849,7 +4057,9 @@ var LoroEntityDocument = class LoroEntityDocument {
 			"relations",
 			"project",
 			"attachments",
-			"ordering"
+			"ordering",
+			"clipContentSelections",
+			"phoneticScriptSelections"
 		]) root(doc).ensureMergeableMap(name);
 		for (const row of rows.entities) apply(doc, {
 			type: "create",
@@ -3900,11 +4110,13 @@ var LoroEntityDocument = class LoroEntityDocument {
 	}
 	/** The callback and every domain validation execute on a causally complete fork first. */
 	transact(edit) {
+		const before = readEntityDocument(this.doc, true);
 		const probe = this.doc.fork();
 		const draft = new LoroEntityDraft(probe);
 		edit(draft);
 		draft.captureSelectionBaselines();
 		const state = readEntityDocument(probe);
+		validateEntityRelationTransition(before.rows, state.rows);
 		assertState(state);
 		this.validate?.(state);
 		materialize(probe);
@@ -3918,8 +4130,15 @@ var LoroEntityDocument = class LoroEntityDocument {
 			from
 		});
 	}
-	/** Import preserves native operation identities; projection errors never discard remote operations. */
+	/** Validate remote operations on a fork before importing their native identities. */
 	import(update) {
+		const before = readEntityDocument(this.doc, true);
+		const probe = this.doc.fork();
+		probe.import(update);
+		const candidate = readEntityDocument(probe, true);
+		validateEntityRelationTransition(before.rows, candidate.rows);
+		assertState(candidate);
+		this.validate?.(candidate);
 		this.doc.import(update);
 		const state = this.snapshot();
 		assertState(state);
@@ -4035,6 +4254,7 @@ var LoroEntityDraft = class {
 		});
 	}
 	delete(entityId) {
+		if (workspace(this.doc, family(this.doc, entityId)).get("kind") === "script") throw new Error("Script entities are immutable history and cannot be deleted");
 		this.record({
 			type: "delete",
 			root: family(this.doc, entityId)
@@ -4053,11 +4273,14 @@ var LoroEntityDraft = class {
 			row: clone(row)
 		});
 	}
-	patchRelation(relationId, metadata, trace) {
+	patchRelationTrace(relationId, trace) {
+		const relation = this.snapshot().rows.relations.find((row) => row.relationId === relationId);
+		if (relation == null) throw new Error(`Unknown relation ${relationId}`);
+		if (relation.relationKind === "caption-alignment") throw new Error("caption-alignment Relations are read-only legacy facts");
 		this.record({
 			type: "relation-fields",
 			root: this.relationRoot(relationId),
-			metadata: clone(metadata),
+			metadata: clone(relation.metadata),
 			trace: clone(trace)
 		});
 	}
@@ -4067,6 +4290,35 @@ var LoroEntityDraft = class {
 			root: this.relationRoot(relationId)
 		});
 	}
+	/** Select the one content membership projected for this stable Clip identity. */
+	selectClipContent(relationId) {
+		const relationRoot = this.relationRoot(relationId);
+		const map = section(this.doc, "relations").get(relationRoot);
+		if (!(map instanceof LoroMap)) throw new Error(`Unknown relation ${relationId}`);
+		const identity = map.get("identity");
+		if (!isJsonObject(identity) || identity.kind !== "contain" || !Array.isArray(identity.endpoints) || typeof identity.endpoints[0] !== "string") throw new Error("Clip-content selection requires a contain relation");
+		const clipRoot = family(this.doc, identity.endpoints[0]);
+		if (workspace(this.doc, clipRoot).get("kind") !== "clip") throw new Error("Clip-content selection requires a Clip container");
+		this.record({
+			type: "select-clip-content",
+			clipRoot,
+			relationRoot
+		});
+	}
+	/** Select the pending immutable pronunciation variant for one stable Speech Clip. */
+	selectPhoneticScript(clipEntityId, phoneticScriptEntityId) {
+		const clipRoot = family(this.doc, clipEntityId);
+		const phoneticScriptRoot = family(this.doc, phoneticScriptEntityId);
+		const clip = workspace(this.doc, clipRoot);
+		const phoneticScript = workspace(this.doc, phoneticScriptRoot);
+		if (clip.get("deleted") === true || clip.get("kind") !== "clip") throw new Error("Phonetic-script selection target must be an active Clip");
+		if (phoneticScript.get("deleted") === true || phoneticScript.get("kind") !== "phonetic-script") throw new Error("Phonetic-script selection value must be an active PhoneticScript");
+		this.record({
+			type: "select-phonetic-script",
+			clipRoot,
+			phoneticScriptRoot
+		});
+	}
 	relationRoot(relationId) {
 		const alias = this.relationAliases.get(relationId);
 		if (alias !== void 0) return alias;
@@ -4104,6 +4356,7 @@ var LoroEntityDraft = class {
 		});
 	}
 	replaceOwned(entityId, payload) {
+		this.assertGenericMutationAllowed(entityId);
 		this.record({
 			type: "write",
 			root: family(this.doc, entityId),
@@ -4114,6 +4367,7 @@ var LoroEntityDraft = class {
 	editText(entityId, path, start, deleteCount, text) {
 		if (typeof path[0] !== "string") throw new Error("Text path must start with a field");
 		const owner = resolveEntityFieldOwner(this.snapshot().rows, createEntityId(currentId(this.doc, entityId)), path[0]);
+		this.assertGenericMutationAllowed(owner);
 		this.record({
 			type: "text",
 			root: family(this.doc, owner),
@@ -4139,6 +4393,7 @@ var LoroEntityDraft = class {
 			const owner = resolveEntityFieldOwner(state.rows, id, change.path[0]);
 			const row = state.rows.entities.find((row) => row.entityId === owner);
 			if (equalJson(row.payload, applyFieldChanges(row.payload, [change]))) continue;
+			this.assertGenericMutationAllowed(owner);
 			this.record({
 				type: "field",
 				root: family(this.doc, owner),
@@ -4148,13 +4403,17 @@ var LoroEntityDraft = class {
 			});
 		}
 	}
+	assertGenericMutationAllowed(entityId) {
+		if (workspace(this.doc, family(this.doc, entityId)).get("kind") === "script") throw new Error("Script content is immutable; create a new Script revision");
+	}
 	changeRelation(relationId, changes) {
 		assertFieldChanges(changes);
 		const key = this.relationRoot(relationId);
 		const map = section(this.doc, "relations").get(key);
 		if (!(map instanceof LoroMap) || map.get("deleted") === true) throw new Error("Unknown relation");
+		if (map.get("identity").kind === "caption-alignment") throw new Error("caption-alignment Relations are read-only legacy facts");
 		for (const change of changes) {
-			if (!["metadata", "trace"].includes(change.path[0]) || change.path.length < 2) throw new Error("Relation changes may only edit metadata or trace fields");
+			if (change.path[0] !== "trace" || change.path.length < 2) throw new Error("Relation changes may only edit trace fields");
 			const payload = {
 				metadata: requireMap(map, "metadata").toJSON(),
 				trace: requireMap(map, "trace").toJSON()
@@ -4273,6 +4532,12 @@ function apply(doc, command) {
 			map.set("deleted", true);
 			break;
 		}
+		case "select-clip-content":
+			root(doc).ensureMergeableMap("clipContentSelections").set(command.clipRoot, command.relationRoot);
+			break;
+		case "select-phonetic-script":
+			root(doc).ensureMergeableMap("phoneticScriptSelections").set(command.clipRoot, command.phoneticScriptRoot);
+			break;
 		case "relation-fields": {
 			const map = section(doc, "relations").get(command.root);
 			if (!(map instanceof LoroMap)) throw new Error("Unknown relation");
@@ -4694,4 +4959,4 @@ function createPlainMemoryAdapter(document, options) {
 	return new PlainMemoryAdapter(document, options);
 }
 //#endregion
-export { assertValidVideoDocument as $, decodeEntityRelationRows as A, updateEntityFields as B, applyFieldChanges as C, speedOf as Ct, EntityProjectionGraph as D, base64ToBytes as Dt, projectEntityTimeline as E, videoDocumentMirrorSchema as Et, assembleEntityContent as F, hasSequence as G, isJsonObject as H, assemblePhoneticScriptContent as I, buildSpeechHostMap as J, isMediaAssetVariantKind as K, assembleScriptText as L, relationsTo as M, ScriptCompositionError as N, resolveEntityTimelineLayout as O, bytesToBase64 as Ot, assembleCaptionContent as P, VideoDocumentValidationError as Q, findComposedAudioScript as R, equalJson as S, effectiveVideoClipDurationMs as St, resolveFieldPath as T, recordEntries as Tt, createEntityId as U, variantBaseEntityIds as V, createRelationId as W, fromVideoDocument as X, derivePositionFromAbs as Y, toVideoDocument as Z, audioScriptAssetOf as _, TIMELINE_SKELETON_DURATION_MS as _t, createMirrorVideoDocument as a, findLaneTrack as at, phoneticScriptAssetOf as b, safeDurationMs as bt, DocumentMutationGuard as c, solveVideoDocument as ct, LoroEntityDraft as d, fillMainTrackTimeGaps as dt, validateVideoDocument as et, readEntityDocument as f, reassignSpeechesToVideoClipsByTime as ft, audioScriptAssetHash as g, syncAggregatedClipsTimePosition as gt, audioScriptAssetFields as h, resolveSpeechOverlapByShiftingVideos as ht, MirrorVideoDocumentAdapter as i, ensureLaneTrack as it, relationsFrom as j, EntityTimelineProjectionError as k, LORO_ENTITY_SCHEMA as l, cascadeAfterVideoClipChanges as lt, audioScriptAssetContent as m, resolveAllSpeechOverlaps as mt, createPlainMemoryAdapter as n, videoDocumentSchema as nt, createMirrorVideoDocumentAdapter as o, hasResolvedPlacement as ot, entityOrderGroups as p, recalculateTimelineDuration as pt, buildInitialVideoDocument as q, generatePartId as r, LANE_KINDS_IN_STACK_ORDER as rt, readVideoDocumentFromDraft as s, laneTrackId as st, PlainMemoryAdapter as t, partUnionSchema as tt, LoroEntityDocument as u, arrangeMainTrackSeamlessly as ut, phoneticScriptAssetContent as v, isEmptyVideoClip as vt, assertFieldChanges as w, partUnionToDraft as wt, scriptSourceAssetOf as x, DEFAULT_UNIT_TIME_MS as xt, phoneticScriptAssetHash as y, partDurationMs as yt, selectAudioScriptSegment as z };
+export { fromVideoDocument as $, resolveEntityTimelineLayout as A, base64ToBytes as At, assembleScriptText as B, canonicalJson as C, safeDurationMs as Ct, resolveFieldPath as D, partUnionToDraft as Dt, assertFieldChanges as E, speedOf as Et, relationsTo as F, isJsonObject as G, selectAudioScriptSegment as H, ScriptCompositionError as I, hasSequence as J, createEntityId as K, assembleCaptionContent as L, validateEntityRelationTransition as M, decodeEntityRelationRows as N, projectEntityTimeline as O, recordEntries as Ot, relationsFrom as P, derivePositionFromAbs as Q, assembleEntityContent as R, scriptSourceAssetOf as S, partDurationMs as St, applyFieldChanges as T, effectiveVideoClipDurationMs as Tt, updateEntityFields as U, findComposedAudioScript as V, variantBaseEntityIds as W, buildInitialVideoDocument as X, isMediaAssetVariantKind as Y, buildSpeechHostMap as Z, audioScriptAssetHash as _, resolveAllSpeechOverlaps as _t, createMirrorVideoDocument as a, videoDocumentSchema as at, phoneticScriptAssetHash as b, TIMELINE_SKELETON_DURATION_MS as bt, DocumentMutationGuard as c, findLaneTrack as ct, LoroEntityDraft as d, solveVideoDocument as dt, toVideoDocument as et, readEntityDocument as f, cascadeAfterVideoClipChanges as ft, audioScriptAssetFields as g, recalculateTimelineDuration as gt, audioScriptAssetContent as h, reassignSpeechesToVideoClipsByTime as ht, MirrorVideoDocumentAdapter as i, partUnionSchema as it, EntityTimelineProjectionError as j, bytesToBase64 as jt, EntityProjectionGraph as k, videoDocumentMirrorSchema as kt, LORO_ENTITY_SCHEMA as l, hasResolvedPlacement as lt, entityOrderGroups as m, fillMainTrackTimeGaps as mt, createPlainMemoryAdapter as n, assertValidVideoDocument as nt, createMirrorVideoDocumentAdapter as o, LANE_KINDS_IN_STACK_ORDER as ot, readEntityRelationRecords as p, arrangeMainTrackSeamlessly as pt, createRelationId as q, generatePartId as r, validateVideoDocument as rt, readVideoDocumentFromDraft as s, ensureLaneTrack as st, PlainMemoryAdapter as t, VideoDocumentValidationError as tt, LoroEntityDocument as u, laneTrackId as ut, audioScriptAssetOf as v, resolveSpeechOverlapByShiftingVideos as vt, equalJson as w, DEFAULT_UNIT_TIME_MS as wt, phoneticScriptAssetOf as x, isEmptyVideoClip as xt, phoneticScriptAssetContent as y, syncAggregatedClipsTimePosition as yt, assemblePhoneticScriptContent as z };