@mengine/medeo-tool 1.0.1-alpha.2 → 1.2.1-alpha.10

package/README.md

@@ -1,15 +1,16 @@
 # `@mengine/medeo-tool`
 
-Node tool surface for editing a Medeo video document through the deterministic
-edit sandbox.
+Node tool surface for editing the authoritative Medeo Entity/Relation graph
+through the deterministic edit sandbox. Timeline editing is entity editing,
+not a legacy document mutation followed by optional entity registration.
 
 The package owns the complete tool path:
 
 - compact snapshot projection;
 - trusted worker execution of an agent-authored JavaScript edit script;
-- op-journal `ChangePlan` caching;
-- versioned or per-op-preflight commit through `MengineDocSession`;
-- session cache and shutdown.
+- entity-command `ChangePlan` caching;
+- complete Entity/Relation snapshot reads and revision-CAS commits;
+- per-document serialization, document cache, and shutdown.
 
 A host supplies only environment facts: Mengine HTTP origin, optional request
 identity headers, `fetch`, and a stable agent peer id.
@@ -27,7 +28,8 @@ const snapshot = await medeo.handle({ op: 'snapshot', doc_id: docId });
 const run = await medeo.handle({
   op: 'run-edit-script',
   doc_id: docId,
-  script: 'await edit.deleteBgm({})',
+  script: 'edit.updateClip({ clipEntityId: inputs.clip_id, payload: { volume: -6 } })',
+  inputs: { clip_id: existingClipEntityId },
 });
 if (!run.ok || run.op !== 'run-edit-script') throw new Error('edit script failed');
 const commit = await medeo.handle({
@@ -36,9 +38,117 @@ const commit = await medeo.handle({
   plan_id: run.plan_id,
 });
 
+// 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',
+  doc_id: docId,
+  inputs: { output_asset_id: 'asset-from-host', track_entity_id: existingTrackEntityId },
+  script: `
+if (typeof inputs.output_asset_id !== 'string' || typeof inputs.track_entity_id !== 'string') {
+  throw new Error('missing recalled generation facts');
+}
+const { contentEntityId: output } = entities.ensureMedia({
+  assetId: inputs.output_asset_id,
+  kind: 'image',
+});
+edit.insertClip({
+  trackEntityId: inputs.track_entity_id,
+  contentEntityId: output,
+  sourceRange: { start: 0, end: 1 },
+  duration: { mode: 'fixed', value: 5000 },
+  targetRange: { start: 0, end: 5000 },
+});
+  `,
+});
+
 await medeo.close();
 ```
 
 The sandbox has no network, storage, clock, or generation access. Materialize
-speech/media side effects in the host first and pass stable facts through
-`inputs`.
+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 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, 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
+references are Relations. There is no separate orientation or timing profile.
+
+The server validates and commits the graph and its read-only Loro projection in
+one database transaction. `deleted_entity_ids` and `deleted_relation_ids` make
+deletion explicit; dropped rows without deletion intent are rejected. After
+cutover, raw Loro `/updates` cannot mutate the document. Legacy standalone
+sandbox exports remain library compatibility APIs, not a production-tool mode.
+
+Existing nonempty legacy documents require a separate version-CAS migration
+whose projection preserves existing editing facts. `snapshot` identifies that
+requirement and the media IDs needing factual metadata. Call
+`{op:'migrate-legacy',doc_id,asset_facts}` explicitly, then take a fresh snapshot
+before editing. The package reads the canonical document and current Loro
+version itself; it does not accept a caller-supplied snapshot or version, use a
+stale cached document after a failed pull, or combine migration with a new edit.
+Repeating migration on an entity timeline is read-only. An uncertain submission
+must be inspected and retried, never reported as committed.
+
+The compatibility reader covers the existing four lanes: Image/Video, Voice,
+Caption, and background Audio. Coordinates are whole milliseconds for this
+reader. It preserves linear visual remapping (`{kind:'linear',rate:2}`), including
+image display speed, and explicit anchor chains. Nonlinear remapping and multiple
+visual overlay tracks are not existing editor features and remain unsupported.

package/dist/entity-contract-C5HHaYKk.d.mts

@@ -0,0 +1,228 @@
+import { MediaAssetFact } from "@mengine/medeo-client";
+
+//#region src/entity/entity-contract.d.ts
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+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' | 'voice';
+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 AuthorableRelationKind = Exclude<KnownRelationKind, 'generated'>;
+interface BoundedNativeSequencePayload extends JsonObject {
+  /** Factual coordinates from recalled media metadata; never invent an end/duration. */
+  extent: {
+    kind: 'bounded';
+    start: number;
+    end: number;
+  };
+  sampling: 'native';
+  coordinateSpace: JsonValue;
+}
+interface UnboundedConstantSequencePayload extends JsonObject {
+  extent: {
+    kind: 'unbounded';
+    start: number;
+  };
+  sampling: 'constant';
+  coordinateSpace: JsonValue;
+}
+interface BoundedDerivedSequencePayload extends JsonObject {
+  extent: {
+    kind: 'bounded';
+    start: number;
+    end: number;
+  };
+  sampling: 'derived';
+  coordinateSpace: JsonValue;
+}
+type ScriptTextSegment = JsonObject & {
+  segmentId: string;
+  text: string;
+  language?: string;
+};
+type MediaAssetPayload = JsonObject & {
+  external: {
+    system: 'memota' | 'memota-speech';
+    key: string;
+  };
+  storageKey?: string;
+};
+interface EntityPayloadByKind {
+  axvideo: BoundedDerivedSequencePayload;
+  timeline: JsonObject;
+  track: JsonObject & {
+    hidden?: boolean;
+    role?: string;
+  };
+  clip: JsonObject;
+  /** Inline caption text; external media uses a typed Asset variant. */
+  asset: JsonObject;
+  video: BoundedNativeSequencePayload & MediaAssetPayload;
+  audio: BoundedNativeSequencePayload & MediaAssetPayload;
+  voice: BoundedNativeSequencePayload & MediaAssetPayload;
+  image: UnboundedConstantSequencePayload & MediaAssetPayload;
+  'sequence-marker': JsonObject & {
+    sourceRange: {
+      start: number;
+      end: number;
+    };
+    targetRange?: {
+      start: number;
+      end: number;
+    };
+    duration: {
+      mode: 'from-source';
+    } | {
+      mode: 'fixed';
+      value: number;
+    };
+    timeRemapping?: JsonValue;
+    anchorOffset?: number;
+    durationPolicy?: 'timeline';
+  };
+  viewport: JsonObject;
+  'audio-script': JsonObject & {
+    segments: ScriptTextSegment[];
+  };
+  'phonetic-script': JsonObject & {
+    segments: ScriptTextSegment[];
+  };
+  caption: BoundedNativeSequencePayload;
+}
+interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {
+  entity_id: string;
+  entity_kind: K;
+  payload: EntityPayloadByKind[K];
+}
+interface SandboxRelation {
+  relation_id: string;
+  relation_kind: KnownRelationKind;
+  endpoint_0_entity_id: string;
+  endpoint_1_entity_id: string;
+  metadata: JsonObject;
+  trace: JsonObject;
+}
+interface EntityStoreSnapshot {
+  revision: number;
+  entities: SandboxEntity[];
+  relations: SandboxRelation[];
+}
+type CreateEntityInput = { [K in KnownEntityKind]: {
+  entity_id?: string;
+  entity_kind: K;
+  payload: EntityPayloadByKind[K];
+} }[KnownEntityKind];
+interface UpdateEntityInput {
+  entity_id: string;
+  payload: JsonObject;
+}
+interface DeleteEntityInput {
+  entity_id: string;
+}
+type EmptyRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline';
+interface LinkRelationBase {
+  relation_id?: string;
+  endpoint_0_entity_id: string;
+  endpoint_1_entity_id: string;
+  trace?: JsonObject;
+}
+type LinkRelationInput = (LinkRelationBase & {
+  relation_kind: EmptyRelationKind;
+  metadata?: {
+    [key: string]: never;
+  };
+}) | (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 & {
+    alignment: JsonValue;
+  };
+});
+interface LinkGeneratedRelationInput {
+  relation_id?: string;
+  output_entity_id: string;
+  input_entity_id: string;
+  trace?: JsonObject;
+}
+interface LinkClipAnchorRelationInput {
+  relation_id?: string;
+  child_clip_entity_id: string;
+  host_clip_entity_id: string;
+  trace?: JsonObject;
+}
+interface LinkAudioScriptRenderRelationInput {
+  relation_id?: string;
+  output_entity_id: string;
+  script_entity_id: string;
+  trace?: JsonObject;
+}
+interface UnlinkRelationInput {
+  relation_id: string;
+}
+type EntityCommand = {
+  kind: 'create-entity';
+  entity: SandboxEntity;
+} | {
+  kind: 'update-entity';
+  entity_id: string;
+  payload: JsonObject;
+} | {
+  kind: 'delete-entity';
+  entity_id: string;
+} | {
+  kind: 'link-relation';
+  relation: SandboxRelation;
+} | {
+  kind: 'unlink-relation';
+  relation_id: string;
+};
+interface EntityPlanState {
+  base_revision: number;
+  commands: readonly EntityCommand[];
+  rows: EntityStoreSnapshot;
+  deleted_entity_ids: readonly string[];
+  deleted_relation_ids: readonly string[];
+}
+interface EntityFacade {
+  list(): SandboxEntity[];
+  get(entityId: string): SandboxEntity | null;
+  /** Find document resources by external Memota asset id, including directly composed media variants. */
+  findByAssetId(assetId: string): SandboxEntity<ResourceEntityKind>[];
+  create(input: CreateEntityInput): string;
+  /** Replace one Entity's owned payload without changing its identity or kind. */
+  update(input: UpdateEntityInput): void;
+  /** Delete an Entity only after all of its incident Relations have been explicitly unlinked. */
+  delete(input: DeleteEntityInput): void;
+  /** 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[];
+  /** physical-asset binds inline Caption text, never external media. */
+  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;
+  /** 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, 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-C5HHaYKk.d.mts.map