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

package/dist/{entity-sandbox-OArq9NSH.mjs → entity-sandbox-BTR2cRl1.mjs}

@@ -1,35 +1,94 @@
 import { applyFieldChanges, assertCanonicalEditorResources, assertFieldChanges, ensureEditorFoundation, importMediaAsset, readDocumentAudioScript } from "@mengine/medeo-client";
 //#region ../medeo-dsl/src/entities.ts
+/**
+* What every known entity kind declares.
+*
+* `kinds` is a multi-declaration: every entry holds at the same time, and each
+* is a property shared with other entity kinds — what the object *is* comes
+* from `entityKind` and is never repeated here. The order carries no priority,
+* endpoint role, or edit sequence — an operation asks whether the entity
+* declares the kind it needs, never what its "main type" is. An entity kind
+* that shares nothing declares nothing.
+*
+* `Caption` declares `Sequence` on purpose: it owns the display timing of the
+* one AudioScript segment it shows, which is what admits it into a Clip.
+* `Voice` declares no `Sequence` — it is a timbre identity, not playable
+* content; a rendered voiceover is an `audio` entity.
+*
+* No declaration says anything about resources: whether an entity has one, and
+* which, is the `from-asset` Relation's answer alone.
+*/
+const ENTITY_KINDS = Object.freeze({
+	axvideo: Object.freeze([
+		"Container",
+		"Sequence",
+		"Visual",
+		"Audible"
+	]),
+	timeline: Object.freeze(["Container"]),
+	track: Object.freeze(["Container"]),
+	clip: Object.freeze(["Container"]),
+	asset: Object.freeze([]),
+	video: Object.freeze([
+		"Sequence",
+		"Visual",
+		"Audible",
+		"FromAsset"
+	]),
+	audio: Object.freeze([
+		"Sequence",
+		"Audible",
+		"FromAsset"
+	]),
+	image: Object.freeze([
+		"Sequence",
+		"Visual",
+		"FromAsset"
+	]),
+	voice: Object.freeze(["Container", "IPBound"]),
+	"sequence-marker": Object.freeze([]),
+	viewport: Object.freeze([]),
+	"audio-script": Object.freeze(["SegmentText", "FromAsset"]),
+	"phonetic-script": Object.freeze(["SegmentText"]),
+	caption: Object.freeze([
+		"SegmentText",
+		"Sequence",
+		"FromAsset"
+	])
+});
+/** What a known kind declares; extension kinds declare nothing through this table. */
+function kindsOf(entityKind) {
+	return isKnownEntityKind(entityKind) ? ENTITY_KINDS[entityKind] : [];
+}
+function declaresKind(entityKind, kind) {
+	return kindsOf(entityKind).includes(kind);
+}
+/**
+* Sequence admission is a declaration, not a shape: a known kind is admitted
+* because its `kinds` say so, and a malformed payload is a separate, louder
+* failure than a silently non-Sequence entity. Extension kinds declare nothing
+* through the table and stay structurally detected.
+*/
 function hasSequence(entity) {
-	if (isKnownNonSequenceKind(entity.entityKind) || isReservedEntityKind(entity.entityKind)) return false;
+	if (isReservedEntityKind(entity.entityKind)) return false;
+	if (isKnownEntityKind(entity.entityKind)) return declaresKind(entity.entityKind, "Sequence");
 	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";
+	const duration = value.durationMs;
+	return duration === null || typeof duration === "number" && Number.isSafeInteger(duration) && duration > 0;
 }
 function isMediaAssetVariantKind(kind) {
-	return kind === "video" || kind === "image" || kind === "audio" || kind === "voice";
+	return kind === "video" || kind === "image" || kind === "audio";
 }
 function isKnownEntityKind(kind) {
-	return isKnownSequenceKind(kind) || isKnownNonSequenceKind(kind);
+	return Object.hasOwn(ENTITY_KINDS, 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);
 }
@@ -209,15 +268,18 @@ function assembleCaptionContent(rows, captionEntityId) {
 	requireEntityKind(rows, captionEntityId, "caption");
 	const caption = assembleEntityContent(rows, captionEntityId);
 	const script = findComposedAudioScript(rows, captionEntityId, "caption");
-	const segments = selectAudioScriptSegments({
+	const selection = captionSelection(caption);
+	const composed = {
 		...script,
 		payload: caption.payload
-	}, captionSelections(caption));
+	};
+	const segment = selectAudioScriptSegment(composed, selection);
 	return {
 		caption,
 		audioScript: script,
-		segments,
-		text: segments.map((segment) => segment.text).join("")
+		segments: [segment],
+		segmentIndex: scriptSegments(composed).findIndex((entry) => entry.segmentId === selection.segmentId),
+		text: segment.text
 	};
 }
 /**
@@ -239,20 +301,18 @@ function assemblePhoneticScriptContent(rows, phoneticScriptEntityId) {
 		text: segments.map((segment) => segment.text).join("")
 	};
 }
-function captionSelections(caption) {
-	const selections = caption.payload.selections;
-	if (!Array.isArray(selections) || selections.length === 0) throw new ScriptCompositionError("empty_selection", caption.entityId, `Caption "${caption.entityId}" requires a non-empty segment selection into its AudioScript`);
-	if (!selections.every(isSegmentSelection)) throw new ScriptCompositionError("invalid_selection", caption.entityId, "Caption selections require a segmentId and optional textRange");
-	return selections;
+function captionSelection(caption) {
+	if (Object.hasOwn(caption.payload, "selections") || !isSegmentSelection(caption.payload.selection)) throw new ScriptCompositionError("invalid_selection", caption.entityId, "Caption requires one selection object with segmentId and optional textRange; selections arrays are forbidden");
+	return caption.payload.selection;
 }
 function isSegmentSelection(value) {
 	return typeof value === "object" && value != null && !Array.isArray(value) && typeof value.segmentId === "string" && value.segmentId.trim() !== "" && Object.keys(value).every((key) => key === "segmentId" || key === "textRange");
 }
 /** Select source text without creating another authoritative text field. */
-function selectAudioScriptSegments(script, selections) {
-	if (!Array.isArray(selections) || selections.length === 0 || !selections.every(isSegmentSelection) || new Set(selections.map((s) => s.segmentId)).size !== selections.length) throw new ScriptCompositionError("invalid_selection", script.entityId, "Caption selections must be non-empty and name unique source segments");
+function selectAudioScriptSegment(script, selection) {
+	if (!isSegmentSelection(selection)) throw new ScriptCompositionError("invalid_selection", script.entityId, "Caption requires one selection object with segmentId and optional textRange");
 	const bySegmentId = new Map(scriptSegments(script).map((segment) => [segment.segmentId, segment]));
-	const selected = selections.map((selection) => {
+	const selected = (() => {
 		const segment = bySegmentId.get(selection.segmentId);
 		if (segment === void 0) throw new ScriptCompositionError("unknown_segment", script.entityId, `Caption selection "${selection.segmentId}" does not name a segment of AudioScript "${script.entityId}"`);
 		if (selection.textRange === void 0) return segment;
@@ -263,8 +323,8 @@ function selectAudioScriptSegments(script, selections) {
 			...segment,
 			text: points.slice(range.start, range.end).join("")
 		};
-	});
-	if (!selected.map((segment) => segment.text).join("").trim()) throw new ScriptCompositionError("empty_selection", script.entityId, "Caption selection must contain visible source text");
+	})();
+	if (!selected.text.trim()) throw new ScriptCompositionError("empty_selection", script.entityId, "Caption selection must contain visible source text");
 	return selected;
 }
 function requireEntityKind(rows, entityIdValue, entityKind) {
@@ -286,17 +346,15 @@ function entityToRow(entity) {
 }
 //#endregion
 //#region ../medeo-dsl/src/invariants.ts
-/**
-* Media variants own their Asset identity directly: a `physical-asset`
-* Relation may not bind them. Caption may associate with a physical text Asset
-* independently of its AudioScript composition.
-*/
-function validateMediaAssetIdentity(entity, index) {
-	return [...index.relationsOf(entity)].filter((relation) => relation.kind === "physical-asset").map(() => ({
-		code: "media_physical_asset_forbidden",
+/** An entity is made from at most one Asset; two would leave its bytes ambiguous. */
+function validateAssetSource(entity, index) {
+	if (entity.current().entityKind === "asset") return [];
+	if ([...index.relationsOf(entity)].filter((relation) => relation.kind === "from-asset").length <= 1) return [];
+	return [{
+		code: "asset_source_cardinality",
 		entityId: entity.entityId,
-		message: `Media entity "${entity.entityId}" owns its Asset identity; remove its physical-asset Relation`
-	}));
+		message: `Entity "${entity.entityId}" is made from more than one Asset`
+	}];
 }
 /** Validates one complete set of entities and its authoritative Relation rows. */
 function validateEntityRelationSet(entityRefs, index, options) {
@@ -319,7 +377,7 @@ function validateEntityRelationSet(entityRefs, index, options) {
 		const current = entity.current();
 		const entityIssues = validateEntity(entity, entityIds);
 		issues.push(...entityIssues);
-		if (isMediaAssetVariantKind(current.entityKind)) issues.push(...validateMediaAssetIdentity(entity, index));
+		issues.push(...validateAssetSource(entity, index));
 		if (entityIssues.some((issue) => issue.code === "invalid_entity_payload")) continue;
 		if (current.entityKind === "sequence-marker") {
 			const marker = entity;
@@ -544,24 +602,25 @@ function validateMarkerSourceBounds(marker, index, compare) {
 	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 [];
+	const startVsOrigin = compare(sourceRange.start, 0);
+	const endVsDuration = content.durationMs == null ? void 0 : compare(sourceRange.end, content.durationMs);
+	if (!Number.isNaN(startVsOrigin) && startVsOrigin >= 0 && (endVsDuration == null || !Number.isNaN(endVsDuration) && endVsDuration <= 0)) return [];
 	return [{
 		code: "marker_source_out_of_bounds",
 		entityId: marker.entityId,
-		message: `Sequence Marker sourceRange must stay within content "${content.entityId}" extent`
+		message: `Sequence Marker sourceRange must stay within content "${content.entityId}" duration`
 	}];
 }
 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 [];
+	const expected = expectedDurationShape(current.entityKind);
+	if (expected === void 0) return [];
+	const duration = current.durationMs;
+	if ((duration === null ? "none" : isPositiveInteger(duration) ? "own" : "invalid") === expected) return [];
 	return [{
 		code: "invalid_sequence_composition",
 		entityId: current.entityId,
-		message: `${current.entityKind} must compose ${expected.extent} / ${expected.sampling} Sequence semantics`
+		message: expected === "own" ? `${current.entityKind} must state its own durationMs in whole milliseconds` : `${current.entityKind} has no intrinsic length; durationMs must be null`
 	}];
 }
 function validateEntity(entity, entityIds = /* @__PURE__ */ new Set()) {
@@ -592,6 +651,7 @@ function validateKnownEntityPayload(entity) {
 	if (value.lifecycle !== void 0 && !isRecord(value.lifecycle)) problems.push("lifecycle must be an object when present");
 	if (entity.entityKind === "audio-script" || entity.entityKind === "phonetic-script") {
 		for (const key of [
+			"durationMs",
 			"extent",
 			"sampling",
 			"coordinateSpace",
@@ -600,7 +660,7 @@ function validateKnownEntityPayload(entity) {
 			"duration",
 			"startMs",
 			"endMs"
-		]) if (Object.hasOwn(value, key)) problems.push(`${key} is not intrinsic script data; assign an external annotation Marker`);
+		]) if (Object.hasOwn(value, key)) problems.push(`${key} is not intrinsic script data; assign an annotation Marker instead`);
 	}
 	switch (entity.entityKind) {
 		case "track":
@@ -610,19 +670,25 @@ function validateKnownEntityPayload(entity) {
 			break;
 		case "video":
 		case "audio":
-		case "voice":
+			validateDurationPayload(value, "own", problems);
+			break;
 		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);
+			validateDurationPayload(value, "own", problems);
+			validateCaptionPayload(value, problems);
+			break;
+		case "voice":
+			validateVoicePayload(value, problems);
 			break;
 		case "image":
-			validateSequencePayload(value, "unbounded", "constant", problems);
-			validateMediaAssetFields(value, problems);
+			validateDurationPayload(value, "none", problems);
 			break;
 		case "axvideo":
-			validateSequencePayload(value, "bounded", "derived", problems);
+			for (const retired of [
+				"extent",
+				"sampling",
+				"coordinateSpace",
+				"durationMs"
+			]) if (Object.hasOwn(value, retired)) problems.push(`${retired} is derived from the Timeline, not stored`);
 			break;
 		case "sequence-marker":
 			validateMarkerPayload(value, problems);
@@ -647,17 +713,27 @@ function validateKnownEntityPayload(entity) {
 	}
 	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");
+/**
+* Content states its own length and nothing else. The retired `extent` carried
+* a start as well, which had no meaning of its own and drifted into holding a
+* position; rejecting it keeps that mistake unwritable.
+*/
+function validateDurationPayload(value, expected, problems) {
+	for (const retired of [
+		"extent",
+		"sampling",
+		"coordinateSpace"
+	]) if (Object.hasOwn(value, retired)) problems.push(`${retired} is retired; state durationMs instead`);
+	if (!Object.hasOwn(value, "durationMs")) {
+		problems.push("durationMs is required");
+		return;
+	}
+	const duration = value.durationMs;
+	if (expected === "none") {
+		if (duration !== null) problems.push("durationMs must be null; this content has no intrinsic length");
+		return;
 	}
-	if (value.sampling !== expectedSampling) problems.push(`sampling must be "${expectedSampling}"`);
-	if (!Object.hasOwn(value, "coordinateSpace") || value.coordinateSpace === void 0) problems.push("coordinateSpace is required");
+	if (!isPositiveInteger(duration)) problems.push("durationMs must be positive whole milliseconds");
 }
 function validateMarkerPayload(value, problems) {
 	validateRange(value.sourceRange, "sourceRange", true, problems);
@@ -693,40 +769,38 @@ function validateSegmentRanges(value, problems) {
 		if (typeof entry.startMs === "number" && Number.isFinite(entry.startMs) && typeof entry.endMs === "number" && Number.isFinite(entry.endMs) && entry.startMs > entry.endMs) problems.push(`segmentRanges[${index}].startMs must not exceed segmentRanges[${index}].endMs`);
 	}
 }
+/** The Asset entity is the locator; it states where the bytes live and nothing else. */
 function validateAssetPayload(value, problems) {
-	validateExternalLocator(value, problems);
-	validateStorageKey(value, problems);
+	if (value.system !== "memota" && value.system !== "memota-speech") problems.push("system must be \"memota\" or \"memota-speech\"");
+	if (typeof value.key !== "string" || value.key.trim() === "") problems.push("key must be a non-empty string");
 	if (value.inline !== void 0) problems.push("inline is not a physical location; text is domain content owned by its AudioScript");
-}
-/**
-* Media variants own their Asset locator directly: `external` is required and
-* textual domain content is owned by AudioScript; the physical-location
-* vocabularies cannot mix.
-*/
-function validateMediaAssetFields(value, problems) {
-	if (value.external === void 0) problems.push("external is required; media variants own their Asset identity");
-	else validateExternalLocator(value, problems);
 	validateStorageKey(value, problems);
-	if (value.inline !== void 0) problems.push("media variants use external locators, not inline domain text");
-}
-function validateExternalLocator(value, problems) {
-	const external = value.external;
-	if (external === void 0) 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");
 }
+/**
+* Voice is a timbre identity, not playable content: it owns the voice-library
+* descriptor and nothing that would make it look like media or a Sequence. The
+* rendered voiceover is an `audio` entity bound by a `voice-timbre` Relation.
+*/
 function validateVoicePayload(value, problems) {
+	for (const key of [
+		"durationMs",
+		"extent",
+		"sampling",
+		"coordinateSpace",
+		"system",
+		"key",
+		"storageKey"
+	]) if (Object.hasOwn(value, key)) problems.push(`${key} belongs to the rendered Audio, not to the Voice identity`);
 	const voice = value.voice;
-	if (voice === void 0) return;
+	if (voice === void 0) {
+		problems.push("voice is required; a Voice entity is its voice-library identity");
+		return;
+	}
 	if (!isRecord(voice)) {
-		problems.push("voice must be an object when present");
+		problems.push("voice must be an object");
 		return;
 	}
 	if (voice.system !== "voice-library") problems.push("voice.system must be \"voice-library\"");
@@ -734,27 +808,16 @@ function validateVoicePayload(value, problems) {
 	if (voice.name !== void 0 && typeof voice.name !== "string") problems.push("voice.name must be a string when present");
 }
 function validateCaptionPayload(value, problems) {
-	validateExternalLocator(value, problems);
 	if (value.segmentRanges !== void 0) validateSegmentRanges(value.segmentRanges, problems);
-	const selections = value.selections;
-	if (!Array.isArray(selections)) problems.push("selections must be a non-empty array of AudioScript segment selections");
+	if (Object.hasOwn(value, "selections")) problems.push("selections is forbidden; Caption requires one selection object");
+	const selection = value.selection;
+	if (!isRecord(selection)) problems.push("selection must be one AudioScript segment selection object, not an array");
 	else {
-		if (selections.length === 0) problems.push("selections must name at least one AudioScript segment");
-		const seen = /* @__PURE__ */ new Set();
-		for (const [index, selection] of selections.entries()) {
-			if (!isRecord(selection)) {
-				problems.push(`selections[${index}] must be an object`);
-				continue;
-			}
-			if (typeof selection.segmentId !== "string" || selection.segmentId.trim() === "") problems.push(`selections[${index}].segmentId must be a string`);
-			else if (seen.has(selection.segmentId)) problems.push(`selections[${index}].segmentId must be unique within the Caption`);
-			else seen.add(selection.segmentId);
-			if (Object.keys(selection).some((key) => key !== "segmentId" && key !== "textRange")) problems.push(`selections[${index}] may only contain segmentId and textRange`);
-			if (selection.textRange !== void 0) {
-				const range = selection.textRange;
-				if (!isRecord(range) || !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end <= range.start || Object.keys(range).some((key) => key !== "start" && key !== "end")) problems.push(`selections[${index}].textRange must be a non-empty half-open code-point range`);
-			}
-		}
+		if (typeof selection.segmentId !== "string" || !selection.segmentId.trim()) problems.push("selection.segmentId must be a non-empty string");
+		if (Object.keys(selection).some((key) => key !== "segmentId" && key !== "textRange")) problems.push("selection may only contain segmentId and textRange");
+		const range = selection.textRange;
+		if (range !== void 0 && (!isRecord(range) || !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end <= range.start || Object.keys(range).some((key) => key !== "start" && key !== "end"))) problems.push("selection.textRange must be a non-empty half-open code-point range");
+		if (Array.isArray(value.segmentRanges) && (value.segmentRanges.length !== 1 || !isRecord(value.segmentRanges[0]) || value.segmentRanges[0].segmentId !== selection.segmentId)) problems.push("Caption segmentRanges must contain only the selected segment timing");
 	}
 	const style = value.style;
 	if (style === void 0) return;
@@ -868,17 +931,15 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 	if ([
 		"video",
 		"audio",
-		"voice",
 		"image",
 		"caption",
 		"axvideo"
-	].includes(entityKind) && /^(?:sampling|coordinateSpace|coordinateSpace\.unit|extent\.kind)$/.test(path)) return true;
+	].includes(entityKind) && /^durationMs$/.test(path)) return true;
 	if (entityKind === "sequence-marker" && /^(?:durationPolicy|duration\.mode|timeRemapping\.(?:kind|mode))$/.test(path)) return true;
 	if ((entityKind === "sequence-marker" || entityKind === "caption") && /^segmentRanges\[\d+\]\.segmentId$/.test(path)) return true;
-	if (entityKind === "asset" && /^(?:external\.(?:system|key)|storageKey)$/.test(path)) return true;
-	if (isMediaAssetVariantKind(entityKind) && /^(?:external\.(?:system|key)|storageKey)$/.test(path)) return true;
+	if (entityKind === "asset" && /^(?:system|key|storageKey)$/.test(path)) return true;
 	if (entityKind === "voice" && /^voice\.(?:system|key|name)$/.test(path)) return true;
-	if (entityKind === "caption" && (path.startsWith("style.") || /^selections\[\d+\]\.segmentId$/.test(path))) return true;
+	if (entityKind === "caption" && (path.startsWith("style.") || path === "selection.segmentId")) return true;
 	if ([
 		"audio-script",
 		"caption",
@@ -893,7 +954,7 @@ function isOwnedLocalIdPath(entityKind, path) {
 		"caption",
 		"phonetic-script"
 	].includes(entityKind) && /^segments\[\d+\]\.segmentId$/.test(path)) return true;
-	if (entityKind === "caption" && /^selections\[\d+\]\.segmentId$/.test(path)) return true;
+	if (entityKind === "caption" && path === "selection.segmentId") return true;
 	if ((entityKind === "sequence-marker" || entityKind === "caption") && /^segmentRanges\[\d+\]\.segmentId$/.test(path)) return true;
 	if (entityKind === "asset" && /^(?:tracks\[\d+\]\.trackId|renditions\[\d+\]\.renditionId)$/.test(path)) return true;
 	return false;
@@ -931,19 +992,16 @@ function collectRelatedEntities(entityRefs, index) {
 		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"
-	};
+/**
+* What a kind must state about its own length. An AXVideo is absent here on
+* purpose: its Timeline decides its length, so it stores none.
+*/
+function expectedDurationShape(kind) {
+	if (kind === "video" || kind === "audio" || kind === "caption") return "own";
+	if (kind === "image") return "none";
+}
+function isPositiveInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
 function ofKind(relations, kind) {
 	return relations.filter((relation) => relation.kind === kind);
@@ -960,9 +1018,18 @@ const markerContentRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => hasMarkerAndSequence(endpoints),
 	validateMetadata: isEmptyMetadata
 });
-const physicalAssetRelationSpec = Object.freeze({
-	kind: "physical-asset",
-	validateEndpoints: (endpoints) => hasAssetAndSequence(endpoints),
+/**
+* `from-asset(entity, asset)` — the entity was made from that stored resource.
+*
+* Eligibility is declared: the non-Asset endpoint must carry the `FromAsset`
+* kind, which says an entity of that kind can be made from stored bytes and
+* asks nothing of its payload. The bytes stay named in exactly one place, so
+* no entity copies the locator into its own row and one Asset can back several
+* entities.
+*/
+const fromAssetRelationSpec = Object.freeze({
+	kind: "from-asset",
+	validateEndpoints: (endpoints) => hasExactlyOneAsset(endpoints),
 	validateMetadata: isAssetBinding
 });
 /** `generated(output, input)` means endpoint 0 was generated from endpoint 1. */
@@ -973,7 +1040,7 @@ const generatedRelationSpec = Object.freeze({
 });
 const captionAlignmentRelationSpec = Object.freeze({
 	kind: "caption-alignment",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["caption"]), new Set(["audio", "voice"])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["caption"]), new Set(["audio"])),
 	validateMetadata: isCaptionAlignmentMetadata
 });
 /** `clip-anchor(child, host)` means endpoint 0 follows endpoint 1. */
@@ -982,20 +1049,29 @@ const clipAnchorRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => endpoints[0].current().entityKind === "clip" && endpoints[1].current().entityKind === "clip",
 	validateMetadata: isEmptyMetadata
 });
-/** Voice is generated from PhoneticScript; kinds determine roles regardless of endpoint positions. */
+/**
+* The rendered voiceover Audio and the PhoneticScript it was synthesized from;
+* kinds determine roles regardless of endpoint positions.
+*/
 const phoneticScriptRenderRelationSpec = Object.freeze({
 	kind: "phonetic-script-render",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["voice"]), new Set(["phonetic-script"])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio"]), new Set(["phonetic-script"])),
+	validateMetadata: isEmptyMetadata
+});
+/**
+* The timbre identity a rendered voiceover Audio was synthesized with. Voice
+* stays an identity: it never carries the audio itself, so the link between the
+* two is a Relation rather than one shared entity.
+*/
+const voiceTimbreRelationSpec = Object.freeze({
+	kind: "voice-timbre",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio"]), new Set(["voice"])),
 	validateMetadata: isEmptyMetadata
 });
 /** AudioScript was transcribed from Audio, Video, or recorded Voice; kinds determine roles. */
 const audioScriptSourceRelationSpec = Object.freeze({
 	kind: "audio-script-source",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set([
-		"audio",
-		"video",
-		"voice"
-	])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set(["audio", "video"])),
 	validateMetadata: isEmptyMetadata
 });
 /**
@@ -1017,11 +1093,12 @@ const builtInRelationSpecs = Object.freeze([
 	markerContentRelationSpec,
 	axVideoMarkerRelationSpec,
 	markerTimelineRelationSpec,
-	physicalAssetRelationSpec,
+	fromAssetRelationSpec,
 	generatedRelationSpec,
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
 	phoneticScriptRenderRelationSpec,
+	voiceTimbreRelationSpec,
 	audioScriptSourceRelationSpec,
 	audioScriptMarkerRelationSpec
 ]);
@@ -1045,13 +1122,15 @@ function hasMarkerAndSequence(endpoints) {
 	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);
+/** Exactly one end is the Asset, so the other end is unambiguously the maker. */
+function hasExactlyOneAsset(endpoints) {
+	const kinds = endpoints.map((endpoint) => endpoint.current().entityKind);
+	const assets = kinds.map((kind) => kind === "asset");
+	if (assets[0] === assets[1]) return false;
+	return declaresKind(assets[0] ? kinds[1] : kinds[0], "FromAsset");
 }
 function isGeneratedMedia(entity) {
-	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio" || entity.entityKind === "voice";
+	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio";
 }
 function isEmptyMetadata(value) {
 	return isJsonObject(value) && Object.keys(value).length === 0;
@@ -1387,7 +1466,7 @@ function errorMessage(error) {
 //#endregion
 //#region src/sandbox/business-facades.ts
 /** Resource IDs are entity data; physical storage paths remain host-owned. */
-const infrastructureFields = new Set(["storageKey"]);
+const infrastructureFields = new Set(["storageKey", "assetContentHash"]);
 function businessEntity(entity) {
 	return {
 		...entity,
@@ -1400,11 +1479,11 @@ function businessState(state) {
 		revision: state.revision,
 		audioScriptEntityId: state.audioScriptEntityId,
 		entities: state.entities.filter((row) => !assets.has(row.entity_id)).map(businessEntity),
-		relations: state.relations.filter((row) => row.relation_kind !== "physical-asset" && !assets.has(row.endpoint_0_entity_id) && !assets.has(row.endpoint_1_entity_id))
+		relations: state.relations.filter((row) => row.relation_kind !== "from-asset" && !assets.has(row.endpoint_0_entity_id) && !assets.has(row.endpoint_1_entity_id))
 	};
 }
 /** Keep infrastructure rows available to assembly without exposing their management to scripts. */
-function businessFacades(entities, relations) {
+function businessFacades(entities, relations, onDirectScriptWrite) {
 	const isAsset = (id) => entities.get(id)?.entity_kind === "asset";
 	const assertBusiness = (id) => {
 		if (isAsset(id)) throw new Error("Asset entities are managed by host assembly");
@@ -1415,7 +1494,7 @@ function businessFacades(entities, relations) {
 			for (const id of payload.baseEntityIds) if (typeof id === "string") assertBusiness(id);
 		}
 	};
-	const visibleRelation = (relation) => relation.relation_kind !== "physical-asset" && !isAsset(relation.endpoint_0_entity_id) && !isAsset(relation.endpoint_1_entity_id);
+	const visibleRelation = (relation) => relation.relation_kind !== "from-asset" && !isAsset(relation.endpoint_0_entity_id) && !isAsset(relation.endpoint_1_entity_id);
 	return {
 		entities: {
 			list: () => entities.list().filter((entity) => entity.entity_kind !== "asset").map(businessEntity),
@@ -1427,7 +1506,9 @@ function businessFacades(entities, relations) {
 				if (input.entity_kind === "asset") throw new Error("Asset entities are managed by host assembly");
 				assertBusinessPayload(input.payload);
 				if (input.entity_id && entities.get(input.entity_id)) throw new Error(`Entity id ${input.entity_id} already exists`);
-				return entities.create(input);
+				const id = entities.create(input);
+				if (input.entity_kind === "audio-script") onDirectScriptWrite?.(id);
+				return id;
 			},
 			update: (input) => {
 				assertBusiness(input.entity_id);
@@ -1437,11 +1518,13 @@ function businessFacades(entities, relations) {
 					if (change.path?.[0] === "baseEntityIds" && change.op === "list.insert" && typeof change.value === "string") assertBusiness(change.value);
 				}
 				entities.changeFields(input);
+				if (entities.get(input.entity_id)?.entity_kind === "audio-script" && input.changes.some((change) => change.path[0] === "segments")) onDirectScriptWrite?.(input.entity_id);
 			},
 			declareFields: (input) => {
 				assertBusiness(input.entity_id);
 				assertBusinessPayload(input.payload);
 				entities.declareFields(input);
+				if (entities.get(input.entity_id)?.entity_kind === "audio-script" && Object.hasOwn(input.payload, "segments")) onDirectScriptWrite?.(input.entity_id);
 			},
 			delete: (input) => {
 				assertBusiness(input.entity_id);
@@ -1458,7 +1541,7 @@ function businessFacades(entities, relations) {
 			list: () => relations.list().filter(visibleRelation),
 			of: (id, kind) => relations.of(id, kind).filter(visibleRelation),
 			link: (input) => {
-				if (input.relation_kind === "physical-asset") throw new Error("Asset bindings are managed by host assembly");
+				if (input.relation_kind === "from-asset") throw new Error("Asset bindings are managed by host assembly");
 				assertBusiness(input.endpoint_0_entity_id);
 				assertBusiness(input.endpoint_1_entity_id);
 				return relations.link(input);
@@ -1478,8 +1561,6 @@ function businessFacades(entities, relations) {
 }
 //#endregion
 //#region src/entity/entity-sandbox.ts
-const ASSET_SOURCE_KEY = "external";
-const MEMOTA_SYSTEM = "memota";
 /** Mutable entity/relation draft whose only durable product is an explicit command plan. */
 var EntitySandbox = class {
 	original;
@@ -1520,6 +1601,14 @@ var EntitySandbox = class {
 	captionAudioScriptId(entityId) {
 		return findComposedAudioScript(toDslRows(this.state), createEntityId(entityId), "caption").entityId;
 	}
+	/** The Asset an entity was made from; the bytes are named there alone. */
+	assetOf(entityId) {
+		const link = this.state.relations.find((relation) => relation.relation_kind === "from-asset" && (relation.endpoint_0_entity_id === entityId || relation.endpoint_1_entity_id === entityId));
+		if (!link) return null;
+		const otherId = link.endpoint_0_entity_id === entityId ? link.endpoint_1_entity_id : link.endpoint_0_entity_id;
+		const other = this.entities.get(otherId);
+		return other?.entity_kind === "asset" ? other : null;
+	}
 	get audioScriptEntityId() {
 		return this.state.audioScriptEntityId;
 	}
@@ -1532,6 +1621,10 @@ var EntitySandbox = class {
 		this.commands.push(...prefix);
 		this.onTruncate?.(index);
 	}
+	/** The working rows, for callers that must ask the graph rather than one row. */
+	rows() {
+		return toDslRows(this.state);
+	}
 	buildPlan() {
 		const rows = toDslRows(this.state);
 		decodeEntityRelationRows(rows, numericMarkerComparators);
@@ -1596,12 +1689,15 @@ var EntitySandbox = class {
 			},
 			findByAssetId: (assetId) => {
 				assertTrimmed(assetId, "assetId");
-				return clone(this.state.entities.map((entity) => this.assembledEntity(entity)).filter((entity) => isMediaAssetVariantKind(entity.entity_kind) && isImportedMemotaAsset(entity.payload, assetId)));
+				const assetIds = new Set(this.state.entities.filter((entity) => entity.entity_kind === "asset" && isImportedMemotaAsset(entity.payload, assetId)).map((entity) => entity.entity_id));
+				const madeIds = new Set(this.state.relations.filter((relation) => relation.relation_kind === "from-asset").flatMap((relation) => assetIds.has(relation.endpoint_1_entity_id) ? [relation.endpoint_0_entity_id] : assetIds.has(relation.endpoint_0_entity_id) ? [relation.endpoint_1_entity_id] : []));
+				return clone(this.state.entities.filter((entity) => madeIds.has(entity.entity_id) && isMediaAssetVariantKind(entity.entity_kind)).map((entity) => this.assembledEntity(entity)));
 			},
 			readCaptionContent: (entityId) => {
 				const assembled = assembleCaptionContent(toDslRows(this.state), createEntityId(entityId));
 				return clone({
 					audio_script_entity_id: assembled.audioScript.entityId,
+					segment_index: assembled.segmentIndex,
 					text: assembled.text,
 					segments: assembled.segments.map((segment) => ({ ...segment }))
 				});
@@ -1657,7 +1753,9 @@ var EntitySandbox = class {
 				});
 			},
 			delete: (input) => this.deleteEntity(input),
-			ensureMedia: (fact) => this.ensureMedia(fact)
+			ensureMedia: (fact) => this.ensureMedia(fact),
+			ensureAsset: (locator) => this.ensureAsset(locator),
+			assetIdOf: (entityId) => this.assetOf(entityId)?.entity_id ?? null
 		};
 	}
 	buildRelationFacade() {
@@ -1686,15 +1784,10 @@ var EntitySandbox = class {
 			if (matches.length > 1) throw new Error(`Ambiguous editor ${input.entity_kind}; resolve existing identities`);
 			if (matches[0] !== void 0) return this.reuseEntity(matches[0], input, payload);
 		}
-		const external = payload.external;
-		if (isMediaAssetVariantKind(input.entity_kind) && isJsonObject(external) && (external.system === "memota" || external.system === "memota-speech") && typeof external.key === "string") {
-			const matches = this.state.entities.filter((entity) => isMediaAssetVariantKind(entity.entity_kind) && isJsonObject(entity.payload.external) && entity.payload.external.system === external.system && entity.payload.external.key === external.key);
-			if (matches.length > 1) throw new Error(`Ambiguous Asset bindings for ${external.key}`);
-			const existing = matches[0];
-			if (existing !== void 0) {
-				if (existing.entity_kind !== input.entity_kind) throw new Error(`Asset kind conflicts for ${external.key}; cannot change ${existing.entity_kind} to ${input.entity_kind}`);
-				return this.reuseEntity(existing, input, payload);
-			}
+		if (input.entity_kind === "asset" && typeof payload.key === "string") {
+			const matches = this.state.entities.filter((entity) => entity.entity_kind === "asset" && entity.payload.system === payload.system && entity.payload.key === payload.key);
+			if (matches.length > 1) throw new Error(`Ambiguous Assets for ${payload.key}`);
+			if (matches[0] !== void 0) return this.reuseEntity(matches[0], input, payload);
 		}
 		const entityId = input.entity_id ?? this.idFactory("entity");
 		assertTrimmed(entityId, "entity_id");
@@ -1765,6 +1858,18 @@ var EntitySandbox = class {
 			entity_id: input.entity_id
 		});
 	}
+	/** Get or create the one Asset entity naming these bytes. */
+	ensureAsset(locator) {
+		const found = this.state.entities.find((row) => row.entity_kind === "asset" && row.payload.system === locator.system && row.payload.key === locator.key);
+		if (found) return found.entity_id;
+		return this.createEntity({
+			entity_kind: "asset",
+			payload: {
+				...locator,
+				...locator.storageKey === void 0 ? {} : { storageKey: locator.storageKey }
+			}
+		});
+	}
 	ensureMedia(fact) {
 		const checkpoint = this.commandCount;
 		try {
@@ -1791,7 +1896,7 @@ var EntitySandbox = class {
 		}
 		for (const row of rows.relations) {
 			if (this.state.relations.some((relation) => relation.relation_id === row.relationId)) continue;
-			if (row.relationKind !== "timeline-track") throw new Error(`Unexpected resource Relation ${row.relationKind}`);
+			if (row.relationKind !== "timeline-track" && row.relationKind !== "voice-timbre" && row.relationKind !== "from-asset") throw new Error(`Unexpected resource Relation ${row.relationKind}`);
 			this.link({
 				relation_id: row.relationId,
 				relation_kind: row.relationKind,
@@ -2048,8 +2153,7 @@ var EntitySandbox = class {
 	}
 };
 function isImportedMemotaAsset(payload, assetId) {
-	const external = payload[ASSET_SOURCE_KEY];
-	return external != null && !Array.isArray(external) && typeof external === "object" && (external.system === MEMOTA_SYSTEM || external.system === "memota-speech") && external.key === assetId;
+	return (payload.system === "memota" || payload.system === "memota-speech") && payload.key === assetId;
 }
 function toDslEntity(entity) {
 	return {
@@ -2098,4 +2202,4 @@ const numericMarkerComparators = { compareMarkerPoints: (_marker, _range, left,
 //#endregion
 export { createEntityId as a, businessState as i, toDslRows as n, createRelationId as o, businessFacades as r, isMediaAssetVariantKind as s, EntitySandbox as t };
 
-//# sourceMappingURL=entity-sandbox-OArq9NSH.mjs.map
+//# sourceMappingURL=entity-sandbox-BTR2cRl1.mjs.map