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

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 a Medeo video document and its explicit
+Entity/Relation state through the deterministic edit sandbox.
 
 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.
+- versioned or per-op-preflight commit through `ManualSyncDoc`;
+- 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.
@@ -36,9 +37,38 @@ const commit = await medeo.handle({
   plan_id: run.plan_id,
 });
 
+// Generation facts are recalled by the host and passed into the sandbox.
+const entityRun = await medeo.handle({
+  op: 'run-edit-script',
+  doc_id: docId,
+  inputs: { output_asset_id: 'asset-from-host', generation_id: 'generation-from-host' },
+  script: `
+if (typeof inputs.output_asset_id !== 'string' || typeof inputs.generation_id !== 'string') {
+  throw new Error('missing recalled generation facts');
+}
+const asset = entities.importAsset({ asset_id: inputs.output_asset_id });
+const input = entities.create({
+  entity_kind: 'image',
+  payload: { extent: { kind: 'unbounded', start: 0 }, sampling: 'constant', coordinateSpace: 'ms' },
+});
+const output = entities.create({
+  entity_kind: 'video',
+  payload: { extent: { kind: 'bounded', start: 0, end: 1000 }, sampling: 'native', coordinateSpace: 'ms' },
+});
+relations.link({ relation_kind: 'physical-asset', endpoint_0_entity_id: output, endpoint_1_entity_id: asset });
+relations.linkGenerated({ output_entity_id: output, input_entity_id: input, trace: { generation_id: inputs.generation_id } });
+  `,
+});
+
 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.
+
+Timeline mutations and Entity/Relation mutations use different storage and CAS
+boundaries. A single script plan cannot mix them; create and commit two plans
+when a workflow needs both.

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

@@ -0,0 +1,174 @@
+//#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';
+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;
+  };
+  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 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;
+}
+type EntityCommand = {
+  kind: 'create-entity';
+  entity: SandboxEntity;
+} | {
+  kind: 'link-relation';
+  relation: SandboxRelation;
+};
+interface EntityPlanState {
+  base_revision: number;
+  commands: readonly EntityCommand[];
+  rows: EntityStoreSnapshot;
+}
+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;
+  /** 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;
+}
+//#endregion
+export { SandboxRelation as _, EntityPlanState as a, JsonObject as c, KnownEntityKind as d, KnownRelationKind as f, SandboxEntity as g, RelationFacade as h, EntityFacade as i, JsonPrimitive as l, LinkRelationInput as m, CreateEntityInput as n, EntityStoreSnapshot as o, LinkGeneratedRelationInput as p, EntityCommand as r, ImportAssetInput as s, AuthorableRelationKind as t, JsonValue as u };
+//# sourceMappingURL=entity-contract-B3txrzTt.d.mts.map

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { JournalEntry, MengineDocSession, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft, fromVideoDocument } from "@mengine/medeo-client";
+import { _ as SandboxRelation, a as EntityPlanState, c as JsonObject, d as KnownEntityKind, f as KnownRelationKind, g as SandboxEntity, h as RelationFacade, i as EntityFacade, l as JsonPrimitive, m as LinkRelationInput, n as CreateEntityInput, o as EntityStoreSnapshot, p as LinkGeneratedRelationInput, r as EntityCommand, s as ImportAssetInput, t as AuthorableRelationKind, u as JsonValue } from "./entity-contract-B3txrzTt.mjs";
+import { JournalEntry, ManualSyncDoc, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft, fromVideoDocument } from "@mengine/medeo-client";
 import { AddSpeechesInput, AddVideoClipsInput, AdjustBgmVolumeInput, AdjustSpeechVolumeInput, AdjustVideoClipDurationInput, AdjustVideoClipVolumeInput, ChangeSpeechScriptInput, ChangeSpeechVoiceInput, DeleteBgmInput, DeleteSpeechesInput, DeleteVideoClipsInput, MoveSpeechesInput, MoveVideoClipsByAnchorInput, MoveVideoClipsInput, ReplaceVideoClipContentInput, ReplaceVideoClipSequenceInput, SetBgmInput, SetCaptionStyleInput, SetCaptionVisibilityInput, SetVideoClipSpeedShiftInput } from "@mengine/medeo-client/schemas";
 
 //#region src/document/compact-projection.d.ts
@@ -32,6 +33,9 @@ declare function collectAffectedPartIds(journal: readonly JournalEntry[]): Set<s
  */
 declare function renderPreview(document: VideoDocument, journal: readonly JournalEntry[]): string;
 //#endregion
+//#region src/entity/entity-sandbox.d.ts
+type DomainIdFactory = (prefix: 'entity' | 'relation') => string;
+//#endregion
 //#region src/sandbox/script-session.d.ts
 /**
  * Runtime-neutral edit-sandbox session: `edit.*` / `timeline.*` / checkpoint
@@ -45,9 +49,13 @@ interface SandboxCheckpoint {
   readonly index: number;
 }
 interface ChangePlan {
+  readonly plan_kind: 'timeline' | 'entities';
   doc_id: string;
   base_version: string;
   ops: readonly JournalEntry[];
+  entity_base_revision: number;
+  entity_commands: readonly EntityCommand[];
+  entity_rows?: EntityStoreSnapshot;
   preview: string;
   logs: string[];
 }
@@ -57,6 +65,10 @@ interface EditSandboxSessionOptions {
   onLog?: (line: string) => void;
   /** Notify host that the streamed journal was truncated to `index` (rollback). */
   onTruncate?: (index: number) => void;
+  entityState?: EntityStoreSnapshot;
+  domainIdFactory?: DomainIdFactory;
+  onEntityCommand?: (command: EntityCommand) => void;
+  onEntityTruncate?: (index: number) => void;
 }
 interface TimelineClipDescriptor {
   id: string;
@@ -83,6 +95,7 @@ declare class EditSandboxSession {
   private readonly onEntry;
   private readonly onLog;
   private readonly onTruncate;
+  private readonly entitySandbox;
   private current;
   /** Adapter journal length already accounted for — new slices are real commits. */
   private adapterJournalSeen;
@@ -92,6 +105,8 @@ declare class EditSandboxSession {
   private logCapped;
   readonly edit: EditFacade;
   readonly timeline: TimelineFacade;
+  readonly entities: EntityFacade;
+  readonly relations: RelationFacade;
   readonly console: ConsoleShim;
   readonly checkpoint: () => SandboxCheckpoint;
   readonly rollbackTo: (cp: SandboxCheckpoint) => void;
@@ -123,8 +138,8 @@ interface EditFacade {
   deleteSpeeches: (input: DeleteSpeechesInput) => Promise<void>;
   deleteVideoClips: (input: DeleteVideoClipsInput) => Promise<void>;
   moveSpeeches: (input: MoveSpeechesInput) => Promise<void>;
-  moveVideoClipsByAnchor: (input: MoveVideoClipsByAnchorInput) => Promise<void>;
   moveVideoClips: (input: MoveVideoClipsInput) => Promise<void>;
+  moveVideoClipsByAnchor: (input: MoveVideoClipsByAnchorInput) => Promise<void>;
   replaceVideoClipContent: (input: ReplaceVideoClipContentInput) => Promise<void>;
   replaceVideoClipSequence: (input: ReplaceVideoClipSequenceInput) => Promise<void>;
   setBgm: (input: SetBgmInput) => Promise<void>;
@@ -157,6 +172,8 @@ interface RunEditScriptOptions {
   baseVersion: string;
   script: string;
   inputs?: Record<string, unknown>;
+  /** Authoritative entity/relation rows and revision fetched for this document. */
+  entityState?: EntityStoreSnapshot;
   /** Deterministic id mint label for tests; omit to use the default ULID factory. */
   idLabel?: string;
   /** Hard wall-clock timeout; default 2000 ms. */
@@ -181,6 +198,7 @@ type EditScriptResult = {
   };
   partial: {
     ops: readonly JournalEntry[];
+    entityCommands: readonly EntityCommand[];
     logs: string[];
   };
 };
@@ -219,11 +237,11 @@ declare const MEDEO_TOOL_PARAMETERS: {
     readonly script: {
       readonly type: 'string';
       readonly minLength: 1;
-      readonly description: 'JavaScript body for run-edit-script. It receives edit, timeline, checkpoint, rollbackTo, inputs, and console; perform all calculations in the script.';
+      readonly description: 'JavaScript body for run-edit-script. It receives edit, timeline, entities, relations, checkpoint, rollbackTo, inputs, and console. A plan may mutate the timeline or Entity/Relation state, never both.';
     };
     readonly inputs: {
       readonly type: 'object';
-      readonly description: 'Pre-materialized, side-effect-free values passed into the script. Generation and network IO must happen in the host before this call.';
+      readonly description: 'Pre-materialized, side-effect-free values passed into the script, including recalled generation lineage and asset facts. Generation and network IO must happen in the host before this call.';
     };
     readonly timeout_ms: {
       readonly type: 'integer';
@@ -247,7 +265,7 @@ declare const MEDEO_TOOL_PARAMETERS: {
     readonly validation: {
       readonly type: 'string';
       readonly enum: readonly ['version', 'preflight'];
-      readonly description: 'commit-plan mode: version rejects any concurrent change; preflight revalidates each op against the current snapshot.';
+      readonly description: 'Timeline commit mode: version rejects any concurrent change; preflight revalidates each op. Entity plans always use revision CAS and reject preflight.';
     };
   };
   readonly oneOf: readonly [{
@@ -310,23 +328,39 @@ declare const MEDEO_TOOL_PARAMETERS: {
 //#region src/session/commit-plan.d.ts
 /**
  * A sandbox journal plus the opaque version token taken at fork time.
- * `commitPlan` rejects the whole plan when the live session has moved on
+ * `commitPlan` rejects the whole plan when the live document has moved on
  * (phase-1 version gate), or localizes a business conflict to a journal
  * entry under `{ validation: 'preflight' }`.
  */
 interface CommitPlan {
-  /** `session.version()` at the moment the sandbox was forked. */
+  /** Encoded `ManualSyncDoc.versionMark()` from when the sandbox was forked. */
   base_version: string;
   ops: readonly JournalEntry[];
 }
+interface CommitPlanWarning {
+  kind: 'pull_failed';
+  message: string;
+}
 type CommitPlanResult = {
   kind: 'committed';
   ops_applied: number;
+  collaborated: boolean;
+  warnings?: CommitPlanWarning[];
+} | {
+  kind: 'unconfirmed';
+  reason: 'push_failed';
+  ops_applied: number;
+  message: string;
 } | {
   kind: 'rejected';
   reason: 'version_mismatch';
   expected: string;
   actual: string;
+} | {
+  kind: 'rejected';
+  reason: 'push_rejected';
+  code?: string;
+  message: string;
 } | {
   kind: 'rejected';
   reason: 'op_conflict'; /** Failing entry index in the journal — agent rerun anchor. */
@@ -339,18 +373,18 @@ interface CommitPlanOptions {
   validation?: 'version' | 'preflight';
 }
 /**
- * Replay a sandbox journal into a live session through its document adapter
- * (SemanticEditor → Loro → mengine-server).
+ * Replay a sandbox journal into a manually-synchronized document and push the
+ * whole plan as one causally complete update.
  *
- * - Default / `{ validation: 'version' }`: if `session.version()` ≠
- *   `plan.base_version`, reject with zero writes.
+ * - Default / `{ validation: 'version' }`: if the current document mark differs
+ *   from `plan.base_version`, reject with zero writes.
  * - `{ validation: 'preflight' }`: skip the version gate; revalidate each op
  *   against a PlainMemoryAdapter seeded from the current live snapshot, then
  *   replay for real. A SchemaValidator failure becomes `op_conflict` with the
  *   failing entry's index. Journal integrity errors (unrecorded/unconsumed
  *   ids) still propagate as throws in both modes.
  */
-declare function commitPlan(session: MengineDocSession, plan: CommitPlan, options?: CommitPlanOptions): Promise<CommitPlanResult>;
+declare function commitPlan(doc: ManualSyncDoc, plan: CommitPlan, options?: CommitPlanOptions): Promise<CommitPlanResult>;
 //#endregion
 //#region src/host-tool.d.ts
 type ContextualValue<T> = T | ((docId: string) => T | undefined);
@@ -358,7 +392,7 @@ interface CreateMedeoToolOptions {
   /**
    * Mengine HTTP origin for a document. The host owns environment routing
    * (local/stg/prd/lane) and may return a different origin per document.
-   * Sessions cache by doc id, so the origin must remain stable for that doc.
+   * Documents cache by doc id, so the origin must remain stable for that doc.
    */
   httpOrigin: ContextualValue<string>;
   /** Optional bearer token, evaluated for each HTTP request. */
@@ -375,6 +409,7 @@ interface CreateMedeoToolOptions {
    */
   loadInitialDraft?: (docId: string) => Promise<VideoDraft>;
   fetchImpl?: typeof fetch;
+  /** @deprecated ManualSyncDoc has no SSE or reconnect loop. */
   sseReconnectDelayMs?: number;
   /** Defaults passed to runEditScript; each call may override them. */
   sandbox?: {
@@ -415,24 +450,56 @@ type MedeoToolInput = {
   plan_id: string;
   validation?: 'version' | 'preflight';
 };
+interface MedeoToolWarning {
+  kind: 'pull_failed';
+  message: string;
+}
+type EntityCommitResult = {
+  kind: 'committed';
+  ops_applied: number;
+  collaborated: false;
+  entity_revision: number;
+} | {
+  kind: 'unconfirmed';
+  reason: 'push_failed';
+  ops_applied: number;
+  message: string;
+} | {
+  kind: 'rejected';
+  reason: 'entity_revision_mismatch';
+  expected: number;
+  actual: number;
+} | {
+  kind: 'rejected';
+  reason: 'entity_state_rejected';
+  status: number;
+  message: string;
+};
+type MedeoCommitResult = CommitPlanResult | EntityCommitResult;
 type MedeoToolResult = {
   ok: true;
   op: 'snapshot';
   doc_id: string;
   version: string;
   preview: string;
+  collaborated?: boolean;
+  warnings?: MedeoToolWarning[];
 } | {
   ok: true;
   op: 'run-edit-script';
   doc_id: string;
   plan_id: string;
+  plan_kind: 'timeline' | 'entities';
   base_version: string;
+  entity_base_revision: number;
   ops_count: number;
   preview: string;
   logs: string[];
   duration_ms: number;
   committed?: boolean;
-  commit_result?: CommitPlanResult;
+  commit_result?: MedeoCommitResult;
+  collaborated?: boolean;
+  warnings?: MedeoToolWarning[];
 } | {
   ok: false;
   op: 'run-edit-script';
@@ -453,8 +520,11 @@ type MedeoToolResult = {
   op: 'commit-plan';
   doc_id: string;
   plan_id: string;
+  plan_kind: 'timeline' | 'entities';
   committed: boolean;
-  result: CommitPlanResult;
+  result: MedeoCommitResult;
+  collaborated?: boolean;
+  warnings?: MedeoToolWarning[];
 } | {
   ok: false;
   op: MedeoToolOp;
@@ -472,12 +542,12 @@ type MedeoInitialDraft = VideoDraft;
 /**
  * Create the self-contained Medeo LLM tool.
  *
- * The package owns session construction, compact projection, sandbox execution,
+ * The package owns document construction, compact projection, sandbox execution,
  * plan caching, commit, document get-or-create, and shutdown. The host supplies
  * environment facts plus the authoritative legacy draft loader used only when
  * Mengine has no document yet.
  */
 declare function createMedeoTool(options: CreateMedeoToolOptions): MedeoTool;
 //#endregion
-export { type ChangePlan, type CommitPlan, type CommitPlanOptions, type CommitPlanResult, type CompactProjectionOptions, type ConsoleShim, type CreateMedeoToolOptions, type EditFacade, EditSandboxSession, type EditSandboxSessionOptions, type EditScriptResult, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, type MedeoInitialDraft, type MedeoModelContext, type MedeoModelContextInput, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RunEditScriptOptions, type SandboxCheckpoint, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
+export { type AuthorableRelationKind, type ChangePlan, type CommitPlan, type CommitPlanOptions, type CommitPlanResult, type CompactProjectionOptions, type ConsoleShim, type CreateEntityInput, type CreateMedeoToolOptions, type EditFacade, EditSandboxSession, type EditSandboxSessionOptions, type EditScriptResult, type EntityCommand, type EntityCommitResult, type EntityFacade, type EntityPlanState, type EntityStoreSnapshot, type ImportAssetInput, type JsonObject, type JsonPrimitive, type JsonValue, type KnownEntityKind, type KnownRelationKind, type LinkGeneratedRelationInput, type LinkRelationInput, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, type MedeoCommitResult, type MedeoInitialDraft, type MedeoModelContext, type MedeoModelContextInput, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RelationFacade, type RunEditScriptOptions, type SandboxCheckpoint, type SandboxEntity, type SandboxRelation, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
 //# sourceMappingURL=index.d.mts.map