@mengine/medeo-client 2.0.1-alpha.6 → 2.0.1-alpha.7

package/dist/{index-B31KeDzA.d.ts → index-CDrPUhBH.d.ts}

@@ -442,10 +442,6 @@ interface VideoDraft$1 {
 }
 //#endregion
 //#region src/document/types.d.ts
-declare const VIDEO_DOCUMENT_SCHEMA_VERSION: "video-document/v0";
-/** A server-derived compatibility view, never an editor write authority. */
-declare const ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION: "video-document/entity-projection-v1";
-type VideoDocumentSchemaVersion = typeof VIDEO_DOCUMENT_SCHEMA_VERSION | typeof ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION;
 type PartKind = 'video_clip' | 'speech' | 'caption' | 'bgm';
 /**
  * Project-level creation settings. Mirrors the IDL, but keeps the two fields the
@@ -645,17 +641,52 @@ type VideoDraftPartUnion = {
   };
 };
 /**
- * Derived `VideoDraft` read-view. The shape follows the IDL verbatim except for
- * `part_library`: the IDL types its parts with the generated namespace
- * `PartUnion`, but the engine's projection emits `VideoDraftPartUnion` — the
- * authoritative parts with the derived `duration_ms` re-injected (reference/17 §7)
- * plus the engine extensions (`media_duration_ms`, the looser `SpeedShift`). This
- * is the intentional superset over the IDL `VideoDraft` (see the extensions note).
+ * Legacy Draft import shape. It allows omitted durations and engine extensions
+ * so existing fixtures and migrations can state only the facts they have.
+ * Projection returns the narrower `VideoDraftContent` contract instead.
  */
 type VideoDraft = Omit<VideoDraft$1, 'part_library' | 'video_creation_settings'> & {
   part_library: Record<string, VideoDraftPartUnion> | undefined;
   video_creation_settings?: VideoCreationSettings | undefined;
 };
+/**
+ * The complete content read model produced by the shared projection. Business
+ * identity, settings, thumbnail and revision counters are assembled by Director;
+ * keeping an explicit field list prevents new business DTO fields entering here.
+ */
+type VideoDraftContent = Pick<VideoDraft, 'timeline' | 'main_track' | 'above_main_tracks' | 'below_main_tracks' | 'part_aggregations'> & {
+  part_library: Record<string, VideoDraftContentPartUnion> | undefined;
+};
+/** Projection always states the duration field; legacy imports may omit it. */
+type VideoDraftContentPartUnion = {
+  video_clip: VideoClipPart & {
+    duration_ms: number | undefined;
+  };
+  speech?: never;
+  caption?: never;
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech: SpeechPart & {
+    duration_ms: number | undefined;
+  };
+  caption?: never;
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech?: never;
+  caption: CaptionPart & {
+    duration_ms: number | undefined;
+  };
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech?: never;
+  caption?: never;
+  bgm: BgmPart & {
+    duration_ms: number | undefined;
+  };
+};
 /** Authoritative timeline: `duration_ms` is derived (= longest track), not stored. */
 interface Timeline {
   unit_time_ms: number | undefined;
@@ -670,39 +701,19 @@ interface Timeline {
  * is not, and passes any `>= 0` guard on its way to an editor that cannot use it.
  */
 declare const DEFAULT_UNIT_TIME_MS = 33.333;
-/**
- * Project-level scalars that do not participate in track ordering. Grouped under
- * `meta` because the loro-mirror `schema()` root only accepts container schemas,
- * not bare scalars — so these must live inside a map container in storage. The
- * domain type mirrors that storage shape 1:1 (RFC 03 §4) rather than flattening,
- * keeping `VideoDocument` and the loro draft isomorphic and the mapping layer a
- * near-identity. `schema_version` lives here too (it is a scalar fact).
- */
-interface VideoDocumentMeta {
-  schema_version: VideoDocumentSchemaVersion;
-  draft_id?: string | undefined;
-  project_id: VideoDraft['project_id'];
-  owner_id: VideoDraft['owner_id'];
-  thumbnail_storage_key: VideoDraft['thumbnail_storage_key'];
-  chat_session_id: VideoDraft['chat_session_id'];
-  video_creation_settings: VideoDraft['video_creation_settings'];
-  /** Legacy imported version for v0; committed Entity revision for entity-projection-v1. */
-  version: VideoDraft['version'];
-}
 /**
  * Authoritative collaborative document: only facts. Positioning lives on each
  * `TrackItem.time_position`; absolute time, `part_aggregations`, and total
  * duration are derived in the `VideoDraft` projection, not stored here (RFC 02 §6).
  *
- * The shape mirrors the loro storage structure 1:1 (RFC 03 §4): a `meta` map of
- * project scalars, plus a single ordered `tracks` list (reference/17 §4). A
+ * The content mirrors Loro storage: timeline, part library, and a single
+ * ordered `tracks` list (reference/17 §4). Business metadata stays in Director. A
  * track's lane is expressed by its `parts_kind`, not by which container it lives
  * in — the `main` / `above` / `below` three-pane view is reconstructed at
  * projection time. Order is the list order itself, so there is no `lane` /
  * `lane_order` field to diverge under concurrent edits.
  */
 interface VideoDocument {
-  meta: VideoDocumentMeta;
   timeline: Timeline | undefined;
   tracks: Track[] | undefined;
   part_library: Record<string, PartUnion> | undefined;
@@ -724,15 +735,193 @@ interface VideoDocumentValidationIssue {
   severity?: VideoDocumentValidationIssueSeverity;
 }
 //#endregion
+//#region src/document/mirror-schema.d.ts
+declare const videoDocumentMirrorSchema: import("loro-mirror").RootSchemaType<{
+  timeline: import("loro-mirror").LoroMapSchema<{
+    unit_time_ms: /*elided*/any;
+  }> & {
+    options: {};
+  } & {
+    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
+      unit_time_ms: /*elided*/any;
+    }, C>;
+  };
+  tracks: import("loro-mirror").LoroMovableListSchema<import("loro-mirror").LoroMapSchema<{
+    id: /*elided*/any;
+    parts_kind: /*elided*/any;
+    is_hidden: /*elided*/any;
+    items: /*elided*/any;
+  }> & {
+    options: {};
+  } & {
+    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
+      id: /*elided*/any;
+      parts_kind: /*elided*/any;
+      is_hidden: /*elided*/any;
+      items: /*elided*/any;
+    }, C>;
+  }> & {
+    options: {};
+  };
+  part_library: import("loro-mirror").LoroMapSchemaWithCatchall<{}, import("loro-mirror").LoroMapSchema<{
+    video_clip: /*elided*/any;
+    speech: /*elided*/any;
+    caption: /*elided*/any;
+    bgm: /*elided*/any;
+  }> & {
+    options: {};
+  } & {
+    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
+      video_clip: /*elided*/any;
+      speech: /*elided*/any;
+      caption: /*elided*/any;
+      bgm: /*elided*/any;
+    }, C>;
+  }> & {
+    options: {};
+  };
+}> & {
+  options: {};
+};
+type VideoDocumentMirrorSchema = typeof videoDocumentMirrorSchema;
+/**
+ * The mutable draft an op's `transact` callback edits, inferred from the schema.
+ *
+ * `InferInputType` is the schema's *input* shape: the declared business fields
+ * with the `$cid` container ids (which mirror injects into its output
+ * `InferType`) made optional, so ops assign plain objects without supplying
+ * `$cid`. Deriving it from the schema keeps draft and storage in lockstep — a
+ * schema change is a compile error at every edit site, not a silent drift.
+ * Reorders within `items` still diff to real Loro `move` ops because the schema
+ * keys items by `part_id`.
+ */
+type VideoDocumentDraft = InferInputType<VideoDocumentMirrorSchema>;
+/** Track value as it appears in a draft. Derived from the single `tracks` movable list. */
+type TrackDraft = NonNullable<NonNullable<VideoDocumentDraft['tracks']>[number]>;
+/** A single track item in a draft. */
+type TrackItemDraft = NonNullable<NonNullable<TrackDraft['items']>[number]>;
+//#endregion
+//#region src/timeline-core/bridge.d.ts
+/**
+ * Bridge between the authoritative `VideoDocument` (position-only facts) and the
+ * flat `TimelineDoc` the cascade primitives solve over.
+ *
+ * The data flow is single-directional (RFC 02 §7/§10): ops write only facts
+ * (`time_position`, parts) to `VideoDocument`; absolute time, `part_aggregations`,
+ * total duration, and gap fillers are NOT stored — the projection derives them
+ * on read by running the cascade. There is no write-back of solved positions.
+ *
+ * - `solveVideoDocument` seeds a `TimelineDoc` from each item's `time_position`,
+ *   runs the full cascade, and returns the derived read-view (abs / aggregations
+ *   / duration). It is the single solve shared by the legacy `VideoDraft`
+ *   projection.
+ * - `ensureLaneTrack` / `findLaneTrack` locate (or mint) a secondary lane's
+ *   track row in the draft, so ops can write authoritative facts onto the right
+ *   named container (lane = container).
+ */
+/** The projection-derived read-view of a `VideoDocument` (RFC 02 §7). */
+interface SolvedVideoDocument {
+  absByPartId: Map<string, number>;
+  aggregations: PartAggregation[];
+  durationMs: number;
+  partLibrary: Record<string, PartUnion>;
+  /**
+   * Part ids of the gap fillers this solve minted.
+   *
+   * They exist only inside the solve: gap filling needs them so the clips after a
+   * gap land at the right absolute time, but they are not authoritative state and
+   * the read view does not carry them (see `fromVideoDocument`).
+   *
+   * Reported as ids rather than left for the caller to detect, because the caller
+   * *cannot* detect them. The obvious predicate — `origin_media_id === ''` — also
+   * matches an empty clip a writer placed on purpose (`batch_replace_video_clip_sequence`
+   * documents "Omit to create an empty clip placeholder"), and those are
+   * authoritative parts that must survive the projection. The mint callback is the
+   * only place that knows the difference.
+   *
+   * Note this deliberately excludes the fillers that gap filling *extended* rather
+   * than minted (`fillMainTrackTimeGaps` cases 1 and 2): those are authoritative
+   * empty clips already in `part_library`, and only their length is derived.
+   */
+  derivedFillerPartIds: Set<string>;
+}
+/** How the caller obtained the document it is asking to be solved. */
+interface SolveVideoDocumentOptions {
+  /**
+   * The producer already resolved every placement, so the legacy cascade must
+   * not run. Only an Entity projection can state this: its placement comes from
+   * Clip order / clip-anchor offsets / Marker targetRange, and re-solving would
+   * overwrite those and synthesize gap fillers the Entity graph never had.
+   *
+   * The document itself no longer carries its provenance (P7M14 moved business
+   * metadata out of the CRDT), so the caller states it. `hasResolvedPlacement`
+   * only verifies the claim — it is never the branch condition, because a
+   * legacy draft can satisfy it by accident and a broken projection can fail it.
+   */
+  readonly placementResolved?: boolean;
+}
+/**
+ * Solve a `VideoDocument` (authoritative, position-only) into its derived
+ * read-view: absolute time per item, `part_aggregations`, and total duration.
+ * This is the read side of the single-directional flow — never written back.
+ */
+declare function solveVideoDocument(document: VideoDocument, options?: SolveVideoDocumentOptions): SolvedVideoDocument;
+/** The named container a secondary lane lives in. */
+type SecondaryLane = 'speech' | 'caption' | 'bgm';
+/** A lane's track kind: the `video_clip` main lane plus the three secondary lanes. */
+type LaneKind = SecondaryLane | 'video_clip';
+/**
+ * The four lanes in top-to-bottom stack order — the order a `tracks` list holds
+ * them in (see {@link laneRank}).
+ *
+ * Exported so a document can be seeded with all four lanes up front. That seed is
+ * not cosmetic: {@link ensureLaneTrack} is find-then-mint over a `LoroMovableList`,
+ * so two concurrent writers that each mint the same absent lane both keep their
+ * row, and the merged document holds two tracks for one lane. For the main lane
+ * that is fatal — `videoDocumentSchema` allows at most one `video_clip` track, so
+ * the merged document stops being projectable at all, symmetrically on both
+ * replicas. Pre-seeding every lane makes `ensureLaneTrack` always take its find
+ * branch, which removes the race by construction rather than by detection.
+ *
+ * What closes the race is that a track with the lane's `parts_kind` EXISTS — the
+ * lookup is by kind, not by id. So a seed is only safe if it covers every lane:
+ * a partial seed leaves the uncovered lanes exactly as exposed as before.
+ */
+declare const LANE_KINDS_IN_STACK_ORDER: readonly LaneKind[];
+/**
+ * The conventional track id for a lane (`main_track`, `<kind>_track`). Shared by
+ * the up-front seed and {@link ensureLaneTrack}'s lazy mint so a document's lane
+ * ids do not depend on which of the two created the track.
+ *
+ * Ids are cosmetic to the merge itself — lane lookup goes by `parts_kind`, so
+ * drifting them apart would not reopen the concurrent-mint race. They matter to
+ * readers that address a lane by id (the FE editor's panes, fixtures), which is
+ * why there is one convention rather than two.
+ */
+declare function laneTrackId(kind: LaneKind): string;
+/**
+ * Locate a lane's track row in the single `tracks` list by kind, minting an empty
+ * row in lane-stacking order if absent (reference/17 §4: lane = `parts_kind`).
+ * Ops use this to write authoritative items onto the right lane. The track id
+ * comes from {@link laneTrackId}, shared with the up-front seed.
+ *
+ * The mint branch is a concurrency hazard, not a convenience: see
+ * {@link LANE_KINDS_IN_STACK_ORDER}. A document seeded with all four lanes never
+ * reaches it.
+ */
+declare function ensureLaneTrack(draft: VideoDocumentDraft, kind: LaneKind): TrackDraft;
+/** Find a secondary lane's track row without minting it. */
+declare function findLaneTrack(draft: VideoDocumentDraft, kind: SecondaryLane): TrackDraft | undefined;
+//#endregion
 //#region src/document/projection.d.ts
 /**
- * Projection between the authoritative `VideoDocument` and the legacy
- * `VideoDraft` read-view (RFC 02 §5/§7). Both directions live here:
+ * Projection between authoritative `VideoDocument` and compatible content
+ * layouts (RFC 02 §5/§7). Both directions live here:
  *
  * - `toVideoDocument` ingests a `VideoDraft`, deriving each item's `position`
  *   from the legacy absolute layout + aggregations; derived values (abs time,
  *   `part_aggregations`, total duration) are dropped.
- * - `fromVideoDocument` solves a `VideoDocument` back into a `VideoDraft` via the
+ * - `fromVideoDocument` solves a `VideoDocument` into `VideoDraftContent` via the
  *   timeline-core cascade, re-deriving exactly those values.
  *
  * Business validation lives in `validation.ts`; `fromVideoDocument` asserts a
@@ -744,7 +933,7 @@ interface VideoDocumentValidationIssue {
  * aggregations (RFC 02 §4/§5). Absolute time, `part_aggregations`, and total
  * duration are dropped — they are re-derived by the projection.
  */
-declare function toVideoDocument(draft: VideoDraft): VideoDocument;
+declare function toVideoDocument(draft: Pick<VideoDraft, keyof VideoDraftContent>): VideoDocument;
 /** speech/attachment part_id → its host video part_id + relative offset. */
 type SpeechHostMap = Map<string, {
   hostPartId: string;
@@ -784,8 +973,8 @@ interface DerivedItemPosition {
  */
 declare function derivePositionFromAbs(partId: string, abs: number, isMain: boolean, speechHost: SpeechHostMap, partLibrary: Record<string, PartUnion | string | undefined>): DerivedItemPosition;
 /**
- * Project the authoritative `VideoDocument` back into the legacy `VideoDraft`
- * read-view, solving each item's absolute position, the `part_aggregations`, and
+ * Project `VideoDocument` into `VideoDraftContent`, solving each item's
+ * absolute position, the `part_aggregations`, and
  * the total duration via the timeline-core cascade.
  *
  * The read-view is a compatibility contract, and the IDL declares
@@ -799,32 +988,15 @@ declare function derivePositionFromAbs(partId: string, abs: number, isMain: bool
  * These two are defaultable because the projection knows their values on its own:
  * absent `unit_time_ms` means "no display granularity was ever stated" and absent
  * `is_hidden` means "this track was never hidden". `version` is NOT defaultable
- * here — its only honest value is server state (`update_seq`) that a
- * `VideoDocument` cannot see, so it stays absent and the HTTP layer fills it.
+ * here — it belongs to Director assembly using the server envelope update_seq.
+ * Neither business metadata nor a revision counter belongs in content projection.
  */
-declare function fromVideoDocument(document: VideoDocument): VideoDraft;
+declare function fromVideoDocument(document: VideoDocument, options?: SolveVideoDocumentOptions): VideoDraftContent;
 //#endregion
 //#region src/document/initial-document.d.ts
-/**
- * The project facts a freshly created document is built from — exactly the five
- * fields Director sets when it creates a draft row, and nothing else.
- *
- * Deliberately not a whole `VideoDraft`: tracks and the part library of a new
- * document are empty by definition, so accepting them would mean accepting
- * values that must always be empty, and every such field is a place for a future
- * caller to send something that is silently dropped. The narrow shape makes the
- * "a new document has no content" rule structural instead of a convention.
- */
-interface InitialDocumentFacts {
-  draftId: string;
-  projectId: string | undefined;
-  ownerId: string | undefined;
-  chatSessionId: string | undefined;
-  videoCreationSettings: VideoCreationSettings | undefined;
-}
 /**
  * Build the `VideoDocument` a newly created project starts from: the caller's
- * project facts, no parts, and one empty track per lane.
+ * no parts and one empty track per lane. Business facts remain in Director.
  *
  * The empty lane tracks are the reason this function exists rather than callers
  * assembling a document inline. Lane tracks are otherwise minted lazily by the
@@ -845,7 +1017,7 @@ interface InitialDocumentFacts {
  * supplies, and total duration is derived on read (RFC 02 §6), so a new document
  * has no timeline fact to state.
  */
-declare function buildInitialVideoDocument(facts: InitialDocumentFacts): VideoDocument;
+declare function buildInitialVideoDocument(): VideoDocument;
 //#endregion
 //#region ../medeo-dsl/src/ids.d.ts
 declare const entityIdBrand: unique symbol;
@@ -976,7 +1148,7 @@ declare class EntityTimelineProjectionError extends Error {
  * consulted as an editing fact. Peer IDs appear only in this derived read
  * contract, reconstructed from relations; they are not stored in payloads.
  */
-declare function projectEntityTimeline(rows: EntityRelationRows, meta: VideoDocumentMeta): VideoDocument;
+declare function projectEntityTimeline(rows: EntityRelationRows): VideoDocument;
 //#endregion
 //#region src/document/entity-timeline-layout.d.ts
 type EntityTimelineTrackRole = 'video_clip' | 'speech' | 'caption' | 'bgm';
@@ -1039,95 +1211,6 @@ declare class VideoDocumentValidationError extends Error {
 declare function assertValidVideoDocument(document: unknown): asserts document is VideoDocument;
 declare function validateVideoDocument(document: unknown): VideoDocumentValidationIssue[];
 //#endregion
-//#region src/document/mirror-schema.d.ts
-declare const videoDocumentMirrorSchema: import("loro-mirror").RootSchemaType<{
-  meta: import("loro-mirror").LoroMapSchema<{
-    schema_version: /*elided*/any;
-    draft_id: /*elided*/any;
-    project_id: /*elided*/any;
-    owner_id: /*elided*/any;
-    thumbnail_storage_key: /*elided*/any;
-    chat_session_id: /*elided*/any;
-    video_creation_settings: /*elided*/any;
-    version: /*elided*/any;
-  }> & {
-    options: {};
-  } & {
-    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
-      schema_version: /*elided*/any;
-      draft_id: /*elided*/any;
-      project_id: /*elided*/any;
-      owner_id: /*elided*/any;
-      thumbnail_storage_key: /*elided*/any;
-      chat_session_id: /*elided*/any;
-      video_creation_settings: /*elided*/any;
-      version: /*elided*/any;
-    }, C>;
-  };
-  timeline: import("loro-mirror").LoroMapSchema<{
-    unit_time_ms: /*elided*/any;
-  }> & {
-    options: {};
-  } & {
-    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
-      unit_time_ms: /*elided*/any;
-    }, C>;
-  };
-  tracks: import("loro-mirror").LoroMovableListSchema<import("loro-mirror").LoroMapSchema<{
-    id: /*elided*/any;
-    parts_kind: /*elided*/any;
-    is_hidden: /*elided*/any;
-    items: /*elided*/any;
-  }> & {
-    options: {};
-  } & {
-    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
-      id: /*elided*/any;
-      parts_kind: /*elided*/any;
-      is_hidden: /*elided*/any;
-      items: /*elided*/any;
-    }, C>;
-  }> & {
-    options: {};
-  };
-  part_library: import("loro-mirror").LoroMapSchemaWithCatchall<{}, import("loro-mirror").LoroMapSchema<{
-    video_clip: /*elided*/any;
-    speech: /*elided*/any;
-    caption: /*elided*/any;
-    bgm: /*elided*/any;
-  }> & {
-    options: {};
-  } & {
-    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
-      video_clip: /*elided*/any;
-      speech: /*elided*/any;
-      caption: /*elided*/any;
-      bgm: /*elided*/any;
-    }, C>;
-  }> & {
-    options: {};
-  };
-}> & {
-  options: {};
-};
-type VideoDocumentMirrorSchema = typeof videoDocumentMirrorSchema;
-/**
- * The mutable draft an op's `transact` callback edits, inferred from the schema.
- *
- * `InferInputType` is the schema's *input* shape: the declared business fields
- * with the `$cid` container ids (which mirror injects into its output
- * `InferType`) made optional, so ops assign plain objects without supplying
- * `$cid`. Deriving it from the schema keeps draft and storage in lockstep — a
- * schema change is a compile error at every edit site, not a silent drift.
- * Reorders within `items` still diff to real Loro `move` ops because the schema
- * keys items by `part_id`.
- */
-type VideoDocumentDraft = InferInputType<VideoDocumentMirrorSchema>;
-/** Track value as it appears in a draft. Derived from the single `tracks` movable list. */
-type TrackDraft = NonNullable<NonNullable<VideoDocumentDraft['tracks']>[number]>;
-/** A single track item in a draft. */
-type TrackItemDraft = NonNullable<NonNullable<TrackDraft['items']>[number]>;
-//#endregion
 //#region src/editor/id-gen.d.ts
 /**
  * Part-id generation, aligned with the online ecosystem.
@@ -1350,13 +1433,12 @@ interface TransactAudit {
  * position. The caller never materializes a layout (ADR 0009).
  */
 interface SemanticDocumentAdapter extends SnapshotReadable {
-  /** True once the document holds real content (a bootstrapped/synced snapshot). */
-  hasContent(): boolean;
   /**
-   * Apply one op's whole mutation in a single transaction. `edit` mutates the
-   * document draft; the adapter diffs the result and commits once with `audit`.
+   * Apply one op's domain mutation in a single synchronous transaction. `edit`
+   * must finish before returning; async callbacks/await are unsupported. The
+   * adapter diffs the resulting draft and commits once with `audit`.
    * A throw in `edit` rolls back (the draft is discarded, Loro untouched). An
-   * edit that changes nothing produces no commit (no phantom audit entry).
+   * edit that changes nothing produces no domain commit (no phantom undo step).
    */
   transact(edit: (draft: VideoDocumentDraft) => void, audit: TransactAudit): void;
 }
@@ -1492,6 +1574,19 @@ declare class SemanticEditor {
   private computeAddInsertIndex;
 }
 //#endregion
+//#region src/document/document-mutation-guard.d.ts
+/**
+ * @internal
+ * Shared by synchronous mutation entry points for one document. The session
+ * closes it before teardown callbacks can attempt another write.
+ */
+declare class DocumentMutationGuard {
+  private running;
+  private closed;
+  run<T>(mutation: () => T): T;
+  close(): void;
+}
+//#endregion
 //#region src/document/mirror-adapter.d.ts
 interface MirrorVideoDocumentOptions {
   peerId?: PeerID;
@@ -1507,22 +1602,31 @@ interface MirrorVideoDocumentOptions {
  * - `transact(edit, audit)` runs the whole op in one `mirror.setState` callback:
  *   one diff, one `doc.commit` carrying the audit message. The callback edits an
  *   immer draft, so a throw inside it discards the draft and never touches Loro
- *   (natural rollback) — no `guard` / `rollback` / `openTransaction` machinery.
+ *   (natural rollback) without a document checkout or compensating commit.
  * - mirror's `idSelector` (track items keyed by `part_id`) diffs reorders to
  *   real Loro `move` ops on every lane, so per-item CRDT identity survives on
  *   main and secondary tracks alike.
  */
 declare class MirrorVideoDocumentAdapter implements SemanticDocumentAdapter {
   readonly doc: LoroDoc;
+  private readonly mutationGuard;
   private readonly mirror;
-  constructor(doc: LoroDoc);
+  private disposed;
+  constructor(doc: LoroDoc, mutationGuard?: DocumentMutationGuard);
   snapshot(): VideoDocument;
   /**
-   * True once the doc holds real document content. A fresh mirror over an empty
-   * doc still reports defaulted root maps, so probe the stored `schema_version`
-   * (empty until a snapshot is bootstrapped or synced in).
+   * Native Entity authority: placement is already solved by the Entity graph.
+   *
+   * The root check goes through `getShallowValue` first because `getMap` creates
+   * the container on access — probing a legacy document for `medeo` would
+   * otherwise mutate it, which a read must never do.
    */
-  hasContent(): boolean;
+  isEntityDocument(): boolean;
+  /**
+   * Release mirror subscriptions; do not reuse this adapter afterwards.
+   * The caller still owns the borrowed LoroDoc.
+   */
+  dispose(): void;
   /**
    * Apply one op as a single transaction. `edit` mutates the immer draft; mirror
    * diffs the result and commits once with the audit `message`. A throw in `edit`
@@ -1530,15 +1634,12 @@ declare class MirrorVideoDocumentAdapter implements SemanticDocumentAdapter {
    * skips the commit — matching the prior "empty op leaves no audit" behavior.
    */
   transact(edit: (draft: VideoDocumentDraft) => void, audit: TransactAudit): void;
+  private assertActive;
 }
 /** Build a fresh Loro doc seeded with `document` through the mirror. */
 declare function createMirrorVideoDocument(document: VideoDocument, options?: MirrorVideoDocumentOptions): LoroDoc;
 /** Build a `MirrorVideoDocumentAdapter` over a fresh doc seeded with `document`. */
 declare function createMirrorVideoDocumentAdapter(document: VideoDocument, options?: MirrorVideoDocumentOptions): MirrorVideoDocumentAdapter;
-/** Host-only replacement of a derived view, retaining the existing Loro history. */
-declare function applyEntityTimelineProjection(doc: LoroDoc, projection: VideoDocument, entityRevision: number): Uint8Array;
-/** Write a whole `VideoDocument` into a draft (seed a fresh doc / plain-memory state). */
-declare function writeVideoDocumentToDraft(draft: VideoDocumentDraft, document: VideoDocument): void;
 //#endregion
 //#region src/document/plain-memory-adapter.d.ts
 /**
@@ -1552,6 +1653,12 @@ interface JournalEntry extends TransactAudit {
 interface PlainMemoryAdapterOptions {
   /** Underlying id mint; wrapped so each call inside a transact is journaled. */
   idFactory?: PartIdFactory;
+  /**
+   * Refuse every `transact`. Set when the seed document is an Entity projection:
+   * its timeline is owned by the Entity graph, and the document itself no longer
+   * states its provenance (business metadata left the CRDT), so the caller does.
+   */
+  readOnly?: boolean;
 }
 /**
  * Pure in-memory `SemanticDocumentAdapter` — no Loro/WASM. Holds a
@@ -1575,6 +1682,7 @@ declare class PlainMemoryAdapter implements SemanticDocumentAdapter {
    * use this so every minted id is appended to the current transact's list.
    */
   readonly idFactory: PartIdFactory;
+  private readonly readOnly;
   constructor(document: VideoDocument, options?: PlainMemoryAdapterOptions);
   get journal(): readonly JournalEntry[];
   hasContent(): boolean;
@@ -1593,9 +1701,9 @@ declare function createPlainMemoryAdapter(document: VideoDocument, options?: Pla
 /**
  * Project the mirror state (`VideoDocumentDraft`) into the authoritative
  * `VideoDocument`. The storage shape is isomorphic to the domain shape (RFC 03
- * §4, reference/17 §4: meta map + a single `tracks` list + part_library), so this
+ * §4, reference/17 §4: timeline + a single `tracks` list + part_library), so this
  * is a near-identity — it reads `time_position` / `fallback_abs_ms` JSON blobs
- * back into structured values and trims empty strings, nothing more.
+ * back into structured values and selects content fields. Legacy meta is ignored.
  *
  * It maps only authoritative facts (RFC 02 §6): `part_id` + `time_position`. The
  * projection-derived `VideoDraft` read-view (absolute time, `part_aggregations`,
@@ -1671,19 +1779,6 @@ declare const partUnionSchema: z.ZodUnion<readonly [z.ZodObject<{
   }, z.core.$loose>;
 }, z.core.$loose>]>;
 declare const videoDocumentSchema: z.ZodObject<{
-  meta: z.ZodObject<{
-    schema_version: z.ZodEnum<{
-      "video-document/v0": "video-document/v0";
-      "video-document/entity-projection-v1": "video-document/entity-projection-v1";
-    }>;
-    draft_id: z.ZodOptional<z.ZodString>;
-    project_id: z.ZodOptional<z.ZodString>;
-    owner_id: z.ZodOptional<z.ZodString>;
-    thumbnail_storage_key: z.ZodOptional<z.ZodString>;
-    chat_session_id: z.ZodOptional<z.ZodString>;
-    video_creation_settings: z.ZodOptional<z.ZodUnknown>;
-    version: z.ZodOptional<z.ZodNumber>;
-  }, z.core.$loose>;
   timeline: z.ZodOptional<z.ZodObject<{
     unit_time_ms: z.ZodOptional<z.ZodNumber>;
   }, z.core.$loose>>;
@@ -1775,4 +1870,4 @@ declare const videoDocumentSchema: z.ZodObject<{
   }, z.core.$loose>]>>>;
 }, z.core.$loose>;
 //#endregion
-export { SequenceRange as $, generatePartId as A, VideoDraft as At, ResolvedEntityClipPlacement as B, Track$1 as Bt, PlannedSemanticOpKind as C, TrackItemTimePosition as Ct, SnapshotReadable as D, VideoDocumentSchemaVersion as Dt, SchemaValidator as E, VideoDocument as Et, videoDocumentMirrorSchema as F, CaptionPart$1 as Ft, EntityTimelineProjectionError as G, ResolvedEntityTrack as H, VideoDocumentValidationError as I, CaptionStyle as It, RelationRow as J, EntityRelationRows as K, assertValidVideoDocument as L, PartAggregation as Lt, TrackItemDraft as M, effectiveVideoClipDurationMs as Mt, VideoDocumentDraft as N, speedOf as Nt, ValidationError as O, VideoDocumentValidationIssue as Ot, VideoDocumentMirrorSchema as P, Attachment as Pt, SequenceDuration as Q, validateVideoDocument as R, SpeedShift as Rt, ImplementedSemanticOpKind as S, TrackItem as St, isImplementedSemanticOpKind as T, VideoClipPart as Tt, resolveEntityTimelineLayout as U, ResolvedEntityTimelineLayout as V, TrackItem$1 as Vt, projectEntityTimeline as W, CaptionStyleFields as X, CaptionSegmentSelection as Y, ScriptTextSegment as Z, SemanticEditor as _, PartKind as _t, PlainMemoryAdapter as a, buildInitialVideoDocument as at, TransactAudit as b, Timeline as bt, MirrorVideoDocumentAdapter as c, buildSpeechHostMap as ct, createMirrorVideoDocument as d, toVideoDocument as dt, VoiceDescriptor as et, createMirrorVideoDocumentAdapter as f, BgmPart as ft, SemanticDocumentAdapter as g, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as gt, OpActor as h, DEFAULT_UNIT_TIME_MS as ht, JournalEntry as i, InitialDocumentFacts as it, TrackDraft as j, VideoDraftPartUnion as jt, PartIdFactory as k, VideoDocumentValidationIssueCode as kt, MirrorVideoDocumentOptions as l, derivePositionFromAbs as lt, CommitOptions as m, CaptionPart as mt, videoDocumentSchema as n, JsonValue as nt, PlainMemoryAdapterOptions as o, DerivedItemPosition as ot, writeVideoDocumentToDraft as p, CaptionDisplayCue as pt, EntityRow as q, readVideoDocumentFromDraft as r, EntityId as rt, createPlainMemoryAdapter as s, SpeechHostMap as st, partUnionSchema as t, JsonObject as tt, applyEntityTimelineProjection as u, fromVideoDocument as ut, SemanticOpInput as v, PartUnion as vt, SemanticOpKind as w, VIDEO_DOCUMENT_SCHEMA_VERSION as wt, IMPLEMENTED_SEMANTIC_OP_KINDS as x, Track as xt, SemanticOpName as y, SpeechPart as yt, EntityTimelineTrackRole as z, Timeline$1 as zt };
+export { SpeechHostMap as $, assertValidVideoDocument as A, VideoDocumentValidationIssueCode as At, EntityRow as B, SpeedShift as Bt, isImplementedSemanticOpKind as C, Timeline as Ct, PartIdFactory as D, VideoClipPart as Dt, ValidationError as E, TrackItemTimePosition as Et, ResolvedEntityTrack as F, speedOf as Ft, SequenceDuration as G, CaptionSegmentSelection as H, Track$1 as Ht, resolveEntityTimelineLayout as I, Attachment as It, JsonObject as J, SequenceRange as K, projectEntityTimeline as L, CaptionPart$1 as Lt, EntityTimelineTrackRole as M, VideoDraftContent as Mt, ResolvedEntityClipPlacement as N, VideoDraftPartUnion as Nt, generatePartId as O, VideoDocument as Ot, ResolvedEntityTimelineLayout as P, effectiveVideoClipDurationMs as Pt, DerivedItemPosition as Q, EntityTimelineProjectionError as R, CaptionStyle as Rt, SemanticOpKind as S, SpeechPart as St, SnapshotReadable as T, TrackItem as Tt, CaptionStyleFields as U, TrackItem$1 as Ut, RelationRow as V, Timeline$1 as Vt, ScriptTextSegment as W, EntityId as X, JsonValue as Y, buildInitialVideoDocument as Z, SemanticOpName as _, CaptionDisplayCue as _t, PlainMemoryAdapter as a, LaneKind as at, ImplementedSemanticOpKind as b, PartKind as bt, MirrorVideoDocumentAdapter as c, findLaneTrack as ct, createMirrorVideoDocumentAdapter as d, TrackDraft as dt, buildSpeechHostMap as et, CommitOptions as f, TrackItemDraft as ft, SemanticOpInput as g, BgmPart as gt, SemanticEditor as h, videoDocumentMirrorSchema as ht, JournalEntry as i, LANE_KINDS_IN_STACK_ORDER as it, validateVideoDocument as j, VideoDraft as jt, VideoDocumentValidationError as k, VideoDocumentValidationIssue as kt, MirrorVideoDocumentOptions as l, laneTrackId as lt, SemanticDocumentAdapter as m, VideoDocumentMirrorSchema as mt, videoDocumentSchema as n, fromVideoDocument as nt, PlainMemoryAdapterOptions as o, SolvedVideoDocument as ot, OpActor as p, VideoDocumentDraft as pt, VoiceDescriptor as q, readVideoDocumentFromDraft as r, toVideoDocument as rt, createPlainMemoryAdapter as s, ensureLaneTrack as st, partUnionSchema as t, derivePositionFromAbs as tt, createMirrorVideoDocument as u, solveVideoDocument as ut, TransactAudit as v, CaptionPart as vt, SchemaValidator as w, Track as wt, PlannedSemanticOpKind as x, PartUnion as xt, IMPLEMENTED_SEMANTIC_OP_KINDS as y, DEFAULT_UNIT_TIME_MS as yt, EntityRelationRows as z, PartAggregation as zt };