@mengine/medeo-tool 1.2.1-alpha.8 → 1.3.1-alpha.6

package/README.md

@@ -38,7 +38,7 @@ const commit = await medeo.handle({
   plan_id: run.plan_id,
 });
 
-// Generation facts are recalled by the host and passed into the sandbox.
+// Media facts are recalled by the host and passed into the sandbox.
 // This example is text-to-image: there is no invented input-media entity.
 const entityRun = await medeo.handle({
   op: 'run-edit-script',
@@ -48,12 +48,10 @@ const entityRun = await medeo.handle({
 if (typeof inputs.output_asset_id !== 'string' || typeof inputs.track_entity_id !== 'string') {
   throw new Error('missing recalled generation facts');
 }
-const asset = entities.importAsset({ asset_id: inputs.output_asset_id });
-const output = entities.create({
-  entity_kind: 'image',
-  payload: { extent: { kind: 'unbounded', start: 0 }, sampling: 'constant', coordinateSpace: 'ms' },
+const { contentEntityId: output } = entities.ensureMedia({
+  assetId: inputs.output_asset_id,
+  kind: 'image',
 });
-relations.link({ relation_kind: 'physical-asset', endpoint_0_entity_id: output, endpoint_1_entity_id: asset });
 edit.insertClip({
   trackEntityId: inputs.track_entity_id,
   contentEntityId: output,
@@ -70,15 +68,64 @@ await medeo.close();
 The sandbox has no network, storage, clock, or generation access. Materialize
 or recall speech/media side effects in the host first and pass stable facts
 through `inputs`. There is no automatic Asset→Entity projection: the model
-selects and imports assets, creates only known typed Entities, and links them
-explicitly. Assets and media Entities are intentionally not one-to-one.
+selects when to bring a recalled asset into the editor through `entities.ensureMedia`.
+The resolver gets or creates one typed Asset by external `(system, key)` within
+the document. Image/Video/Audio/Voice are logical Asset variants: the typed row
+directly owns `external`, `storageKey` and its media fields, and its Asset ID is
+also its content Entity ID. Imports create no separate physical-only Asset
+row and no `physical-asset` relation. Raw typed resource creation also reuses
+an existing identity; prefer `ensureMedia` with the recalled media kind.
+`findByAssetId` includes Voice (`memota-speech`) variants. There is no separate
+`importAsset` API.
+Generation facts currently carry bare asset IDs. If a returned fact matches
+both media and speech namespaces, synchronization fails explicitly without
+writing ambiguous lineage edges.
+Conflicting facts or duplicate candidates fail explicitly; no automatic
+merge or deletion occurs. This is the MEngine editor profile, not a global DSL
+cardinality rule. Separate Asset+media graphs are invalid: every media variant
+must directly own its external identity, with no read fallback or migration.
+Inline caption Assets without external identity are not deduplicated.
+
+Before model context/snapshot/editing, the host ensures one Timeline and the four
+fixed Tracks (`video_clip`, `speech`, `caption`, `bgm`). Existing IDs, settings and
+relations are retained; repeated calls add no rows or revisions. First initialization
+uses revision CAS and may write. An empty legacy draft is initialized through the
+version-guarded migration path to preserve configured track identities/visibility;
+non-empty legacy content still requires explicit `migrate-legacy`. Missing Tracks
+are filled in a subsequent CAS when necessary. A lost initialization response is
+reconciled by a fresh snapshot, never by assuming success.
+
+Each placement still creates an independent Clip and SequenceMarker. Reusing a
+media variant does not share per-placement trim, speed, volume or placement state.
 
 The production tool exposes native Clip/Marker editing plus visual placement,
 voiceover, caption, and BGM helpers through its generated sandbox interface.
 They preserve structural and anchor relations in the same plan. Timeline targets
-are Entity IDs, never raw asset IDs or URLs. Asset import, media creation, factual `generated` relations, and Clip
-insertion belong in the **same entity plan**. `generated` retains output at
-endpoint 0 and input at endpoint 1, while lookup can use either endpoint.
+are Entity IDs, never raw asset IDs or URLs. Asset import, media creation, and
+Clip insertion belong in the **same entity plan**.
+
+Generation lineage is program-synced, not model-authored. After a confirmed
+entity commit the tool resolves the plan's diff against host-supplied generation
+facts and commits missing `generated` Relations between fact-matched media
+Entities already present in the document (endpoint 0 output, endpoint 1 input;
+lookup can use either endpoint). The diff covers newly exposed media Asset
+identities; placement-only edits and
+pairs already fact-resolvable before the plan stay untouched. Models
+do not pass generation history through inputs — the host queries it with
+`loadGenerationFacts(docId, assetIds)`, returning every known generation record
+involving the given asset ids in either role. Each record must carry an explicit
+`inputAssetIds` array: an explicit empty array declares text-only generation
+with no lineage edge, while a missing or non-array field is a malformed record
+that fails the whole query instead of being silently read as text-only.
+One-sided facts are skipped without creating entities or blocking the commit —
+lineage sync never backfills a missing source or output Entity; entity creation
+stays a model decision inside the edit plan. Repeated commits are idempotent,
+and deletions and revision conflicts are respected: a CAS-conflict retry reads
+the fresh graph and recomputes missing edges without recreating deleted endpoints.
+Asset identities are immutable, so each synchronization queries its facts once.
+An empty result array means no known lineage; a rejection means the lineage
+query failed and is reported as `generation_sync: {status:'failed'}` plus a
+`generation_sync_failed` warning — never as synced state.
 
 Entities own their facts: SequenceMarker owns source/target ranges, duration,
 and time remapping; Clip owns volume; Track owns role/visibility. Cross-entity

package/dist/{entity-contract-DycLxdQ5.d.mts → entity-contract-hKZbJSRP.d.mts}

@@ -1,3 +1,5 @@
+import { MediaAssetFact } from "@mengine/medeo-client";
+
 //#region src/entity/entity-contract.d.ts
 type JsonPrimitive = string | number | boolean | null;
 type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
@@ -5,7 +7,9 @@ interface JsonObject {
   [key: string]: JsonValue;
 }
 type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
-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';
+/** Asset identity, either an old physical-only row or a directly composed media variant. */
+type ResourceEntityKind = 'image' | 'video' | 'audio' | 'voice';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'audio-script-source' | 'audio-script-marker';
 type AuthorableRelationKind = Exclude<KnownRelationKind, 'generated'>;
 interface BoundedNativeSequencePayload extends JsonObject {
   /** Factual coordinates from recalled media metadata; never invent an end/duration. */
@@ -39,6 +43,30 @@ type ScriptTextSegment = JsonObject & {
   text: string;
   language?: string;
 };
+type MediaAssetPayload = JsonObject & {
+  external: {
+    system: 'memota' | 'memota-speech';
+    key: string;
+  };
+  storageKey?: string;
+};
+type CaptionTextSelection = JsonObject & {
+  segmentId: string; /** Half-open Unicode code-point range within the selected source segment. */
+  textRange?: {
+    start: number;
+    end: number;
+  };
+};
+/** Read result only: base text is assembled from the real AudioScript row. */
+interface ComposedScriptContent {
+  audio_script_entity_id: string;
+  text: string;
+  segments: ScriptTextSegment[];
+}
+interface ComposedPhoneticContent extends ComposedScriptContent {
+  phonemeScript?: string;
+  prosody?: JsonObject;
+}
 interface EntityPayloadByKind {
   axvideo: BoundedDerivedSequencePayload;
   timeline: JsonObject;
@@ -47,12 +75,12 @@ interface EntityPayloadByKind {
     role?: string;
   };
   clip: JsonObject;
-  /** Asset-owned metadata. Peer media associations belong in physical-asset Relations. */
+  /** Physical resource fields; never a copy of Caption content. */
   asset: JsonObject;
-  video: BoundedNativeSequencePayload;
-  audio: BoundedNativeSequencePayload;
-  voice: BoundedNativeSequencePayload;
-  image: UnboundedConstantSequencePayload;
+  video: BoundedNativeSequencePayload & MediaAssetPayload;
+  audio: BoundedNativeSequencePayload & MediaAssetPayload;
+  voice: BoundedNativeSequencePayload & MediaAssetPayload;
+  image: UnboundedConstantSequencePayload & MediaAssetPayload;
   'sequence-marker': JsonObject & {
     sourceRange: {
       start: number;
@@ -70,21 +98,36 @@ interface EntityPayloadByKind {
     };
     timeRemapping?: JsonValue;
     anchorOffset?: number;
-    durationPolicy?: 'timeline';
+    durationPolicy?: 'timeline'; /** Directly assigned AudioScript annotation times; annotation Markers only. */
+    segmentRanges?: {
+      segmentId: string;
+      startMs: number;
+      endMs: number;
+    }[];
   };
   viewport: JsonObject;
   'audio-script': JsonObject & {
     segments: ScriptTextSegment[];
   };
   'phonetic-script': JsonObject & {
-    segments: ScriptTextSegment[];
+    baseEntityIds: string[];
+    phonemeScript?: string;
+    prosody?: JsonObject;
+  };
+  caption: BoundedNativeSequencePayload & {
+    baseEntityIds: string[];
+    selections: CaptionTextSelection[];
+    style?: JsonObject;
   };
-  caption: BoundedNativeSequencePayload;
 }
+/** Stored own fields; a variant may obtain required content fields from its declared bases. */
+type StoredEntityPayload<K extends KnownEntityKind> = EntityPayloadByKind[K] | (JsonObject & Partial<EntityPayloadByKind[K]> & {
+  baseEntityIds: string[];
+});
 interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {
   entity_id: string;
   entity_kind: K;
-  payload: EntityPayloadByKind[K];
+  payload: StoredEntityPayload<K>;
 }
 interface SandboxRelation {
   relation_id: string;
@@ -102,8 +145,9 @@ interface EntityStoreSnapshot {
 type CreateEntityInput = { [K in KnownEntityKind]: {
   entity_id?: string;
   entity_kind: K;
-  payload: EntityPayloadByKind[K];
+  payload: StoredEntityPayload<K>;
 } }[KnownEntityKind];
+/** Patch supplied fields on the assembled entity; omitted fields remain unchanged. */
 interface UpdateEntityInput {
   entity_id: string;
   payload: JsonObject;
@@ -111,12 +155,7 @@ interface UpdateEntityInput {
 interface DeleteEntityInput {
   entity_id: string;
 }
-interface ImportAssetInput {
-  asset_id: string;
-  entity_id?: string;
-  payload?: JsonObject;
-}
-type EmptyRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline';
+type EmptyRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'audio-script-marker';
 interface LinkRelationBase {
   relation_id?: string;
   endpoint_0_entity_id: string;
@@ -131,11 +170,6 @@ type LinkRelationInput = (LinkRelationBase & {
 }) | (LinkRelationBase & {
   relation_kind: 'physical-asset';
   metadata?: JsonObject;
-}) | (LinkRelationBase & {
-  relation_kind: 'phonetic-script-provenance' | 'caption-provenance';
-  metadata: JsonObject & {
-    segmentAlignment: JsonValue;
-  };
 }) | (LinkRelationBase & {
   relation_kind: 'caption-alignment';
   metadata: JsonObject & {
@@ -154,10 +188,17 @@ interface LinkClipAnchorRelationInput {
   host_clip_entity_id: string;
   trace?: JsonObject;
 }
-interface LinkAudioScriptRenderRelationInput {
+interface LinkPhoneticScriptRenderRelationInput {
   relation_id?: string;
   output_entity_id: string;
+  phonetic_script_entity_id: string;
+  trace?: JsonObject;
+}
+/** `audio-script-source(script, source)`; the script was transcribed from the source media. */
+interface LinkAudioScriptSourceRelationInput {
+  relation_id?: string;
   script_entity_id: string;
+  source_entity_id: string;
   trace?: JsonObject;
 }
 interface UnlinkRelationInput {
@@ -188,33 +229,44 @@ interface EntityPlanState {
   deleted_relation_ids: readonly string[];
 }
 interface EntityFacade {
+  /** Read complete assembled fields; returned objects are snapshots. Use update to persist edits. */
   list(): SandboxEntity[];
   get(entityId: string): SandboxEntity | null;
-  /** Return every explicitly imported Asset entity for a Memota asset id. */
-  findByAssetId(assetId: string): SandboxEntity<'asset'>[];
+  /** Find document resources by external Memota asset id, including directly composed media variants. */
+  findByAssetId(assetId: string): SandboxEntity<ResourceEntityKind>[];
+  /** Assemble selected Caption text; missing composition is an error. */
+  readCaptionContent(entityId: string): ComposedScriptContent;
+  /** Assemble base text and pronunciation fields before generating Voice. */
+  readPhoneticScriptContent(entityId: string): ComposedPhoneticContent;
   create(input: CreateEntityInput): string;
-  /** Replace one Entity's owned payload without changing its identity or kind. */
+  /** Patch assembled fields, routing inherited fields to their declaring entity. */
   update(input: UpdateEntityInput): void;
+  /** Explicitly declare own fields, overriding unambiguous bases without modifying them. Ordinary edits use update. */
+  declareFields(input: UpdateEntityInput): void;
   /** Delete an Entity only after all of its incident Relations have been explicitly unlinked. */
   delete(input: DeleteEntityInput): void;
-  /** Import one physical asset without implying a one-to-one media Entity mapping. */
-  importAsset(input: ImportAssetInput): string;
+  /** Get or create one typed Asset by factual external id and return its single content identity. Never creates a Clip. */
+  ensureMedia(fact: MediaAssetFact): {
+    contentEntityId: string;
+  };
 }
 interface RelationFacade {
   list(): SandboxRelation[];
   /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */
   of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];
-  /** For physical-asset use sequence media as endpoint 0 and Asset as endpoint 1. */
+  /** Link existing entities through ordinary associations; variant bases are stored directly on the variant. */
   link(input: LinkRelationInput): string;
   /** Author ordered generated(output,input); generic link() deliberately rejects this kind. */
   linkGenerated(input: LinkGeneratedRelationInput): string;
   /** Author ordered clip-anchor(child,host) without positional endpoint ambiguity. */
   linkClipAnchor(input: LinkClipAnchorRelationInput): string;
-  /** Author ordered audio-script-render(output,script) without positional endpoint ambiguity. */
-  linkAudioScriptRender(input: LinkAudioScriptRenderRelationInput): string;
+  /** Author ordered phonetic-script-render(output,script) without positional endpoint ambiguity. */
+  linkPhoneticScriptRender(input: LinkPhoneticScriptRenderRelationInput): string;
+  /** Author ordered audio-script-source(script,source) without positional endpoint ambiguity. */
+  linkAudioScriptSource(input: LinkAudioScriptSourceRelationInput): string;
   /** Remove a Relation by identity; endpoint replacement is an explicit unlink plus link. */
   unlink(input: UnlinkRelationInput): void;
 }
 //#endregion
-export { SandboxEntity as _, EntityFacade as a, UpdateEntityInput as b, ImportAssetInput as c, JsonValue as d, KnownEntityKind as f, RelationFacade as g, LinkRelationInput as h, EntityCommand as i, JsonObject as l, LinkGeneratedRelationInput as m, CreateEntityInput as n, EntityPlanState as o, KnownRelationKind as p, DeleteEntityInput as r, EntityStoreSnapshot as s, AuthorableRelationKind as t, JsonPrimitive as u, SandboxRelation as v, UnlinkRelationInput as y };
-//# sourceMappingURL=entity-contract-DycLxdQ5.d.mts.map
+export { SandboxEntity as _, EntityFacade as a, UpdateEntityInput as b, JsonObject as c, KnownEntityKind as d, KnownRelationKind as f, ResourceEntityKind as g, RelationFacade as h, EntityCommand as i, JsonPrimitive as l, LinkRelationInput as m, CreateEntityInput as n, EntityPlanState as o, LinkGeneratedRelationInput as p, DeleteEntityInput as r, EntityStoreSnapshot as s, AuthorableRelationKind as t, JsonValue as u, SandboxRelation as v, UnlinkRelationInput as y };
+//# sourceMappingURL=entity-contract-hKZbJSRP.d.mts.map