@mengine/medeo-client 1.2.1-alpha.9 → 1.3.1-alpha.0

package/README.md

@@ -10,15 +10,43 @@ asset facts, not an entity store implementation.
 For entity-authoritative documents:
 
 1. `EntityGraphHttpClient.fetchState()` obtains the complete graph and revision.
-2. `importMediaAsset` reuses or creates media/Asset bindings from recalled facts.
-   Video duration must come from asset metadata, never a clip trim window. Asset
-   and media entities are not one-to-one; ambiguous graphs require an explicit
-   `MediaAssetSelection` (fourth argument), not an arbitrary first match.
+2. `ensureEditorFoundation` gets or creates one Timeline and four role Tracks,
+   retaining all existing identities and settings. `importMediaAsset` groups and
+   deduplicates only by direct media variants carrying the same external asset
+   id `(system, key)`. Imports mint exactly one media variant Entity
+   (Video/Image/Audio/Voice) that carries the Asset locator itself; no separate
+   `asset` Entity and no `physical-asset` Relation are created, and the returned
+   identity is that single Entity. Video duration must come from asset
+   metadata, never a clip trim window. Dual-entity media graphs (`asset` row
+   plus a `physical-asset` binding) are not reused and fail explicitly instead
+   of minting a second identity. This policy is local to the MEngine editor, not
+   the general-purpose DSL.
 3. `EntityTimelineEditor` edits Clip/Marker/Track relations and payloads.
 4. `EntityGraphHttpClient.commit(baseState, nextRows)` performs revision CAS,
    including explicit net deletions. The server writes entities and the derived
    Loro read view in the same transaction.
 
+Repeated placement reuses the same single media identity but creates independent
+Clips and SequenceMarkers. Asset generation alone still does not create editor
+Entities. Two commit-level guards protect the single-identity policy:
+`assertCanonicalEditorResources(rows)` checks one complete state — every media
+variant carries its own external locator, one external asset id has exactly one
+claimant, and no media variant is bound through a `physical-asset` Relation.
+The exported `assertMediaAssetWritePolicy(before, after)` checks one CAS
+transition and is reusable by the host tool and the entity stores: it applies
+the same rules to the complete after state, and a self-carried identity cannot
+be rewritten to another asset id. The editor applies it to every transaction
+and `EntityGraphHttpClient.commit` applies it to `(baseState.rows, nextRows)`
+before any request. There is no historical exemption: dual-entity media graphs
+are rejected rather than kept editable — the shared `decodeEntityRelationRows`
+boundary already fails rows whose media variants lack `external` or carry a
+`physical-asset` binding, so editors and commits never observe them — deleting
+media is an explicit caller decision, and no implicit historical merge or
+identity rewriting occurs. The
+compatibility reader reads physical facts directly from the media variant;
+Caption inline text still resolves its inline Asset through
+`physical-asset`.
+
 `SequenceMarker` owns source/target ranges, duration, and time remapping. `Clip`
 owns clip properties such as volume; `Track` owns track properties. References
 between entities belong in Relations, not in payload IDs. There is no separate
@@ -39,19 +67,23 @@ cold-start reconciliation must not POST legacy `/updates`. Entity writes use
 the independent graph CAS endpoint.
 
 Anchored placement is a `clip-anchor` Relation from child Clip to host Clip
-plus `SequenceMarker.anchorOffset`. Voice anchors to a visual Clip; Caption
-anchors to a Voice Clip. `resolveEntityTimelineLayout` resolves this graph
+plus `SequenceMarker.anchorOffset`. Voice and Caption can be independently
+placed or explicitly anchored; generation relations do not choose a host. `resolveEntityTimelineLayout` resolves this graph
 without reparenting or synthesizing content. Move/delete operations must write
 their follow, keep-absolute, cascade, or detach decisions into the same entity
 plan. A speech-overlap shift is explicit placement on the real visual Clips;
 an uncovered time interval does not require an invented empty-media entity.
 
 Voice links to its AudioScript through `audio-script-render`; Caption links to
-the same script and Voice through provenance/alignment relations. External
-speech identity and physical storage key belong to Asset, separately from the
-placed Clip identity. Caption styles belong to Caption; text can have a real
-inline text Asset rather than a fabricated Memota ID. Background Audio's
-Marker declares `durationPolicy: 'timeline'`: its source duration stays factual,
+its source script and optional alignment Voice through separate provenance/alignment relations. External
+speech identity and physical storage key belong to the Voice Entity itself.
+`insertCaptionClip` creates a complete independent Caption placement;
+`upsertVoiceoverTake` accepts explicit `placement` for independent voice.
+AudioScript carries only text. `audio-script-marker` attaches directly assigned
+`segmentRanges` timing; those annotation Markers cannot be Clip display Markers.
+Caption styles belong to Caption; text can have a real inline text Asset rather
+than a fabricated Memota ID. Background Audio's Marker declares
+`durationPolicy: 'timeline'`: its source duration stays factual,
 while the view fills the non-BGM timeline duration.
 
 `migrateLegacyTimelineToEntities` is a one-time migration utility, **not** an

package/dist/{document-Df6awJDH.js → document-Caidonf8.js}

@@ -130,7 +130,7 @@ const captionStyle$1 = schema.LoroMap({
 const captionPart = schema.LoroMap({
 	id: schema.String(),
 	initial_duration_ms: schema.Number(),
-	speech_part_id: schema.String(),
+	speech_part_id: schema.String({ required: false }),
 	text: schema.String(),
 	start_ms: schema.Number(),
 	style: captionStyle$1
@@ -819,7 +819,7 @@ const captionPartSchema = z.object({
 	id: z.string().optional(),
 	kind: z.literal("caption"),
 	initial_duration_ms: finiteNumber,
-	speech_part_id: z.string(),
+	speech_part_id: z.string().optional(),
 	text: z.string(),
 	start_ms: finiteNumber,
 	style: z.object({
@@ -1489,45 +1489,6 @@ function emptyLaneTracks() {
 	}));
 }
 //#endregion
-//#region src/document/entity-projection-values.ts
-/** A graph cannot be represented faithfully by the compatibility reader. */
-var EntityTimelineProjectionError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "EntityTimelineProjectionError";
-	}
-};
-function fail(message) {
-	throw new EntityTimelineProjectionError(message);
-}
-function object(value) {
-	return value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function finite(value, label) {
-	if (typeof value !== "number" || !Number.isFinite(value)) fail(`${label} must be finite`);
-	return value;
-}
-function positive(value, label) {
-	const result = finite(value, label);
-	if (result <= 0) fail(`${label} must be positive`);
-	return result;
-}
-function milliseconds(value, label) {
-	const result = finite(value, label);
-	if (!Number.isSafeInteger(result) || result < 0) fail(`${label} must be non-negative whole milliseconds`);
-	return result;
-}
-function range(value, label) {
-	if (!object(value)) fail(`${label} must be a numeric range`);
-	const start = finite(value.start, `${label}.start`);
-	const end = finite(value.end, `${label}.end`);
-	if (start >= end) fail(`${label} must be non-empty`);
-	return {
-		start,
-		end
-	};
-}
-//#endregion
 //#region ../medeo-dsl/src/entities.ts
 function hasSequence(entity) {
 	if (isKnownNonSequenceKind(entity.entityKind) || isReservedEntityKind(entity.entityKind)) return false;
@@ -1544,7 +1505,10 @@ function isSequenceFields(value) {
 	return "coordinateSpace" in value && value.coordinateSpace !== void 0;
 }
 function isKnownSequenceKind(kind) {
-	return kind === "video" || kind === "audio" || kind === "voice" || kind === "image" || kind === "caption" || kind === "axvideo";
+	return isMediaAssetVariantKind(kind) || kind === "caption" || kind === "axvideo";
+}
+function isMediaAssetVariantKind(kind) {
+	return kind === "video" || kind === "image" || kind === "audio" || kind === "voice";
 }
 function isKnownEntityKind(kind) {
 	return isKnownSequenceKind(kind) || isKnownNonSequenceKind(kind);
@@ -1573,6 +1537,18 @@ function createId(value, label) {
 }
 //#endregion
 //#region ../medeo-dsl/src/invariants.ts
+/**
+* Media variants own their Asset identity directly: a `physical-asset`
+* Relation may not bind them. Caption inline text (and other non-media
+* Sequence entities) keep their Asset binding.
+*/
+function validateMediaAssetIdentity(entity, index) {
+	return [...index.relationsOf(entity)].filter((relation) => relation.kind === "physical-asset").map(() => ({
+		code: "media_physical_asset_forbidden",
+		entityId: entity.entityId,
+		message: `Media entity "${entity.entityId}" owns its Asset identity; remove its physical-asset Relation`
+	}));
+}
 /** Validates one complete set of entities and its authoritative Relation rows. */
 function validateEntityRelationSet(entityRefs, index, options) {
 	const { entities, issues } = collectRelatedEntities(entityRefs, index);
@@ -1581,6 +1557,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));
 		if (entityIssues.some((issue) => issue.code === "invalid_entity_payload")) continue;
 		if (current.entityKind === "sequence-marker") {
 			const marker = entity;
@@ -1608,7 +1585,39 @@ function validateMarkerUse(marker, index) {
 	const axVideoEdges = ofKind(relations, "axvideo-marker");
 	const contentEdges = ofKind(relations, "marker-content");
 	const timelineEdges = ofKind(relations, "marker-timeline");
+	const scriptEdges = ofKind(relations, "audio-script-marker");
 	const issues = [];
+	if (scriptEdges.length > 0) {
+		if (clipEdges.length + axVideoEdges.length + contentEdges.length + timelineEdges.length > 0) issues.push({
+			code: "marker_container_xor",
+			entityId: marker.entityId,
+			message: "An AudioScript annotation Marker must not carry Clip, AXVideo, content, or Timeline relations"
+		});
+		const ranges = marker.current().segmentRanges;
+		if (!ranges?.length) issues.push({
+			code: "invalid_entity_payload",
+			entityId: marker.entityId,
+			message: "An AudioScript annotation Marker requires segmentRanges"
+		});
+		for (const relation of scriptEdges) {
+			const script = relation.other(marker)?.deref()?.current();
+			if (script?.entityKind !== "audio-script") continue;
+			const segments = script.segments;
+			if (!Array.isArray(segments)) continue;
+			const segmentIds = new Set(segments.map((segment) => segment.segmentId));
+			if (ranges?.some((range) => !segmentIds.has(range.segmentId))) issues.push({
+				code: "invalid_entity_payload",
+				entityId: marker.entityId,
+				message: "Annotation segmentRanges must name segments of the related AudioScript"
+			});
+		}
+		return issues;
+	}
+	if (marker.current().segmentRanges !== void 0) issues.push({
+		code: "invalid_entity_payload",
+		entityId: marker.entityId,
+		message: "segmentRanges belongs to an AudioScript annotation Marker, not a display Marker"
+	});
 	if (clipEdges.length + axVideoEdges.length !== 1) issues.push({
 		code: "marker_container_xor",
 		entityId: marker.entityId,
@@ -1711,10 +1720,10 @@ function validateClipPlacement(clip, index) {
 		const content = ofKind([...index.relationsOf(marker)], "marker-content")[0]?.other(marker)?.deref()?.current();
 		const track = ofKind([...index.relationsOf(clip)], "track-clip")[0]?.other(clip)?.deref()?.current();
 		const trackRole = track?.entityKind === "track" ? track.role : void 0;
-		if (content?.entityKind !== "audio" || trackRole !== "bgm" || !hasOrder) issues.push({
+		if (content?.entityKind !== "audio" || trackRole !== "bgm" || !hasOrder && !hasTarget) issues.push({
 			code: "timeline_duration_policy_invalid",
 			entityId: marker.entityId,
-			message: "Marker durationPolicy \"timeline\" is only valid for ordered Audio Clips on the bgm Track"
+			message: "Marker durationPolicy \"timeline\" is only valid for ordered or absolutely placed Audio Clips on the bgm Track"
 		});
 	}
 	return issues;
@@ -1824,11 +1833,13 @@ function validateKnownEntityPayload(entity) {
 		case "voice":
 		case "caption":
 			validateSequencePayload(value, "bounded", "native", problems);
+			if (entity.entityKind !== "caption") validateMediaAssetFields(value, problems);
 			if (entity.entityKind === "voice") validateVoicePayload(value, problems);
 			if (entity.entityKind === "caption") validateCaptionPayload(value, problems);
 			break;
 		case "image":
 			validateSequencePayload(value, "unbounded", "constant", problems);
+			validateMediaAssetFields(value, problems);
 			break;
 		case "axvideo":
 			validateSequencePayload(value, "bounded", "derived", problems);
@@ -1876,22 +1887,64 @@ function validateMarkerPayload(value, problems) {
 	} else if (duration.mode !== "from-source") problems.push("duration.mode must be \"from-source\" or \"fixed\"");
 	if (value.anchorOffset === void 0 && Object.hasOwn(value, "anchorOffset")) problems.push("anchorOffset cannot be undefined when present");
 	if (value.durationPolicy !== void 0 && value.durationPolicy !== "timeline") problems.push("durationPolicy must be \"timeline\" when present");
+	if (value.segmentRanges !== void 0) validateSegmentRanges(value.segmentRanges, problems);
 }
-function validateAssetPayload(value, problems) {
-	const external = value.external;
-	if (external !== void 0) if (!isRecord(external)) problems.push("external must be an object when present");
-	else {
-		if (external.system !== "memota" && external.system !== "memota-speech") problems.push("external.system must be \"memota\" or \"memota-speech\"");
-		if (typeof external.key !== "string" || external.key.trim() === "") problems.push("external.key must be a non-empty string");
+/** Annotation Marker time values are directly assigned facts; no cross-references are allowed. */
+function validateSegmentRanges(value, problems) {
+	if (!Array.isArray(value)) {
+		problems.push("segmentRanges must be an array when present");
+		return;
 	}
-	if (value.storageKey !== void 0 && (typeof value.storageKey !== "string" || value.storageKey.trim() === "")) problems.push("storageKey must be a non-empty string when present");
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, entry] of value.entries()) {
+		if (!isRecord(entry)) {
+			problems.push(`segmentRanges[${index}] must be an object`);
+			continue;
+		}
+		if (typeof entry.segmentId !== "string") problems.push(`segmentRanges[${index}].segmentId must be a string`);
+		else if (seen.has(entry.segmentId)) problems.push(`segmentRanges[${index}].segmentId must be unique within the Marker`);
+		else seen.add(entry.segmentId);
+		for (const key of ["startMs", "endMs"]) {
+			const point = entry[key];
+			if (typeof point !== "number" || !Number.isFinite(point)) problems.push(`segmentRanges[${index}].${key} must be a finite number`);
+		}
+		if (typeof entry.startMs === "number" && Number.isFinite(entry.startMs) && typeof entry.endMs === "number" && Number.isFinite(entry.endMs) && entry.startMs > entry.endMs) problems.push(`segmentRanges[${index}].startMs must not exceed segmentRanges[${index}].endMs`);
+	}
+}
+function validateAssetPayload(value, problems) {
+	validateExternalLocator(value, problems);
+	validateStorageKey(value, problems);
 	const inline = value.inline;
 	if (inline !== void 0) if (!isRecord(inline)) problems.push("inline must be an object when present");
 	else {
 		if (inline.mediaType !== "text/plain") problems.push("inline.mediaType must be \"text/plain\"");
 		if (typeof inline.text !== "string") problems.push("inline.text must be a string");
 	}
-	if (external !== void 0 && inline !== void 0) problems.push("Asset must not combine external and inline physical locations");
+	if (value.external !== void 0 && value.inline !== void 0) problems.push("Asset must not combine external and inline physical locations");
+}
+/**
+* Media variants own their Asset locator directly: `external` is required and
+* inline text stays an Asset-kind-only value so the two physical-location
+* vocabularies cannot mix.
+*/
+function validateMediaAssetFields(value, problems) {
+	if (value.external === void 0) problems.push("external is required; media variants own their Asset identity");
+	else validateExternalLocator(value, problems);
+	validateStorageKey(value, problems);
+	if (value.inline !== void 0) problems.push("inline is an Asset-kind field; media variants use external");
+}
+function validateExternalLocator(value, problems) {
+	const external = value.external;
+	if (external === void 0) return;
+	if (!isRecord(external)) {
+		problems.push("external must be an object when present");
+		return;
+	}
+	if (external.system !== "memota" && external.system !== "memota-speech") problems.push("external.system must be \"memota\" or \"memota-speech\"");
+	if (typeof external.key !== "string" || external.key.trim() === "") problems.push("external.key must be a non-empty string");
+}
+function validateStorageKey(value, problems) {
+	if (value.storageKey !== void 0 && (typeof value.storageKey !== "string" || value.storageKey.trim() === "")) problems.push("storageKey must be a non-empty string when present");
 }
 function validateVoicePayload(value, problems) {
 	const voice = value.voice;
@@ -1950,6 +2003,15 @@ function validateScriptPayload(value, problems) {
 			problems.push(`segments[${index}] must be an object`);
 			continue;
 		}
+		for (const key of [
+			"startMs",
+			"endMs",
+			"start_ms",
+			"end_ms",
+			"sourceRange",
+			"targetRange",
+			"duration"
+		]) if (Object.hasOwn(segment, key)) problems.push(`segments[${index}].${key} is timing; attach an AudioScript annotation Marker instead`);
 		if (typeof segment.segmentId !== "string") problems.push(`segments[${index}].segmentId must be a string`);
 		if (typeof segment.text !== "string") problems.push(`segments[${index}].text must be a string`);
 		if (segment.language !== void 0 && typeof segment.language !== "string") problems.push(`segments[${index}].language must be a string when present`);
@@ -2008,7 +2070,9 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 		"axvideo"
 	].includes(entityKind) && /^(?:sampling|coordinateSpace|coordinateSpace\.unit|extent\.kind)$/.test(path)) return true;
 	if (entityKind === "sequence-marker" && /^(?:durationPolicy|duration\.mode|timeRemapping\.(?:kind|mode))$/.test(path)) return true;
+	if (entityKind === "sequence-marker" && /^segmentRanges\[\d+\]\.segmentId$/.test(path)) return true;
 	if (entityKind === "asset" && /^(?:external\.(?:system|key)|storageKey|inline\.(?:mediaType|text))$/.test(path)) return true;
+	if (isMediaAssetVariantKind(entityKind) && /^(?:external\.(?:system|key)|storageKey)$/.test(path)) return true;
 	if (entityKind === "voice" && /^voice\.(?:system|key|name)$/.test(path)) return true;
 	if (entityKind === "caption" && (path === "text" || path.startsWith("style."))) return true;
 	if ((entityKind === "audio-script" || entityKind === "phonetic-script") && /^segments\[\d+\]\.(?:segmentId|text|language)$/.test(path)) return true;
@@ -2017,6 +2081,7 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 function isOwnedLocalIdPath(entityKind, path) {
 	if (path === "lifecycle.actorId") return true;
 	if ((entityKind === "audio-script" || entityKind === "phonetic-script") && /^segments\[\d+\]\.segmentId$/.test(path)) return true;
+	if (entityKind === "sequence-marker" && /^segmentRanges\[\d+\]\.segmentId$/.test(path)) return true;
 	if (entityKind === "asset" && /^(?:tracks\[\d+\]\.trackId|renditions\[\d+\]\.renditionId)$/.test(path)) return true;
 	return false;
 }
@@ -2144,6 +2209,23 @@ const audioScriptRenderRelationSpec = Object.freeze({
 	},
 	validateMetadata: isEmptyMetadata
 });
+/** `audio-script-source(script, source)` means endpoint 0 was transcribed from endpoint 1. */
+const audioScriptSourceRelationSpec = Object.freeze({
+	kind: "audio-script-source",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set(["audio", "video"])),
+	validateMetadata: isEmptyMetadata
+});
+/**
+* `audio-script-marker(script, marker)` attaches an annotation Sequence Marker
+* whose `segmentRanges` hold directly assigned per-Segment time values. The
+* script keeps no Sequence and no Clip admission; annotation Markers cannot
+* enter Clip/AXVideo use chains (enforced by the marker-use invariant).
+*/
+const audioScriptMarkerRelationSpec = Object.freeze({
+	kind: "audio-script-marker",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set(["sequence-marker"])),
+	validateMetadata: isEmptyMetadata
+});
 /** Built-in kinds are reserved; callers may add specs only under new names. */
 const builtInRelationSpecs = Object.freeze([
 	timelineTrackRelationSpec,
@@ -2158,7 +2240,9 @@ const builtInRelationSpecs = Object.freeze([
 	captionProvenanceRelationSpec,
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
-	audioScriptRenderRelationSpec
+	audioScriptRenderRelationSpec,
+	audioScriptSourceRelationSpec,
+	audioScriptMarkerRelationSpec
 ]);
 function emptySpec(kind, a, b) {
 	return metadataSpec(kind, a, b, isEmptyMetadata);
@@ -2255,7 +2339,7 @@ var BiRelationIndex = class {
 	byRelationId = /* @__PURE__ */ new Map();
 	link(input) {
 		if (input.spec.kind === "generated") throw new Error("Author generated Relations with linkGenerated({ output, input })");
-		if (input.spec.kind === "clip-anchor" || input.spec.kind === "audio-script-render") throw new Error(`Author ordered ${input.spec.kind} Relations with the dedicated role-named method`);
+		if (input.spec.kind === "clip-anchor" || input.spec.kind === "audio-script-render" || input.spec.kind === "audio-script-source") throw new Error(`Author ordered ${input.spec.kind} Relations with the dedicated role-named method`);
 		return this.linkValidated(input);
 	}
 	/** Author `generated(output, input)` without exposing positional arguments. */
@@ -2288,6 +2372,16 @@ var BiRelationIndex = class {
 			trace: input.trace
 		});
 	}
+	/** Author `audio-script-source(script, source)` without exposing positional arguments. */
+	linkAudioScriptSource(input) {
+		return this.linkValidated({
+			relationId: input.relationId,
+			spec: audioScriptSourceRelationSpec,
+			endpoints: [input.script, input.source],
+			metadata: {},
+			trace: input.trace
+		});
+	}
 	/**
 	* Rehydrate a persisted row after resolving its spec and endpoint refs.
 	*
@@ -2507,6 +2601,45 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
+//#region src/document/entity-projection-values.ts
+/** A graph cannot be represented faithfully by the compatibility reader. */
+var EntityTimelineProjectionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EntityTimelineProjectionError";
+	}
+};
+function fail(message) {
+	throw new EntityTimelineProjectionError(message);
+}
+function object(value) {
+	return value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function finite(value, label) {
+	if (typeof value !== "number" || !Number.isFinite(value)) fail(`${label} must be finite`);
+	return value;
+}
+function positive(value, label) {
+	const result = finite(value, label);
+	if (result <= 0) fail(`${label} must be positive`);
+	return result;
+}
+function milliseconds(value, label) {
+	const result = finite(value, label);
+	if (!Number.isSafeInteger(result) || result < 0) fail(`${label} must be non-negative whole milliseconds`);
+	return result;
+}
+function range(value, label) {
+	if (!object(value)) fail(`${label} must be a numeric range`);
+	const start = finite(value.start, `${label}.start`);
+	const end = finite(value.end, `${label}.end`);
+	if (start >= end) fail(`${label} must be non-empty`);
+	return {
+		start,
+		end
+	};
+}
+//#endregion
 //#region src/document/entity-timeline-layout.ts
 /** Validated graph lookup shared by the compatibility layout and projection. */
 var EntityProjectionGraph = class {
@@ -2643,7 +2776,7 @@ function resolveGraphLayout(graph) {
 		let start = fact.absoluteStart ?? 0;
 		if (fact.mode === "anchored") {
 			const host = resolve(fact.anchorId);
-			if (fact.role === "speech" && facts.get(host.clipEntityId).role !== "video_clip") fail("An anchored Voice must use a visual Clip as its host");
+			if (fact.role === "speech" && !["video_clip", "bgm"].includes(facts.get(host.clipEntityId).role)) fail("An anchored Voice must use a visual or BGM Clip as its host");
 			start = host.start + fact.anchorOffset;
 		} else if (fact.predecessor !== void 0) {
 			const prior = resolve(fact.predecessor);
@@ -2671,7 +2804,6 @@ function resolveGraphLayout(graph) {
 	const durationMs = Math.max(0, ...[...resolved.values()].filter((clip) => facts.get(clip.clipEntityId).role !== "bgm").map((clip) => clip.start + clip.duration));
 	for (const [id, fact] of facts) if (fact.fillTimeline) {
 		const clip = resolved.get(id);
-		if (clip.start !== 0) fail("Timeline-filling BGM must start at zero");
 		resolved.set(id, {
 			...clip,
 			duration: durationMs
@@ -2710,8 +2842,8 @@ function projectEntityTimeline(rows, meta) {
 		const content = graph.entity(placement.contentEntityId);
 		const volume = volumeSchema.safeParse(clip.payload.volume ?? 0);
 		if (!volume.success) fail("Clip volume must be decibels between -60 and 20");
-		const asset = graph.one(content.entityId, "physical-asset", "asset");
 		if (track.role === "video_clip") {
+			const asset = mediaAssetFacts(graph, content);
 			const source = range(marker.payload.sourceRange, "sourceRange");
 			const external = externalLocator(asset, "memota");
 			const speed = videoSpeed(content, marker, placement);
@@ -2725,6 +2857,7 @@ function projectEntityTimeline(rows, meta) {
 				...speed === void 0 ? {} : { speed_shift: speed }
 			} };
 		} else if (track.role === "speech") {
+			const asset = mediaAssetFacts(graph, content);
 			requireUntrimmedAudio(content, marker, placement);
 			const external = externalLocator(asset, "memota-speech");
 			const script = graph.one(content.entityId, "audio-script-render", "audio-script");
@@ -2748,27 +2881,25 @@ function projectEntityTimeline(rows, meta) {
 		} else if (track.role === "caption") {
 			const text = content.payload.text;
 			if (typeof text !== "string") fail("Caption " + content.entityId + " requires its text");
+			const asset = graph.one(content.entityId, "physical-asset", "asset");
 			const inline = asset.payload.inline;
 			if (inline !== void 0 && (!object(inline) || inline.mediaType !== "text/plain" || inline.text !== text)) fail("Inline Caption Asset and Caption text must agree");
 			if (inline === void 0 && !object(asset.payload.external)) fail("Caption Asset must identify physical text or contain actual inline text");
-			if (placement.anchorClipEntityId === void 0) fail("Caption placement requires an explicit voice Clip anchor");
-			const anchor = layout.clips.get(placement.anchorClipEntityId);
-			if (anchor === void 0 || graph.entity(anchor.contentEntityId).entityKind !== "voice") fail("Caption anchor must resolve a placed Voice");
-			if (graph.one(content.entityId, "caption-alignment").entityId !== anchor.contentEntityId) fail("Caption alignment must agree with its placed Voice");
-			const script = graph.one(content.entityId, "caption-provenance", "audio-script");
-			if (graph.one(anchor.contentEntityId, "audio-script-render", "audio-script").entityId !== script.entityId) fail("Caption provenance must agree with the Voice AudioScript");
 			if (marker.payload.timeRemapping !== void 0) fail("Caption timeRemapping is not supported by this reader");
 			const style = captionStyle(content.payload.style);
+			const anchor = placement.anchorClipEntityId === void 0 ? void 0 : layout.clips.get(placement.anchorClipEntityId);
+			const anchoredToSpeech = anchor !== void 0 && trackRoleOf(layout, anchor.trackEntityId) === "speech";
 			parts[clip.entityId] = { caption: {
 				id: clip.entityId,
 				kind: "caption",
 				text,
-				speech_part_id: placement.anchorClipEntityId,
-				start_ms: placement.anchorOffset,
+				speech_part_id: anchoredToSpeech ? placement.anchorClipEntityId : void 0,
+				start_ms: anchoredToSpeech ? placement.anchorOffset : 0,
 				initial_duration_ms: placement.duration,
 				...style === void 0 ? {} : { style }
 			} };
 		} else {
+			const asset = mediaAssetFacts(graph, content);
 			const external = externalLocator(asset, "memota");
 			if (marker.payload.durationPolicy !== "timeline") fail("Background Audio requires an explicit timeline-fill durationPolicy");
 			if (marker.payload.timeRemapping !== void 0) fail("BGM timeRemapping is not supported by this reader");
@@ -2815,6 +2946,23 @@ function projectEntityTimeline(rows, meta) {
 	assertValidVideoDocument(document);
 	return document;
 }
+function trackRoleOf(layout, trackEntityId) {
+	return layout.tracks.find((track) => track.entityId === trackEntityId)?.role;
+}
+/**
+* Media facts are read from the variant itself: a media variant owns its
+* Asset identity and carries `external`/`storageKey` directly. Dual-entity
+* media graphs are rejected instead of being resolved through a legacy
+* `physical-asset` binding.
+*/
+function mediaAssetFacts(graph, content) {
+	if (graph.adjacent(content.entityId, "physical-asset").length > 0) fail("Media " + content.entityId + " owns its Asset identity; remove its physical-asset Relation");
+	if (!object(content.payload.external)) fail("Media " + content.entityId + " must carry its own Asset external identity");
+	return {
+		entityId: String(content.entityId),
+		payload: content.payload
+	};
+}
 function externalLocator(asset, system) {
 	const value = asset.payload.external;
 	if (!object(value) || value.system !== system || typeof value.key !== "string" || value.key.trim() === "") fail("Asset " + asset.entityId + " requires an explicit " + system + " external key");
@@ -3203,4 +3351,4 @@ function createPlainMemoryAdapter(document, options) {
 	return new PlainMemoryAdapter(document, options);
 }
 //#endregion
-export { base64ToBytes as $, findLaneTrack as A, syncAggregatedClipsTimePosition as B, VideoDocumentValidationError as C, videoDocumentSchema as D, partUnionSchema as E, fillMainTrackTimeGaps as F, DEFAULT_UNIT_TIME_MS as G, isEmptyVideoClip as H, reassignSpeechesToVideoClipsByTime as I, effectiveVideoClipDurationMs as J, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as K, recalculateTimelineDuration as L, solveVideoDocument as M, cascadeAfterVideoClipChanges as N, LANE_KINDS_IN_STACK_ORDER as O, arrangeMainTrackSeamlessly as P, videoDocumentMirrorSchema as Q, resolveAllSpeechOverlaps as R, toVideoDocument as S, validateVideoDocument as T, partDurationMs as U, TIMELINE_SKELETON_DURATION_MS as V, safeDurationMs as W, partUnionToDraft as X, speedOf as Y, recordEntries as Z, EntityTimelineProjectionError as _, applyEntityTimelineProjection as a, derivePositionFromAbs as b, writeVideoDocumentToDraft as c, resolveEntityTimelineLayout as d, bytesToBase64 as et, decodeEntityRelationRows as f, hasSequence as g, createRelationId as h, MirrorVideoDocumentAdapter as i, laneTrackId as j, ensureLaneTrack as k, readVideoDocumentFromDraft as l, createEntityId as m, createPlainMemoryAdapter as n, createMirrorVideoDocument as o, isJsonObject as p, VIDEO_DOCUMENT_SCHEMA_VERSION as q, generatePartId as r, createMirrorVideoDocumentAdapter as s, PlainMemoryAdapter as t, projectEntityTimeline as u, buildInitialVideoDocument as v, assertValidVideoDocument as w, fromVideoDocument as x, buildSpeechHostMap as y, resolveSpeechOverlapByShiftingVideos as z };
+export { videoDocumentMirrorSchema as $, ensureLaneTrack as A, resolveSpeechOverlapByShiftingVideos as B, toVideoDocument as C, partUnionSchema as D, validateVideoDocument as E, arrangeMainTrackSeamlessly as F, safeDurationMs as G, TIMELINE_SKELETON_DURATION_MS as H, fillMainTrackTimeGaps as I, VIDEO_DOCUMENT_SCHEMA_VERSION as J, DEFAULT_UNIT_TIME_MS as K, reassignSpeechesToVideoClipsByTime as L, laneTrackId as M, solveVideoDocument as N, videoDocumentSchema as O, cascadeAfterVideoClipChanges as P, recordEntries as Q, recalculateTimelineDuration as R, fromVideoDocument as S, assertValidVideoDocument as T, isEmptyVideoClip as U, syncAggregatedClipsTimePosition as V, partDurationMs as W, speedOf as X, effectiveVideoClipDurationMs as Y, partUnionToDraft as Z, hasSequence as _, applyEntityTimelineProjection as a, buildSpeechHostMap as b, writeVideoDocumentToDraft as c, resolveEntityTimelineLayout as d, base64ToBytes as et, EntityTimelineProjectionError as f, createRelationId as g, createEntityId as h, MirrorVideoDocumentAdapter as i, findLaneTrack as j, LANE_KINDS_IN_STACK_ORDER as k, readVideoDocumentFromDraft as l, isJsonObject as m, createPlainMemoryAdapter as n, createMirrorVideoDocument as o, decodeEntityRelationRows as p, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as q, generatePartId as r, createMirrorVideoDocumentAdapter as s, PlainMemoryAdapter as t, bytesToBase64 as tt, projectEntityTimeline as u, isMediaAssetVariantKind as v, VideoDocumentValidationError as w, derivePositionFromAbs as x, buildInitialVideoDocument as y, resolveAllSpeechOverlaps as z };

package/dist/{index-CbuWTReu.d.ts → index-WxMNUbOa.d.ts}

@@ -487,7 +487,11 @@ type SpeechPart = Omit<SpeechPart$1, 'duration_ms'> & {
  *
  * `speech_part_id` / `start_ms` are kept as resource-intrinsic facts (which
  * speech it was split from, and its offset in that source) — reference/17
- * principle 4.
+ * principle 4. An independently placed Caption (its own Clip and Sequence
+ * Marker, no Voice take) has no owning speech: both fields stay unset and its
+ * position is expressed entirely by the Clip's placement. Generation source
+ * (AudioScript provenance) and Voice alignment are entity Relations, decoupled
+ * from this display-side legacy view.
  */
 type CaptionPart = Omit<CaptionPart$1, 'duration_ms'> & {
   initial_duration_ms?: number | undefined;
@@ -893,7 +897,7 @@ type JsonObject = {
 };
 //#endregion
 //#region ../medeo-dsl/src/relations.d.ts
-type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-provenance' | 'caption-provenance' | 'caption-alignment' | 'clip-anchor' | 'audio-script-render';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-provenance' | 'caption-provenance' | 'caption-alignment' | 'clip-anchor' | 'audio-script-render' | 'audio-script-source' | 'audio-script-marker';
 type RelationKind = KnownRelationKind | (string & {});
 type RelationTrace = JsonObject;
 /**
@@ -1606,7 +1610,7 @@ declare const partUnionSchema: z.ZodUnion<readonly [z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     kind: z.ZodLiteral<"caption">;
     initial_duration_ms: z.ZodNumber;
-    speech_part_id: z.ZodString;
+    speech_part_id: z.ZodOptional<z.ZodString>;
     text: z.ZodString;
     start_ms: z.ZodNumber;
     style: z.ZodOptional<z.ZodObject<{
@@ -1709,7 +1713,7 @@ declare const videoDocumentSchema: z.ZodObject<{
       id: z.ZodOptional<z.ZodString>;
       kind: z.ZodLiteral<"caption">;
       initial_duration_ms: z.ZodNumber;
-      speech_part_id: z.ZodString;
+      speech_part_id: z.ZodOptional<z.ZodString>;
       text: z.ZodString;
       start_ms: z.ZodNumber;
       style: z.ZodOptional<z.ZodObject<{
@@ -1736,4 +1740,4 @@ declare const videoDocumentSchema: z.ZodObject<{
   }, z.core.$loose>]>>>;
 }, z.core.$loose>;
 //#endregion
-export { EntityId as $, generatePartId as A, CaptionPart$1 as At, ResolvedEntityClipPlacement as B, PlannedSemanticOpKind as C, VideoDocumentValidationIssue as Ct, SnapshotReadable as D, effectiveVideoClipDurationMs as Dt, SchemaValidator as E, VideoDraftPartUnion as Et, videoDocumentMirrorSchema as F, Track$1 as Ft, EntityTimelineProjectionError as G, ResolvedEntityTrack as H, VideoDocumentValidationError as I, TrackItem$1 as It, JsonValue as J, EntityRelationRows as K, assertValidVideoDocument as L, TrackItemDraft as M, PartAggregation as Mt, VideoDocumentDraft as N, SpeedShift as Nt, ValidationError as O, speedOf as Ot, VideoDocumentMirrorSchema as P, Timeline$1 as Pt, VoiceDescriptor as Q, validateVideoDocument as R, ImplementedSemanticOpKind as S, VideoDocumentSchemaVersion as St, isImplementedSemanticOpKind as T, VideoDraft as Tt, resolveEntityTimelineLayout as U, ResolvedEntityTimelineLayout as V, projectEntityTimeline as W, SequenceDuration as X, CaptionStyleFields as Y, SequenceRange as Z, SemanticEditor as _, TrackItem as _t, PlainMemoryAdapter as a, derivePositionFromAbs as at, TransactAudit as b, VideoClipPart as bt, MirrorVideoDocumentAdapter as c, BgmPart as ct, createMirrorVideoDocument as d, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as dt, InitialDocumentFacts as et, createMirrorVideoDocumentAdapter as f, PartKind as ft, SemanticDocumentAdapter as g, Track as gt, OpActor as h, Timeline as ht, JournalEntry as i, buildSpeechHostMap as it, TrackDraft as j, CaptionStyle as jt, PartIdFactory as k, Attachment as kt, MirrorVideoDocumentOptions as l, CaptionPart as lt, CommitOptions as m, SpeechPart as mt, videoDocumentSchema as n, DerivedItemPosition as nt, PlainMemoryAdapterOptions as o, fromVideoDocument as ot, writeVideoDocumentToDraft as p, PartUnion as pt, JsonObject as q, readVideoDocumentFromDraft as r, SpeechHostMap as rt, createPlainMemoryAdapter as s, toVideoDocument as st, partUnionSchema as t, buildInitialVideoDocument as tt, applyEntityTimelineProjection as u, DEFAULT_UNIT_TIME_MS as ut, SemanticOpInput as v, TrackItemTimePosition as vt, SemanticOpKind as w, VideoDocumentValidationIssueCode as wt, IMPLEMENTED_SEMANTIC_OP_KINDS as x, VideoDocument as xt, SemanticOpName as y, VIDEO_DOCUMENT_SCHEMA_VERSION as yt, EntityTimelineTrackRole as z };
+export { VoiceDescriptor as $, generatePartId as A, Attachment as At, ResolvedEntityClipPlacement as B, PlannedSemanticOpKind as C, VideoDocumentSchemaVersion as Ct, SnapshotReadable as D, VideoDraftPartUnion as Dt, SchemaValidator as E, VideoDraft as Et, videoDocumentMirrorSchema as F, Timeline$1 as Ft, EntityTimelineProjectionError as G, ResolvedEntityTrack as H, VideoDocumentValidationError as I, Track$1 as It, JsonObject as J, EntityRelationRows as K, assertValidVideoDocument as L, TrackItem$1 as Lt, TrackItemDraft as M, CaptionStyle as Mt, VideoDocumentDraft as N, PartAggregation as Nt, ValidationError as O, effectiveVideoClipDurationMs as Ot, VideoDocumentMirrorSchema as P, SpeedShift as Pt, SequenceRange as Q, validateVideoDocument as R, ImplementedSemanticOpKind as S, VideoDocument as St, isImplementedSemanticOpKind as T, VideoDocumentValidationIssueCode as Tt, resolveEntityTimelineLayout as U, ResolvedEntityTimelineLayout as V, projectEntityTimeline as W, CaptionStyleFields as X, JsonValue as Y, SequenceDuration as Z, SemanticEditor as _, Track as _t, PlainMemoryAdapter as a, buildSpeechHostMap as at, TransactAudit as b, VIDEO_DOCUMENT_SCHEMA_VERSION as bt, MirrorVideoDocumentAdapter as c, toVideoDocument as ct, createMirrorVideoDocument as d, DEFAULT_UNIT_TIME_MS as dt, EntityId as et, createMirrorVideoDocumentAdapter as f, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as ft, SemanticDocumentAdapter as g, Timeline as gt, OpActor as h, SpeechPart as ht, JournalEntry as i, SpeechHostMap as it, TrackDraft as j, CaptionPart$1 as jt, PartIdFactory as k, speedOf as kt, MirrorVideoDocumentOptions as l, BgmPart as lt, CommitOptions as m, PartUnion as mt, videoDocumentSchema as n, buildInitialVideoDocument as nt, PlainMemoryAdapterOptions as o, derivePositionFromAbs as ot, writeVideoDocumentToDraft as p, PartKind as pt, EntityRow as q, readVideoDocumentFromDraft as r, DerivedItemPosition as rt, createPlainMemoryAdapter as s, fromVideoDocument as st, partUnionSchema as t, InitialDocumentFacts as tt, applyEntityTimelineProjection as u, CaptionPart as ut, SemanticOpInput as v, TrackItem as vt, SemanticOpKind as w, VideoDocumentValidationIssue as wt, IMPLEMENTED_SEMANTIC_OP_KINDS as x, VideoClipPart as xt, SemanticOpName as y, TrackItemTimePosition as yt, EntityTimelineTrackRole as z };