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

package/dist/{entity-sandbox-TaUVT3on.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,14 +268,17 @@ function assembleCaptionContent(rows, captionEntityId) {
 	requireEntityKind(rows, captionEntityId, "caption");
 	const caption = assembleEntityContent(rows, captionEntityId);
 	const script = findComposedAudioScript(rows, captionEntityId, "caption");
-	const segment = selectAudioScriptSegment({
+	const selection = captionSelection(caption);
+	const composed = {
 		...script,
 		payload: caption.payload
-	}, captionSelection(caption));
+	};
+	const segment = selectAudioScriptSegment(composed, selection);
 	return {
 		caption,
 		audioScript: script,
 		segments: [segment],
+		segmentIndex: scriptSegments(composed).findIndex((entry) => entry.segmentId === selection.segmentId),
 		text: segment.text
 	};
 }
@@ -284,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) {
@@ -317,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;
@@ -542,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()) {
@@ -590,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",
@@ -598,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":
@@ -608,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);
@@ -645,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);
@@ -691,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\"");
@@ -732,7 +808,6 @@ 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);
 	if (Object.hasOwn(value, "selections")) problems.push("selections is forbidden; Caption requires one selection object");
 	const selection = value.selection;
@@ -856,15 +931,13 @@ 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.") || path === "selection.segmentId")) return true;
 	if ([
@@ -919,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);
@@ -948,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. */
@@ -961,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. */
@@ -970,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
 });
 /**
@@ -1005,11 +1093,12 @@ const builtInRelationSpecs = Object.freeze([
 	markerContentRelationSpec,
 	axVideoMarkerRelationSpec,
 	markerTimelineRelationSpec,
-	physicalAssetRelationSpec,
+	fromAssetRelationSpec,
 	generatedRelationSpec,
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
 	phoneticScriptRenderRelationSpec,
+	voiceTimbreRelationSpec,
 	audioScriptSourceRelationSpec,
 	audioScriptMarkerRelationSpec
 ]);
@@ -1033,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;
@@ -1375,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,
@@ -1388,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");
@@ -1403,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),
@@ -1415,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);
@@ -1425,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);
@@ -1446,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);
@@ -1466,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;
@@ -1508,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;
 	}
@@ -1520,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);
@@ -1584,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 }))
 				});
@@ -1645,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() {
@@ -1674,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");
@@ -1753,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 {
@@ -1779,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,
@@ -2036,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 {
@@ -2084,6 +2200,6 @@ const numericMarkerComparators = { compareMarkerPoints: (_marker, _range, left,
 	return left - right;
 } };
 //#endregion
-export { isJsonObject as a, isMediaAssetVariantKind as c, businessState as i, toDslRows as n, createEntityId as o, businessFacades as r, createRelationId as s, EntitySandbox as t };
+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-TaUVT3on.mjs.map
+//# sourceMappingURL=entity-sandbox-BTR2cRl1.mjs.map