@mengine/medeo-tool 2.0.1-alpha.11 → 2.0.1-alpha.13

package/dist/{entity-contract-Cf3AiSe7.d.mts → entity-contract-Dy0cozPt.d.mts}

@@ -9,7 +9,7 @@ interface JsonObject {
 type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
 /** Asset identity, either an old physical-only row or a directly composed media variant. */
 type ResourceEntityKind = 'image' | 'video' | 'audio';
-type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'from-asset' | 'generated' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'voice-timbre' | 'audio-script-source' | 'audio-script-marker';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'from-asset' | 'to-asset' | 'generated' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'voice-timbre' | 'audio-script-source' | 'audio-script-marker';
 type AuthorableRelationKind = KnownRelationKind;
 /**
  * Content states how long it runs and nothing else: where it is taken from and
@@ -58,7 +58,7 @@ interface EntityPayloadByKind {
     role?: string;
   };
   clip: JsonObject;
-  /** Where the bytes live. Reached from other entities by from-asset. */
+  /** Where the bytes live. Reached from other entities by from-asset or to-asset. */
   asset: AssetPayload;
   video: OwnDurationPayload;
   /** Every playable sound, including video original audio and synthesized voiceovers. */
@@ -147,6 +147,18 @@ type CreateEntityInput = { [K in KnownEntityKind]: {
   entity_id?: string;
   entity_kind: K;
   payload: StoredEntityPayload<K>;
+  /**
+   * The stored resource this entity is made from.
+   *
+   * Naming it here is the only way to say where an entity's bytes come from:
+   * the Asset row and the `from-asset` Relation that reaches it are assembled
+   * by the host, never authored. Only a kind that declares `Asset` — video,
+   * audio, image, caption, audio-script, phonetic-script — accepts one.
+   */
+  asset?: {
+    system: 'memota' | 'memota-speech';
+    key: string;
+  };
 } }[KnownEntityKind];
 /** Patch supplied fields on the assembled entity; omitted fields remain unchanged. */
 interface UpdateEntityInput {
@@ -240,4 +252,4 @@ interface BusinessRelationFacade {
 }
 //#endregion
 export { UpdateEntityInput as C, UnlinkRelationInput as S, LinkRelationInput as _, DeleteEntityInput as a, SandboxEntity as b, EntitySandboxCheckpoint as c, JsonObject as d, JsonPrimitive as f, LinkGeneratedRelationInput as g, KnownRelationKind as h, CreateEntityInput as i, EntityStoreSnapshot as l, KnownEntityKind as m, BusinessEntityFacade as n, EntityCommand as o, JsonValue as p, BusinessRelationFacade as r, EntityPlanState as s, AuthorableRelationKind as t, EntityUpdateInput as u, RelationUpdateInput as v, SandboxRelation as x, ResourceEntityKind as y };
-//# sourceMappingURL=entity-contract-Cf3AiSe7.d.mts.map
+//# sourceMappingURL=entity-contract-Dy0cozPt.d.mts.map

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

@@ -15,8 +15,9 @@ import { applyFieldChanges, assertCanonicalEditorResources, assertFieldChanges,
 * `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.
+* `Asset` says only that an entity of that kind may be bound to stored bytes,
+* and asks nothing of its payload. Which bytes, and which way the content
+* flowed, is the `from-asset` / `to-asset` Relation's answer alone.
 */
 const ENTITY_KINDS = Object.freeze({
 	axvideo: Object.freeze([
@@ -33,27 +34,27 @@ const ENTITY_KINDS = Object.freeze({
 		"Sequence",
 		"Visual",
 		"Audible",
-		"FromAsset"
+		"Asset"
 	]),
 	audio: Object.freeze([
 		"Sequence",
 		"Audible",
-		"FromAsset"
+		"Asset"
 	]),
 	image: Object.freeze([
 		"Sequence",
 		"Visual",
-		"FromAsset"
+		"Asset"
 	]),
 	voice: Object.freeze(["Container", "IPBound"]),
 	"sequence-marker": Object.freeze([]),
 	viewport: Object.freeze([]),
-	"audio-script": Object.freeze(["SegmentText", "FromAsset"]),
-	"phonetic-script": Object.freeze(["SegmentText"]),
+	"audio-script": Object.freeze(["SegmentText", "Asset"]),
+	"phonetic-script": Object.freeze(["SegmentText", "Asset"]),
 	caption: Object.freeze([
 		"SegmentText",
 		"Sequence",
-		"FromAsset"
+		"Asset"
 	])
 });
 /** What a known kind declares; extension kinds declare nothing through this table. */
@@ -347,15 +348,6 @@ function entityToRow(entity) {
 //#endregion
 //#region ../medeo-dsl/src/invariants.ts
 /** 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: `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) {
 	const { entities, issues } = collectRelatedEntities(entityRefs, index);
@@ -377,7 +369,6 @@ function validateEntityRelationSet(entityRefs, index, options) {
 		const current = entity.current();
 		const entityIssues = validateEntity(entity, entityIds);
 		issues.push(...entityIssues);
-		issues.push(...validateAssetSource(entity, index));
 		if (entityIssues.some((issue) => issue.code === "invalid_entity_payload")) continue;
 		if (current.entityKind === "sequence-marker") {
 			const marker = entity;
@@ -1021,10 +1012,10 @@ const markerContentRelationSpec = Object.freeze({
 /**
 * `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
+* Eligibility is declared: the non-Asset endpoint must carry the `Asset` kind,
+* which says an entity of that kind can be bound to 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({
@@ -1032,6 +1023,26 @@ const fromAssetRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => hasExactlyOneAsset(endpoints),
 	validateMetadata: isAssetBinding
 });
+/**
+* `to-asset(entity, asset)` — the entity's content was written out to that
+* stored resource.
+*
+* The mirror of `from-asset`, and deliberately a separate relation kind rather
+* than a second declared kind: eligibility is the same either way, but which
+* way the content flowed is what says whether an entity may still be edited.
+* An entity reached by `from-asset` was produced from bytes it does not own,
+* so changing it would contradict them. An entity with a `to-asset` owns its
+* content and the resource is a snapshot of it, which is what goes stale and
+* gets written again. A transcript that is later edited carries both at once,
+* and only the distinct relation kinds keep them apart.
+*
+* Writing a snapshot is host assembly; nothing a script authors creates one.
+*/
+const toAssetRelationSpec = Object.freeze({
+	kind: "to-asset",
+	validateEndpoints: (endpoints) => hasExactlyOneAsset(endpoints),
+	validateMetadata: isAssetBinding
+});
 /** `generated(output, input)` means endpoint 0 was generated from endpoint 1. */
 const generatedRelationSpec = Object.freeze({
 	kind: "generated",
@@ -1094,6 +1105,7 @@ const builtInRelationSpecs = Object.freeze([
 	axVideoMarkerRelationSpec,
 	markerTimelineRelationSpec,
 	fromAssetRelationSpec,
+	toAssetRelationSpec,
 	generatedRelationSpec,
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
@@ -1122,12 +1134,12 @@ function hasMarkerAndSequence(endpoints) {
 	const second = endpoints[1].current();
 	return first.entityKind === "sequence-marker" && hasSequence(second) || second.entityKind === "sequence-marker" && hasSequence(first);
 }
-/** Exactly one end is the Asset, so the other end is unambiguously the maker. */
+/** Exactly one end is the Asset, so the other end is unambiguously the bound entity. */
 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");
+	return declaresKind(assets[0] ? kinds[1] : kinds[0], "Asset");
 }
 function isGeneratedMedia(entity) {
 	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio";
@@ -1467,6 +1479,8 @@ function errorMessage(error) {
 //#region src/sandbox/business-facades.ts
 /** Resource IDs are entity data; physical storage paths remain host-owned. */
 const infrastructureFields = new Set(["storageKey", "assetContentHash"]);
+/** Both directions of an Asset binding are host assembly, whoever asks. */
+const assetBindingKinds = new Set(["from-asset", "to-asset"]);
 function businessEntity(entity) {
 	return {
 		...entity,
@@ -1479,7 +1493,17 @@ 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 !== "from-asset" && !assets.has(row.endpoint_0_entity_id) && !assets.has(row.endpoint_1_entity_id))
+		relations: state.relations.filter((row) => !assetBindingKinds.has(row.relation_kind) && !assets.has(row.endpoint_0_entity_id) && !assets.has(row.endpoint_1_entity_id))
+	};
+}
+/** Only a kind that declares Asset can be bound to stored bytes. */
+function assetLocator(value, entityKind) {
+	if (!declaresKind(entityKind, "Asset")) throw new Error(`Entity kind "${entityKind}" cannot be made from an Asset`);
+	if (!isJsonObject(value) || value.system !== "memota" && value.system !== "memota-speech") throw new Error("asset.system must be \"memota\" or \"memota-speech\"");
+	if (typeof value.key !== "string" || value.key.trim() !== value.key || value.key === "") throw new Error("asset.key must be a trimmed, non-empty resource id");
+	return {
+		system: value.system,
+		key: value.key
 	};
 }
 /** Keep infrastructure rows available to assembly without exposing their management to scripts. */
@@ -1494,7 +1518,7 @@ function businessFacades(entities, relations, onDirectScriptWrite) {
 			for (const id of payload.baseEntityIds) if (typeof id === "string") assertBusiness(id);
 		}
 	};
-	const visibleRelation = (relation) => relation.relation_kind !== "from-asset" && !isAsset(relation.endpoint_0_entity_id) && !isAsset(relation.endpoint_1_entity_id);
+	const visibleRelation = (relation) => !assetBindingKinds.has(relation.relation_kind) && !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),
@@ -1506,7 +1530,14 @@ function businessFacades(entities, relations, onDirectScriptWrite) {
 				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`);
-				const id = entities.create(input);
+				const asset = input.asset === void 0 ? void 0 : assetLocator(input.asset, input.entity_kind);
+				const { asset: _named, ...row } = input;
+				const id = entities.create(row);
+				if (asset !== void 0) relations.link({
+					relation_kind: "from-asset",
+					endpoint_0_entity_id: id,
+					endpoint_1_entity_id: entities.ensureAsset(asset)
+				});
 				if (input.entity_kind === "audio-script") onDirectScriptWrite?.(id);
 				return id;
 			},
@@ -1541,7 +1572,7 @@ function businessFacades(entities, relations, onDirectScriptWrite) {
 			list: () => relations.list().filter(visibleRelation),
 			of: (id, kind) => relations.of(id, kind).filter(visibleRelation),
 			link: (input) => {
-				if (input.relation_kind === "from-asset") throw new Error("Asset bindings are managed by host assembly");
+				if (assetBindingKinds.has(input.relation_kind)) 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);
@@ -1630,7 +1661,7 @@ var EntitySandbox = class {
 		decodeEntityRelationRows(rows, numericMarkerComparators);
 		if (this.state.revision !== 0 || rows.entities.length !== 0 || this.commands.length !== 0) {
 			assertCanonicalEditorResources(rows);
-			readDocumentAudioScript({
+			if (this.state.audioScriptEntityId !== null) readDocumentAudioScript({
 				rows,
 				audioScriptEntityId: this.state.audioScriptEntityId
 			});
@@ -1896,7 +1927,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" && row.relationKind !== "voice-timbre" && row.relationKind !== "from-asset") throw new Error(`Unexpected resource Relation ${row.relationKind}`);
+			if (row.relationKind !== "timeline-track" && row.relationKind !== "voice-timbre" && row.relationKind !== "from-asset" && row.relationKind !== "to-asset") throw new Error(`Unexpected resource Relation ${row.relationKind}`);
 			this.link({
 				relation_id: row.relationId,
 				relation_kind: row.relationKind,
@@ -2202,4 +2233,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-BTR2cRl1.mjs.map
+//# sourceMappingURL=entity-sandbox-CulJBYrI.mjs.map