@mengine/medeo-client 1.3.0 → 1.3.1-alpha.0

package/README.md

@@ -2,4 +2,98 @@
 
 Medeo domain client for the `mengine` document path.
 
-This package owns the shared `VideoDocument` contract, semantic editing layer, and runtime-neutral HTTP/SSE client used by medeo-web, agent-harness, and server-side validation code. UI adapters such as `DraftMutationDriver` stay in product repositories.
+This package owns graph-native Medeo editing, its one-way `VideoDocument`
+compatibility projection, and the runtime-neutral HTTP/SSE clients. UI intent
+adapters stay in product repositories; Harness only supplies environment and
+asset facts, not an entity store implementation.
+
+For entity-authoritative documents:
+
+1. `EntityGraphHttpClient.fetchState()` obtains the complete graph and revision.
+2. `ensureEditorFoundation` gets or creates one Timeline and four role Tracks,
+   retaining all existing identities and settings. `importMediaAsset` groups and
+   deduplicates only by direct media variants carrying the same external asset
+   id `(system, key)`. Imports mint exactly one media variant Entity
+   (Video/Image/Audio/Voice) that carries the Asset locator itself; no separate
+   `asset` Entity and no `physical-asset` Relation are created, and the returned
+   identity is that single Entity. Video duration must come from asset
+   metadata, never a clip trim window. Dual-entity media graphs (`asset` row
+   plus a `physical-asset` binding) are not reused and fail explicitly instead
+   of minting a second identity. This policy is local to the MEngine editor, not
+   the general-purpose DSL.
+3. `EntityTimelineEditor` edits Clip/Marker/Track relations and payloads.
+4. `EntityGraphHttpClient.commit(baseState, nextRows)` performs revision CAS,
+   including explicit net deletions. The server writes entities and the derived
+   Loro read view in the same transaction.
+
+Repeated placement reuses the same single media identity but creates independent
+Clips and SequenceMarkers. Asset generation alone still does not create editor
+Entities. Two commit-level guards protect the single-identity policy:
+`assertCanonicalEditorResources(rows)` checks one complete state — every media
+variant carries its own external locator, one external asset id has exactly one
+claimant, and no media variant is bound through a `physical-asset` Relation.
+The exported `assertMediaAssetWritePolicy(before, after)` checks one CAS
+transition and is reusable by the host tool and the entity stores: it applies
+the same rules to the complete after state, and a self-carried identity cannot
+be rewritten to another asset id. The editor applies it to every transaction
+and `EntityGraphHttpClient.commit` applies it to `(baseState.rows, nextRows)`
+before any request. There is no historical exemption: dual-entity media graphs
+are rejected rather than kept editable — the shared `decodeEntityRelationRows`
+boundary already fails rows whose media variants lack `external` or carry a
+`physical-asset` binding, so editors and commits never observe them — deleting
+media is an explicit caller decision, and no implicit historical merge or
+identity rewriting occurs. The
+compatibility reader reads physical facts directly from the media variant;
+Caption inline text still resolves its inline Asset through
+`physical-asset`.
+
+`SequenceMarker` owns source/target ranges, duration, and time remapping. `Clip`
+owns clip properties such as volume; `Track` owns track properties. References
+between entities belong in Relations, not in payload IDs. There is no separate
+timing profile. The compatibility reader supports the existing four lanes:
+one image/video main track, Voice, Caption, and background Audio. It accepts
+explicit millisecond media coordinates and linear visual remapping
+`{ kind: 'linear', rate: 2 }` (including still-image display speed). Nonlinear
+speed and multiple visual overlay tracks are not existing editor capabilities
+and remain outside this adapter; unsupported layouts fail before persistence.
+Effective duration and absolute target coordinates must be whole milliseconds
+for this reader; generic DSL coordinates are not globally restricted to that
+unit or precision. Sequential placement stays `Clip.order` plus no targetRange,
+so later duration edits continue to move following Clips.
+
+Entity-authoritative editor consumers use the Loro session only to receive the
+server-authored compatibility view. Configure that session as read-only: even
+cold-start reconciliation must not POST legacy `/updates`. Entity writes use
+the independent graph CAS endpoint.
+
+Anchored placement is a `clip-anchor` Relation from child Clip to host Clip
+plus `SequenceMarker.anchorOffset`. Voice and Caption can be independently
+placed or explicitly anchored; generation relations do not choose a host. `resolveEntityTimelineLayout` resolves this graph
+without reparenting or synthesizing content. Move/delete operations must write
+their follow, keep-absolute, cascade, or detach decisions into the same entity
+plan. A speech-overlap shift is explicit placement on the real visual Clips;
+an uncovered time interval does not require an invented empty-media entity.
+
+Voice links to its AudioScript through `audio-script-render`; Caption links to
+its source script and optional alignment Voice through separate provenance/alignment relations. External
+speech identity and physical storage key belong to the Voice Entity itself.
+`insertCaptionClip` creates a complete independent Caption placement;
+`upsertVoiceoverTake` accepts explicit `placement` for independent voice.
+AudioScript carries only text. `audio-script-marker` attaches directly assigned
+`segmentRanges` timing; those annotation Markers cannot be Clip display Markers.
+Caption styles belong to Caption; text can have a real inline text Asset rather
+than a fabricated Memota ID. Background Audio's Marker declares
+`durationPolicy: 'timeline'`: its source duration stays factual,
+while the view fills the non-BGM timeline duration.
+
+`migrateLegacyTimelineToEntities` is a one-time migration utility, **not** an
+ordinary editing diff adapter. A configured legacy document requires a separate
+CAS commit with `migrationBaseVv` equal to its current canonical base64 Loro
+oplog version. The server calls `assertEntityProjectionPreservesLegacy` to reject
+stale or lossy migrations. Only then can a new edit be committed.
+
+The legacy `SemanticEditor` remains available for pre-cutover library consumers.
+It rejects `video-document/entity-projection-v1` documents. Production entity
+tools and editor adapters must not fall back to it or raw `/updates` on failure.
+For an entity projection, `meta.version` is the committed entity revision; the
+Loro version vector remains the transport-sync cursor.