@mengine/medeo-tool 1.2.1-alpha.0 → 1.2.1-alpha.8

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,70 @@ const commit = await medeo.handle({
   plan_id: run.plan_id,
 });
 
+// Generation 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 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' },
+});
+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,
+  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 and imports assets, creates only known typed Entities, and links them
+explicitly. Assets and media Entities are intentionally not one-to-one.
+
+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.
+
+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-DycLxdQ5.d.mts

@@ -0,0 +1,220 @@
+//#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';
+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;
+};
+interface EntityPayloadByKind {
+  axvideo: BoundedDerivedSequencePayload;
+  timeline: JsonObject;
+  track: JsonObject & {
+    hidden?: boolean;
+    role?: string;
+  };
+  clip: JsonObject;
+  /** Asset-owned metadata. Peer media associations belong in physical-asset Relations. */
+  asset: JsonObject;
+  video: BoundedNativeSequencePayload;
+  audio: BoundedNativeSequencePayload;
+  voice: BoundedNativeSequencePayload;
+  image: UnboundedConstantSequencePayload;
+  '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;
+}
+interface ImportAssetInput {
+  asset_id: string;
+  entity_id?: string;
+  payload?: JsonObject;
+}
+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;
+  /** Return every explicitly imported Asset entity for a Memota asset id. */
+  findByAssetId(assetId: string): SandboxEntity<'asset'>[];
+  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;
+  /** Import one physical asset without implying a one-to-one media Entity mapping. */
+  importAsset(input: ImportAssetInput): 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(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, 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