@mengine/medeo-tool 1.4.1-alpha.1 → 1.4.1-alpha.3

package/README.md

@@ -1,142 +1,90 @@
 # `@mengine/medeo-tool`
 
-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 Node host executes scripts against assembled Medeo entities and relations,
+compiles their operation journal against the original Loro causal snapshot, and
+publishes the original native update. It owns the model API declaration and
+editor context; consumers supply authentication, transport and resource loaders.
 
-The package owns the complete tool path:
+The sandbox API consists of:
 
-- compact snapshot projection;
-- trusted worker execution of an agent-authored JavaScript edit script;
-- entity-command `ChangePlan` caching;
-- complete Entity/Relation snapshot reads and revision-CAS commits;
-- per-document serialization, document cache, and shutdown.
+- `entities.list/get/create/update/declareFields/delete`
+- `relations.list/of/link/update/unlink`
+- `rgetAssetFromEntity`, `checkpoint`, `rollbackTo`
 
-A host supplies only environment facts: Mengine HTTP origin, optional request
-identity headers, `fetch`, and a stable agent peer id.
+`inputs` and the four console methods are execution context. There is no separate
+business editing facade. The generated declarations are available through
+`@mengine/medeo-tool/sandbox-api` and in every model context.
 
 ```ts
-import { materializeResources, createMedeoTool } from '@mengine/medeo-tool';
+import { createMedeoTool } from '@mengine/medeo-tool';
 
-const medeo = createMedeoTool({
-  httpOrigin: process.env.MENGINE_HTTP_ORIGIN!,
-  userId: () => process.env.MED_USER_ID,
-  peerId: () => process.env.MED_AGENT_PEER_ID,
-});
-
-const snapshot = await medeo.handle({ op: 'snapshot', doc_id: docId });
+const medeo = createMedeoTool({ httpOrigin, userId, authToken, loadEntityAsset });
 const run = await medeo.handle({
   op: 'run-edit-script',
   doc_id: docId,
-  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({
-  op: 'commit-plan',
-  doc_id: docId,
-  plan_id: run.plan_id,
-});
-
-// Only the host imports resource facts. Model inputs contain domain identities.
-const [contentEntityId] = await materializeResources({ docId, httpOrigin }, [
-  { assetId: 'asset-from-host', kind: 'image' },
-]);
-const entityRun = await medeo.handle({
-  op: 'run-edit-script',
-  doc_id: docId,
-  inputs: { content_entity_id: contentEntityId, track_entity_id: existingTrackEntityId },
-  script: `edit.insertClip({
-    trackEntityId: inputs.track_entity_id,
-    contentEntityId: inputs.content_entity_id,
-    sourceRange: { start: 0, end: 1 }, duration: { mode: 'fixed', value: 5000 },
-    targetRange: { start: 0, end: 5000 },
+  inputs: { clipId },
+  script: `entities.update({
+    entity_id: inputs.clipId,
+    changes: [{ op: 'set', path: ['volume'], value: -6 }],
   });`,
 });
-
+if (!run.ok || run.op !== 'run-edit-script') throw new Error('Edit failed');
+await medeo.handle({ op: 'commit-plan', doc_id: docId, plan_id: run.plan_id });
 await medeo.close();
 ```
 
-The sandbox exposes only business Entity/Relation operations. It has no Asset
-lookup, read, create, update, delete, import or binding API. `ensureMedia`,
-`findByAssetId` and Asset-based editor shortcuts remain host-only.
-Generation tools may return Asset IDs. Entity operations accept these IDs in
-`external: { system: 'memota', key: assetId }`; assembled entity reads preserve
-that reference. An Asset ID is not an Entity ID, a composition base or a Relation
-endpoint. Physical `storageKey` access and Asset rows remain host-only.
-
-`materializeResources` is a host API. It creates media entities from factual
-resources, or Caption with composed AudioScript text, ASR annotation markers
-and an optional physical-asset binding. It publishes a native Loro update
-before returning domain Entity IDs. Text edits through Caption version its
-AudioScript base and rewire composition; Caption's own ID stays unchanged.
-Repeated materialization reuses the persisted resource binding. Generation
-facts, when supplied, are resolved before the same commit so resource import
-and ordered provenance are atomic.
-
-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.
+Reads are assembled snapshots. `update` applies a nonempty, atomic group of
+field operations, routing inherited fields to the declaring entity. Explicit
+own-field declarations use `declareFields`; duplicate fields from multiple bases
+are errors even if the variant overrides them. An owned-field change versions
+its entity. Automatic base-reference advancement preserves an unchanged variant's
+identity and advances project attachments.
+
+Use `text.splice` for Unicode code-point edits and `list.insert/move/remove` for
+collaborative lists, addressing members by `{elementId}`. `set` accepts scalars
+and schema atomic values such as complete time ranges. It cannot replace a
+collaborative map, text or list snapshot. Composition bases are unordered
+membership: insert/remove preserve independent concurrent additions.
+
+Relations retain endpoint positions; their kind defines endpoint roles.
+`relations.update` edits metadata/trace fields only. Explicit endpoint changes
+require unlink and a new relation. Deletion refuses live business relations,
+variant dependencies and protected project attachments. It does not cascade or
+delete external resources.
+
+An Asset ID is permitted in `payload.external`, but is not an entity ID, base ID
+or relation endpoint. Asset lookup/CRUD and physical storage paths are not
+sandbox APIs. The host resolves the resource already attached to an entity:
+
+```js
+const caption = entities.create({
+  entity_kind: 'caption',
+  payload: { external: { system: 'memota', key: inputs.captionAssetId } },
+});
+const original = await rgetAssetFromEntity(caption);
+const view = entities.get(caption);
+entities.update({
+  entity_id: caption,
+  changes: [
+    {
+      op: 'text.splice',
+      path: ['segments', { elementId: view.payload.segments[0].segmentId }, 'text'],
+      index: 0,
+      deleteCount: 0,
+      text: 'Edited: ',
+    },
+  ],
+});
+```
 
-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.
+Caption resource initialization supplies intrinsic timing and the composed
+project AudioScript text in the same plan. Repeated reads return the original
+resource and preserve edited entity content. Failure prevents publication.
+Resource-free Caption composition from AudioScript is also supported. Each
+on-screen placement has its own Clip and display SequenceMarker, connected by
+ordinary relations; intrinsic Caption timing remains independent.
+
+`materializeResources` and generation/resource loaders are host APIs. The model
+never receives these capabilities. Project initialization and historical data
+migration also remain outside script execution. Retrying an unconfirmed commit
+uses the same plan ID and native update, never a recompiled final JSON snapshot.

package/dist/{entity-contract-DHasvrhq.d.mts → entity-contract-DQ56Ihrh.d.mts}

@@ -1,4 +1,4 @@
-import { MediaAssetFact } from "@mengine/medeo-client";
+import { FieldChange, MediaAssetFact } from "@mengine/medeo-client";
 
 //#region src/entity/entity-contract.d.ts
 type JsonPrimitive = string | number | boolean | null;
@@ -10,7 +10,7 @@ type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'vi
 /** 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'>;
+type AuthorableRelationKind = KnownRelationKind;
 interface BoundedNativeSequencePayload extends JsonObject {
   /** Factual coordinates from recalled media metadata; never invent an end/duration. */
   extent: {
@@ -57,16 +57,6 @@ type CaptionTextSelection = JsonObject & {
     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;
@@ -118,10 +108,15 @@ interface EntityPayloadByKind {
     baseEntityIds: string[];
     selections: CaptionTextSelection[];
     style?: JsonObject;
+    segmentRanges?: {
+      segmentId: string;
+      startMs: number;
+      endMs: number;
+    }[];
   };
 }
 /** 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]> & {
+type StoredEntityPayload<K extends KnownEntityKind> = EntityPayloadByKind[K] | (K extends 'caption' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never) | (JsonObject & Partial<EntityPayloadByKind[K]> & {
   baseEntityIds: string[];
 });
 interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {
@@ -159,50 +154,32 @@ interface UpdateEntityInput {
 interface DeleteEntityInput {
   entity_id: string;
 }
-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;
   endpoint_1_entity_id: string;
   trace?: JsonObject;
 }
-type LinkRelationInput = (LinkRelationBase & {
-  relation_kind: EmptyRelationKind;
-  metadata?: {
-    [key: string]: never;
-  };
-}) | (LinkRelationBase & {
-  relation_kind: 'physical-asset';
+interface LinkRelationInput extends LinkRelationBase {
+  relation_kind: KnownRelationKind;
   metadata?: JsonObject;
-}) | (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 EntityUpdateInput {
+  entity_id: string;
+  changes: FieldChange[];
 }
-interface LinkPhoneticScriptRenderRelationInput {
-  relation_id?: string;
-  output_entity_id: string;
-  phonetic_script_entity_id: string;
-  trace?: JsonObject;
+interface RelationUpdateInput {
+  relation_id: string;
+  changes: FieldChange[];
+}
+/** Tokens have no script-authored data; only the creating session can validate them. */
+interface EntitySandboxCheckpoint {
+  readonly __checkpoint: unique symbol;
 }
-/** `audio-script-source(script, source)`; the script was transcribed from the source media. */
-interface LinkAudioScriptSourceRelationInput {
+interface LinkGeneratedRelationInput {
   relation_id?: string;
-  script_entity_id: string;
-  source_entity_id: string;
+  output_entity_id: string;
+  input_entity_id: string;
   trace?: JsonObject;
 }
 interface UnlinkRelationInput {
@@ -215,6 +192,14 @@ type EntityCommand = {
   kind: 'update-entity';
   entity_id: string;
   payload: JsonObject;
+} | {
+  kind: 'change-entity';
+  entity_id: string;
+  changes: FieldChange[];
+} | {
+  kind: 'change-relation';
+  relation_id: string;
+  changes: FieldChange[];
 } | {
   kind: 'delete-entity';
   entity_id: string;
@@ -232,45 +217,25 @@ interface EntityPlanState {
   deleted_entity_ids: readonly string[];
   deleted_relation_ids: readonly string[];
 }
-interface EntityFacade {
-  /** Read complete assembled fields; returned objects are snapshots. Use update to persist edits. */
+/** Business editing surface. Reads are assembled snapshots; writes preserve native operation intent. */
+interface BusinessEntityFacade {
   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>[];
-  /** 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;
-  /** 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. */
+  create(input: Exclude<CreateEntityInput, {
+    entity_kind: 'asset';
+  }>): string;
+  update(input: EntityUpdateInput): void;
   declareFields(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 {
+/** Endpoint order is retained; each relation kind defines its endpoint semantics. */
+interface BusinessRelationFacade {
   list(): SandboxRelation[];
-  /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */
   of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];
-  /** 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 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. */
+  update(input: RelationUpdateInput): void;
   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-DHasvrhq.d.mts.map
+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-DQ56Ihrh.d.mts.map