@mengine/medeo-client 1.0.1-alpha.2 → 1.1.0

package/dist/{index-DRUGsbm2.d.ts → index-BUKA3L7o.d.ts}

@@ -1,4 +1,3 @@
-import { E as MoveVideoClipsInput, H as AdjustVideoClipVolumeInput, I as DeleteBgmInput, J as AdjustBgmVolumeInput, K as AdjustSpeechVolumeInput, O as MoveSpeechesInput, P as DeleteSpeechesInput, Q as AddSpeechesInput, R as ChangeSpeechScriptInput, S as SetBgmInput, W as AdjustVideoClipDurationInput, X as AddVideoClipsInput, b as SetCaptionStyleInput, g as SetVideoClipSpeedShiftInput, j as DeleteVideoClipsInput, v as SetCaptionVisibilityInput, w as ReplaceVideoClipContentInput, z as ChangeSpeechVoiceInput } from "./index-6e5cbdM3.js";
 import { InferInputType } from "loro-mirror";
 import { z } from "zod";
 import { LoroDoc, PeerID } from "loro-crdt";
@@ -553,19 +552,6 @@ interface Track {
   is_hidden: boolean | undefined;
   items: TrackItem[] | undefined;
 }
-/** The linear speed multiplier of a `speed_shift`, defaulting to 1 (original). */
-declare function speedOf(speedShift: SpeedShift | undefined): number;
-/**
- * A video clip's effective timeline duration, derived from authoritative facts
- * (RFC 02, `reference/16` §4, reference/17 §5): the trim window
- * `play_out - play_in` divided by the speed multiplier, rounded to integer ms.
- * `play_in` / `play_out` are optional in the IDL but every write path sets them
- * (defaulting to the whole media), and the legacy-ingest projection backfills the
- * window from a legacy `duration_ms` — so an authoritative clip always carries a
- * trim window and there is no stored `duration_ms` to fall back to. A clip with
- * neither bound yields 0. Speeds the clip up (>1× → shorter) or down (<1×).
- */
-declare function effectiveVideoClipDurationMs(clip: VideoClipPart): number;
 /**
  * Authoritative part union: a flat discriminated union over the four part kinds.
  * Deliberately *not* the IDL's namespace union (no `$unknown` / `visit`): engine
@@ -682,7 +668,7 @@ interface VideoDocument {
   tracks: Track[] | undefined;
   part_library: Record<string, PartUnion> | undefined;
 }
-type VideoDocumentValidationIssueCode = 'invalid_schema' | 'duplicate_track_item_identity' | 'unknown_part_kind' | 'part_kind_mismatch' | 'missing_part_reference' | 'track_kind_mismatch' | 'main_track_non_video_clip' | 'invalid_part_value' | 'invalid_speech_caption_reference' | 'invalid_position_anchor';
+type VideoDocumentValidationIssueCode = 'invalid_schema' | 'duplicate_track_item_identity' | 'duplicate_lane_track' | 'unknown_part_kind' | 'part_kind_mismatch' | 'missing_part_reference' | 'track_kind_mismatch' | 'main_track_non_video_clip' | 'invalid_part_value' | 'invalid_speech_caption_reference' | 'invalid_position_anchor';
 /**
  * Issue severity (RFC 02 §11.1). `error` is a hard reject — the document is not
  * a legal `VideoDocument` and must not be projected. `recoverable` marks a
@@ -765,6 +751,49 @@ declare function derivePositionFromAbs(partId: string, abs: number, isMain: bool
  */
 declare function fromVideoDocument(document: VideoDocument): VideoDraft;
 //#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.
+ *
+ * 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
+ * first op that needs one (`ensureLaneTrack`), which is find-then-mint over a
+ * CRDT list — so if the Agent's first generation and a user edit race on an
+ * empty document, each mints its own copy of the same lane and the merge keeps
+ * both. Two video_clip tracks violate the at-most-one-main-track rule, and the
+ * merged document becomes unprojectable for *every* reader (editor, render,
+ * share) with no winning replica to fall back on. Seeding all four lanes up
+ * front means `ensureLaneTrack` only ever finds, never mints, so the race cannot
+ * happen on a document created here.
+ *
+ * All four, not just the main lane: the secondary lanes fail less loudly (a
+ * duplicate pane rather than an unreadable document), but they fail by the same
+ * mechanism, and covering only the fatal one would leave three live races.
+ *
+ * `timeline` is left absent: `unit_time_ms` is a display concern the editor
+ * 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;
+//#endregion
 //#region src/document/validation.d.ts
 /**
  * Business-level schema guard for `VideoDocument` (RFC 03 §9). It is the gate
@@ -882,35 +911,611 @@ 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
+//#region src/editor/schemas/add-speeches.d.ts
+/**
+ * Add speeches (and their captions). TTS runs upstream; the stable speech /
+ * caption parts arrive materialized (see `speech-assets.ts`). The op writes the
+ * parts and each speech's `{ mode:'anchored', anchorPartId, offsetMs }` fact
+ * verbatim — no write-time host-picking, no cascade (RFC 02 §4). The projection
+ * derives absolute positions on read.
+ */
+declare const addSpeechesInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    anchor_part_id: z.ZodString;
+    offset_ms: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    duration_ms: z.ZodNumber;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    voice: z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    origin_speech_id: z.ZodString;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  captions: z.ZodArray<z.ZodObject<{
+    caption_id: z.ZodString;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    duration_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AddSpeechesInput = z.infer<typeof addSpeechesInputSchema>;
+//#endregion
+//#region src/editor/schemas/add-video-clips.d.ts
+/**
+ * Add video clips to a track. Each clip's duration facts are separated so a
+ * single number is never overloaded (RFC 02 / `reference/16` §0b):
+ *
+ * - `media_duration_ms` is the source media's intrinsic full length (a resource
+ *   fact, written to the part);
+ * - `play_in` / `play_out` are the optional trim window into that media; when
+ *   omitted the whole media is used (`play_in=0`, `play_out=media_duration_ms`).
+ *
+ * The clip's effective timeline duration is derived by the projection from the
+ * trim window and `speed_shift` — it is never an input here.
+ */
+declare const addVideoClipsInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    media_id: z.ZodString;
+    start_ms: z.ZodOptional<z.ZodNumber>;
+    media_duration_ms: z.ZodNumber;
+    play_in: z.ZodOptional<z.ZodNumber>;
+    play_out: z.ZodOptional<z.ZodNumber>;
+    track_id: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  before_clip_id: z.ZodOptional<z.ZodString>;
+  after_clip_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AddVideoClipsInput = z.infer<typeof addVideoClipsInputSchema>;
+//#endregion
+//#region src/editor/schemas/adjust-bgm-volume.d.ts
+declare const adjustBgmVolumeInputSchema: z.ZodObject<{
+  bgm: z.ZodArray<z.ZodObject<{
+    bgm_id: z.ZodString;
+    volume: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AdjustBgmVolumeInput = z.infer<typeof adjustBgmVolumeInputSchema>;
+//#endregion
+//#region src/editor/schemas/adjust-speech-volume.d.ts
+declare const adjustSpeechVolumeInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    volume: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AdjustSpeechVolumeInput = z.infer<typeof adjustSpeechVolumeInputSchema>;
+//#endregion
+//#region src/editor/schemas/adjust-video-clip-duration.d.ts
+/**
+ * Re-trim existing video clips (the user-facing "adjust duration" gesture is a
+ * trim of the source window). The new `play_in` / `play_out` are the facts; the
+ * effective timeline duration is derived from them and the clip's `speed_shift`,
+ * and the change reflows downstream clips, speeches, and the timeline inside the
+ * op's transaction (no caller-materialized cascade).
+ */
+declare const adjustVideoClipDurationInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    play_in: z.ZodNumber;
+    play_out: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AdjustVideoClipDurationInput = z.infer<typeof adjustVideoClipDurationInputSchema>;
+//#endregion
+//#region src/editor/schemas/adjust-video-clip-volume.d.ts
+declare const adjustVideoClipVolumeInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    volume: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AdjustVideoClipVolumeInput = z.infer<typeof adjustVideoClipVolumeInputSchema>;
+//#endregion
+//#region src/editor/schemas/change-speech.d.ts
+/**
+ * Change a speech's script or voice. Both re-run TTS upstream and return the
+ * regenerated speech / caption parts in the same materialized shape as
+ * `AddSpeeches` (`speech-assets.ts`); the op upserts them by id (the speech part
+ * id is preserved across a re-TTS), re-seats at `start_ms`, and reflows. Old
+ * caption parts no longer owned by the speech are removed via `caption_ids`.
+ */
+declare const changeSpeechScriptInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    anchor_part_id: z.ZodString;
+    offset_ms: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    duration_ms: z.ZodNumber;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    voice: z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    origin_speech_id: z.ZodString;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  captions: z.ZodArray<z.ZodObject<{
+    caption_id: z.ZodString;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    duration_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const changeSpeechVoiceInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    anchor_part_id: z.ZodString;
+    offset_ms: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    duration_ms: z.ZodNumber;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    voice: z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    origin_speech_id: z.ZodString;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  captions: z.ZodArray<z.ZodObject<{
+    caption_id: z.ZodString;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    duration_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type ChangeSpeechScriptInput = z.infer<typeof changeSpeechScriptInputSchema>;
+type ChangeSpeechVoiceInput = z.infer<typeof changeSpeechVoiceInputSchema>;
+//#endregion
+//#region src/editor/schemas/delete-bgm.d.ts
+/**
+ * Remove the document BGM. Pure document edit: clears the bgm lane and removes
+ * the bgm part. Takes no input (a document holds at most one bgm); an empty
+ * object keeps the op signature uniform with the rest.
+ */
+declare const deleteBgmInputSchema: z.ZodObject<{}, z.core.$strip>;
+type DeleteBgmInput = z.infer<typeof deleteBgmInputSchema>;
+//#endregion
+//#region src/editor/schemas/delete-speeches.d.ts
+/**
+ * Delete speeches with their captions. Pure document edit (no side effect): the
+ * op removes each speech part, cascade-deletes the captions it owns (via
+ * `caption_ids` / `speech_part_id`), drops their track items, and reflows.
+ */
+declare const deleteSpeechesInputSchema: z.ZodObject<{
+  speech_ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type DeleteSpeechesInput = z.infer<typeof deleteSpeechesInputSchema>;
+//#endregion
+//#region src/editor/schemas/delete-video-clips.d.ts
+/**
+ * How a delete handles the anchored subtree (speeches anchored to a deleted clip,
+ * and their captions) — a delete-op policy, not a data-model field (reference/17
+ * §6). `cascade` (default) removes the subtree; `detach` keeps the direct
+ * anchored children, re-pinning them to `absolute` so they stay on the timeline.
+ */
+declare const anchoredDeletePolicySchema: z.ZodEnum<{
+  cascade: "cascade";
+  detach: "detach";
+}>;
+type AnchoredDeletePolicy = z.infer<typeof anchoredDeletePolicySchema>;
+declare const deleteVideoClipsInputSchema: z.ZodObject<{
+  clip_ids: z.ZodArray<z.ZodString>;
+  on_anchored: z.ZodOptional<z.ZodEnum<{
+    cascade: "cascade";
+    detach: "detach";
+  }>>;
+}, z.core.$strip>;
+type DeleteVideoClipsInput = z.infer<typeof deleteVideoClipsInputSchema>;
+//#endregion
+//#region src/editor/schemas/move-speeches.d.ts
+/**
+ * Move speeches in time. Pure document edit: the op re-seats each speech at its
+ * new absolute `start_ms`; the cascade reassigns it to the host video clip,
+ * resolves overlaps, and reflows. Captions follow their speech.
+ */
+declare const moveSpeechesInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    new_start_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type MoveSpeechesInput = z.infer<typeof moveSpeechesInputSchema>;
+//#endregion
+//#region src/editor/schemas/move-video-clips-by-anchor.d.ts
+/**
+ * Where the moved block lands on the main track.
+ *
+ * A discriminated union rather than two optional `before_clip_id` /
+ * `after_clip_id` fields (the shape `addVideoClips` had to use, because there the
+ * two modes share a whole clip description): here the alternatives carry nothing
+ * in common, so making them mutually exclusive *by type* removes three runtime
+ * `superRefine` checks that would otherwise have to be written and tested.
+ *
+ * `track_start` is an explicit member, not the absence of an anchor. The
+ * agent-harness mutation this maps from treats "neither anchor given" as
+ * "move to the front" (`applyBatchMoveVideoClips` falls back to `insertIndex = 0`),
+ * which is a default buried in a tool description. Requiring the caller to name
+ * that intent keeps a forgotten field from silently reordering the timeline.
+ */
+declare const moveAnchorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  position: z.ZodLiteral<"before">;
+  clip_id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  position: z.ZodLiteral<"after">;
+  clip_id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  position: z.ZodLiteral<"track_start">;
+}, z.core.$strip>], "position">;
+/**
+ * What happens to the speeches anchored to the clips being moved.
+ *
+ * - `follow` keeps each speech anchored where it is, so it travels with its clip
+ *   to the new position. In the anchored model this is the *no-op* branch: a
+ *   speech's authoritative fact is `{ anchorPartId, offsetMs }` and its absolute
+ *   time is derived on read from the host's position, so moving the host moves
+ *   the speech with no write to the speech at all.
+ * - `keep_absolute` preserves each speech's current absolute landing instead, then
+ *   re-anchors it to whichever clip now covers that time (RFC 02 §9.1/§11.1). This
+ *   is the branch that costs an extra pass, and the one the FE timeline uses.
+ *
+ * **Required, with no default**, matching `deleteVideoClips` and
+ * `replaceVideoClipSequence`. The two branches decide which picture the user's
+ * narration ends up over, which is too consequential to infer from a missing
+ * field — and neither branch is "safe enough" to be the implicit one.
+ */
+declare const movedClipAnchoredPolicySchema: z.ZodEnum<{
+  follow: "follow";
+  keep_absolute: "keep_absolute";
+}>;
+/**
+ * Reorder a set of main-track clips relative to a reference clip.
+ *
+ * Distinct from `moveVideoClips`, which positions clips by absolute time
+ * (`new_start_ms`) and is what the FE timeline dispatches after a drag. Main-track
+ * clips are `sequential`-positioned, so absolute time is not authoritative state
+ * there (RFC 02 §4/§7): `moveVideoClips` has to *guess* an index back out of the
+ * time it was handed, whereas an anchor already is the ordinal fact being changed.
+ * Keeping them separate also isolates blast radius — this method can diverge on
+ * speech policy without touching the FE path.
+ *
+ * `clip_ids` need not be contiguous. They move as one block, keeping their
+ * relative order, which is the agent-harness `batch_move_video_clips` contract.
+ */
+declare const moveVideoClipsByAnchorInputSchema: z.ZodObject<{
+  clip_ids: z.ZodArray<z.ZodString>;
+  anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    position: z.ZodLiteral<"before">;
+    clip_id: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    position: z.ZodLiteral<"after">;
+    clip_id: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    position: z.ZodLiteral<"track_start">;
+  }, z.core.$strip>], "position">;
+  on_anchored: z.ZodEnum<{
+    follow: "follow";
+    keep_absolute: "keep_absolute";
+  }>;
+}, z.core.$strip>;
+type MoveAnchor = z.infer<typeof moveAnchorSchema>;
+type MovedClipAnchoredPolicy = z.infer<typeof movedClipAnchoredPolicySchema>;
+type MoveVideoClipsByAnchorInput = z.infer<typeof moveVideoClipsByAnchorInputSchema>;
+//#endregion
+//#region src/editor/schemas/move-video-clips.d.ts
+declare const moveVideoClipsInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    new_start_ms: z.ZodNumber;
+    new_track_id: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type MoveVideoClipsInput = z.infer<typeof moveVideoClipsInputSchema>;
+//#endregion
+//#region src/editor/schemas/replace-video-clip-content.d.ts
+/**
+ * Replace the media backing existing video clips. The media import runs upstream
+ * (Director); its stable result — the new media id, intrinsic length, and the
+ * reset trim window — arrives materialized (see
+ * `results/phase-4-side-effect-payload-contract.md` §4). Director resets
+ * `play_in=0` / `play_out=media_duration_ms` and clears `speed_shift` on
+ * replacement. The clip `part_id`s (hence their track items) are unchanged; the
+ * editor reflows the main track from the new effective durations.
+ */
+declare const replaceVideoClipContentInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    origin_media_id: z.ZodString;
+    media_duration_ms: z.ZodNumber;
+    play_in: z.ZodNumber;
+    play_out: z.ZodNumber;
+    volume: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type ReplaceVideoClipContentInput = z.infer<typeof replaceVideoClipContentInputSchema>;
+//#endregion
+//#region src/editor/schemas/replace-video-clip-sequence.d.ts
+/**
+ * What happens to the speeches anchored to the clips being replaced.
+ *
+ * - `remap` re-anchors each surviving speech to the new clip in the SAME POSITION
+ *   of the sequence, keeping its offset — old[i]'s children become new[i]'s
+ *   children. An old clip with no counterpart (fewer new clips than old) has its
+ *   subtree deleted, because there is nothing left to anchor to.
+ * - `cascade` deletes every anchored speech (and its captions) outright, like
+ *   `deleteVideoClips`.
+ *
+ * **Required, with no default.** The two branches differ in whether the user's
+ * narration survives, and the agent tool that drives this op makes its
+ * `preserve_speeches` flag required for that reason. A default here would let a
+ * caller that forgot the field silently delete speech.
+ */
+declare const anchoredReplacePolicySchema: z.ZodEnum<{
+  cascade: "cascade";
+  remap: "remap";
+}>;
+type AnchoredReplacePolicy = z.infer<typeof anchoredReplacePolicySchema>;
 /**
- * Part-id generation, aligned with the online ecosystem.
+ * Replace a contiguous run of main-track clips with a new run.
  *
- * The authoritative online producers — agent-harness (`@harness/shared`
- * `genObjId`) and director.v2 (`common/obj_id.py` `gen_obj_id`) — both mint part
- * ids as `` `${prefix}_${ulid()}` ``, and real captured drafts use exactly that
- * shape (`clip_…` / `spe_…` / `cap_…` / `bgm_…`, each a 26-char ULID). The engine
- * previously emitted `vc_<base36 timestamp><6 random>`, a different prefix AND a
- * different encoding — the sole cross-repo id divergence. This module removes it
- * by emitting the same `<prefix>_<ULID>` bytes.
+ * A composite of delete + insert that cannot be expressed as the two ops in
+ * sequence, because the anchored speeches have to survive *across* the swap: with
+ * `remap` they are re-anchored positionally, which needs both the old and the new
+ * ids in the same transaction (ADR 0009 — the cascade stays in the editor, callers
+ * never re-wire anchors themselves).
+ *
+ * Duration facts follow `addVideoClips`: `media_duration_ms` is the source's
+ * intrinsic length and the trim window defaults to the whole media. The effective
+ * timeline duration is derived by the projection, never an input.
+ *
+ * `media_id` is optional: omitting it creates a **deliberate empty placeholder
+ * clip** (`origin_media_id: ''`) — structure with no picture. This is the only op
+ * that can produce one, and it is authoritative state, unlike the gap fillers the
+ * read-side solve mints (which never enter the document).
+ */
+declare const replaceVideoClipSequenceInputSchema: z.ZodObject<{
+  old_clip_ids: z.ZodArray<z.ZodString>;
+  new_clips: z.ZodArray<z.ZodObject<{
+    media_id: z.ZodOptional<z.ZodString>;
+    media_duration_ms: z.ZodNumber;
+    play_in: z.ZodOptional<z.ZodNumber>;
+    play_out: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>;
+  on_anchored: z.ZodEnum<{
+    cascade: "cascade";
+    remap: "remap";
+  }>;
+}, z.core.$strip>;
+type ReplaceVideoClipSequenceInput = z.infer<typeof replaceVideoClipSequenceInputSchema>;
+//#endregion
+//#region src/editor/schemas/set-bgm.d.ts
+/**
+ * Set the document BGM. The media's stable result (storage key) arrives
+ * materialized from upstream (see
+ * `results/phase-4-side-effect-payload-contract.md` §3). The op upserts the bgm
+ * part and seats it on the bgm lane; its effective length is always the whole
+ * timeline, derived by the projection on read — so there is no `duration_ms`
+ * input or fact (RFC 02 / `reference/16` §0b). A `bgm_id` lets the op replace an
+ * existing bgm part by id.
+ */
+declare const setBgmInputSchema: z.ZodObject<{
+  bgm_id: z.ZodString;
+  audio_storage_key: z.ZodString;
+  origin_media_id: z.ZodString;
+  volume: z.ZodNumber;
+}, z.core.$strip>;
+type SetBgmInput = z.infer<typeof setBgmInputSchema>;
+//#endregion
+//#region src/editor/schemas/set-caption-style.d.ts
+/**
+ * Set the caption visual style. GLOBAL by design: the style applies to every
+ * caption part in the document — it carries NO `caption_id`. This mirrors the FE,
+ * whose caption-style store (`caption-style.ts:persistCaptionStylePatch`) iterates
+ * ALL captions and writes the same normalized style to each; the product has a
+ * single document-wide caption style, not per-caption styling.
+ *
+ * Every field is optional and maps to a `CaptionStyle` attribute (snake_case
+ * IDL). A field present in the input is written to every caption; a field ABSENT
+ * from the input is left untouched on each caption (the editor merges the patch
+ * onto each caption's existing style — this is a value edit, not a full-style
+ * replace, so a partial patch such as "recolor only" does not wipe font size).
+ *
+ * Pure document edit, no cascade — captions keep their positions; only the style
+ * sub-map of each caption part changes.
+ */
+declare const setCaptionStyleInputSchema: z.ZodObject<{
+  font_id: z.ZodOptional<z.ZodString>;
+  font_size: z.ZodOptional<z.ZodNumber>;
+  font_color: z.ZodOptional<z.ZodString>;
+  font_weight: z.ZodOptional<z.ZodNumber>;
+  entrance_animation: z.ZodOptional<z.ZodString>;
+  entrance_animation_duration_ms: z.ZodOptional<z.ZodNumber>;
+  stroke_color: z.ZodOptional<z.ZodString>;
+  stroke_width: z.ZodOptional<z.ZodNumber>;
+  position_x: z.ZodOptional<z.ZodNumber>;
+  position_y: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type SetCaptionStyleInput = z.infer<typeof setCaptionStyleInputSchema>;
+//#endregion
+//#region src/editor/schemas/set-caption-visibility.d.ts
+/**
+ * Toggle caption visibility (the caption track's `is_hidden` flag). Pure
+ * document edit, no cascade — captions keep their positions; only the lane's
+ * hidden flag changes.
+ */
+declare const setCaptionVisibilityInputSchema: z.ZodObject<{
+  is_hidden: z.ZodBoolean;
+}, z.core.$strip>;
+type SetCaptionVisibilityInput = z.infer<typeof setCaptionVisibilityInputSchema>;
+//#endregion
+//#region src/editor/schemas/set-video-clip-speed-shift.d.ts
+/**
+ * Set the playback speed of existing video clips. Per the speed-shift decision
+ * (`reference/16` §0): the op writes only the `speed_shift` fact — it does NOT
+ * store an effective `duration_ms` (projection derives it from the trim window /
+ * speed) and does NOT scale anchored speeches' relative offsets (offsets stay
+ * put; the cascade reflows absolute positions). A `null` speed_shift clears the
+ * speed back to original (1×).
+ */
+declare const setVideoClipSpeedShiftInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    speed_shift: z.ZodNullable<z.ZodObject<{
+      category: z.ZodEnum<{
+        curve: "curve";
+        linear: "linear";
+      }>;
+      mode: z.ZodString;
+      config: z.ZodUnion<readonly [z.ZodObject<{
+        linear: z.ZodObject<{
+          speed: z.ZodNumber;
+        }, z.core.$strip>;
+      }, z.core.$strip>, z.ZodObject<{
+        curve: z.ZodObject<{
+          keyframes: z.ZodArray<z.ZodObject<{
+            position: z.ZodNumber;
+            rate: z.ZodNumber;
+            in_tangent: z.ZodOptional<z.ZodObject<{
+              x: z.ZodNumber;
+              y: z.ZodNumber;
+            }, z.core.$strip>>;
+            out_tangent: z.ZodOptional<z.ZodObject<{
+              x: z.ZodNumber;
+              y: z.ZodNumber;
+            }, z.core.$strip>>;
+          }, z.core.$strip>>;
+        }, z.core.$strip>;
+      }, z.core.$strip>]>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type SetVideoClipSpeedShiftInput = z.infer<typeof setVideoClipSpeedShiftInputSchema>;
+//#endregion
+//#region src/editor/schemas/shared.d.ts
+declare const clipIdSchema: z.ZodString;
+declare const clipIdsSchema: z.ZodArray<z.ZodString>;
+declare const mediaIdSchema: z.ZodString;
+declare const speechIdSchema: z.ZodString;
+declare const timelineMsSchema: z.ZodNumber;
+declare const positiveMsSchema: z.ZodNumber;
+declare const volumeSchema: z.ZodNumber;
+declare const speechIdsSchema: z.ZodArray<z.ZodString>;
+/**
+ * A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.
+ * Mirrors the IDL `SpeedShift`: `category` is `linear` | `curve`, and `config`
+ * is a discriminated union — `{ linear: { speed } }` for a constant multiplier
+ * (the multiplier projection reads at `config.linear.speed`) or `{ curve: {
+ * keyframes } }` for a Bezier-controlled variable speed (RFC 02 / `reference/16`
+ * §0). Exactly one of `linear` / `curve` is present.
+ */
+declare const speedShiftSchema: z.ZodObject<{
+  category: z.ZodEnum<{
+    curve: "curve";
+    linear: "linear";
+  }>;
+  mode: z.ZodString;
+  config: z.ZodUnion<readonly [z.ZodObject<{
+    linear: z.ZodObject<{
+      speed: z.ZodNumber;
+    }, z.core.$strip>;
+  }, z.core.$strip>, z.ZodObject<{
+    curve: z.ZodObject<{
+      keyframes: z.ZodArray<z.ZodObject<{
+        position: z.ZodNumber;
+        rate: z.ZodNumber;
+        in_tangent: z.ZodOptional<z.ZodObject<{
+          x: z.ZodNumber;
+          y: z.ZodNumber;
+        }, z.core.$strip>>;
+        out_tangent: z.ZodOptional<z.ZodObject<{
+          x: z.ZodNumber;
+          y: z.ZodNumber;
+        }, z.core.$strip>>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }, z.core.$strip>]>;
+}, z.core.$strip>;
+declare const voiceSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+//#region src/editor/schemas/speech-assets.d.ts
+/**
+ * The materialized TTS result shared by `AddSpeeches` / `ChangeSpeechScript` /
+ * `ChangeSpeechVoice` (see `results/phase-4-side-effect-payload-contract.md`
+ * §1/§2). The side effect (TTS/ASR + billing) runs upstream; the op receives the
+ * stable speech + caption parts and writes them as authoritative facts. No
+ * cascade runs on write — the projection derives absolute positions on read.
  *
- * The ULID is generated inline (Crockford Base32, 48-bit time + 80-bit random)
- * rather than pulling the `ulid` npm package: the randomness class matches the
- * old generator (both `Math.random`-based) and it keeps `@mengine/medeo-client`
- * dependency-free for a purely mechanical id string. Part ids only need to be
- * unique and lexicographically time-sortable, which this satisfies.
- */
-/**
- * Online part-id semantic prefixes. `clip` (video clip) is the only value the
- * engine currently mints (see `addVideoClips`); the rest are declared so the
- * type documents the shared vocabulary and guards against reintroducing the old
- * `vc`/`sp`/`cp`/`bg` names. Speech/caption/bgm ids arrive pre-minted in op
- * payloads, so the engine never generates them itself.
- */
-type PartIdPrefix = 'clip' | 'spe' | 'cap' | 'bgm' | 'ti';
-declare function generatePartId(prefix: PartIdPrefix): string;
-/** Injectable part-id mint; defaults to `generatePartId` on `SemanticEditor`. */
-type PartIdFactory = (prefix: PartIdPrefix) => string;
+ * Each speech carries the anchoring fact directly (RFC 02 §4): the host video
+ * clip `anchor_part_id` and the `offset_ms` within it. The upstream caller
+ * already knows which clip a speech attaches to, so the op writes
+ * `{ mode:'anchored', anchorPartId, offsetMs }` verbatim — no write-time
+ * host-picking. Captions anchor to their speech via the caption part's
+ * `start_ms` (offset within the speech).
+ */
+declare const speechAssetSchema: z.ZodObject<{
+  speech_id: z.ZodString;
+  anchor_part_id: z.ZodString;
+  offset_ms: z.ZodNumber;
+  audio_storage_key: z.ZodString;
+  duration_ms: z.ZodNumber;
+  audio_script: z.ZodString;
+  volume: z.ZodNumber;
+  voice: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+  }, z.core.$strip>;
+  origin_speech_id: z.ZodString;
+  caption_ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const captionAssetSchema: z.ZodObject<{
+  caption_id: z.ZodString;
+  speech_part_id: z.ZodString;
+  text: z.ZodString;
+  start_ms: z.ZodNumber;
+  duration_ms: z.ZodNumber;
+}, z.core.$strip>;
+/** A materialized speech-subtree write (speeches + their captions). */
+declare const speechAssetsSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    anchor_part_id: z.ZodString;
+    offset_ms: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    duration_ms: z.ZodNumber;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    voice: z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    origin_speech_id: z.ZodString;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  captions: z.ZodArray<z.ZodObject<{
+    caption_id: z.ZodString;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    duration_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type SpeechAsset = z.infer<typeof speechAssetSchema>;
+type CaptionAsset = z.infer<typeof captionAssetSchema>;
+type SpeechAssets = z.infer<typeof speechAssetsSchema>;
+declare namespace index_d_exports {
+  export { AddSpeechesInput, AddVideoClipsInput, AdjustBgmVolumeInput, AdjustSpeechVolumeInput, AdjustVideoClipDurationInput, AdjustVideoClipVolumeInput, AnchoredDeletePolicy, AnchoredReplacePolicy, CaptionAsset, ChangeSpeechScriptInput, ChangeSpeechVoiceInput, DeleteBgmInput, DeleteSpeechesInput, DeleteVideoClipsInput, MoveAnchor, MoveSpeechesInput, MoveVideoClipsByAnchorInput, MoveVideoClipsInput, MovedClipAnchoredPolicy, ReplaceVideoClipContentInput, ReplaceVideoClipSequenceInput, SetBgmInput, SetCaptionStyleInput, SetCaptionVisibilityInput, SetVideoClipSpeedShiftInput, SpeechAsset, SpeechAssets, addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, anchoredDeletePolicySchema, anchoredReplacePolicySchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, clipIdSchema, clipIdsSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, mediaIdSchema, moveAnchorSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, movedClipAnchoredPolicySchema, positiveMsSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, speechAssetsSchema, speechIdSchema, speechIdsSchema, speedShiftSchema, timelineMsSchema, voiceSchema, volumeSchema };
+}
 //#endregion
 //#region src/editor/schema-validator.d.ts
 interface SnapshotReadable {
@@ -923,11 +1528,33 @@ declare class ValidationError extends Error {
 }
 declare class SchemaValidator {
   validateMoveVideoClips(input: MoveVideoClipsInput, doc: SnapshotReadable): void;
+  /**
+   * The anchor must not be one of the clips being moved. Unlike the schema's
+   * mutual exclusions this needs the input read as a whole, so it stays here.
+   *
+   * Rejected rather than normalized: "put this block before itself" has no
+   * defensible outcome — treating it as a no-op hides a caller bug behind a
+   * success, and picking any surviving neighbour invents an intent. The legacy
+   * `applyBatchMoveVideoClips` omits this check (a self-anchor there silently
+   * lands the block at its own pre-move index); director's original move tool
+   * did enforce it (`_validate_position`: "不是被移动的clips"), and that is the
+   * behaviour worth keeping.
+   */
+  validateMoveVideoClipsByAnchor(input: MoveVideoClipsByAnchorInput, doc: SnapshotReadable): void;
   validateDeleteVideoClips(input: DeleteVideoClipsInput, doc: SnapshotReadable): void;
   validateAddVideoClips(input: AddVideoClipsInput, doc: SnapshotReadable): void;
   validateAdjustVideoClipVolume(input: AdjustVideoClipVolumeInput, doc: SnapshotReadable): void;
   validateSetVideoClipSpeedShift(input: SetVideoClipSpeedShiftInput, doc: SnapshotReadable): void;
   validateReplaceVideoClipContent(input: ReplaceVideoClipContentInput, doc: SnapshotReadable): void;
+  /**
+   * `old_clip_ids` must name a **contiguous run of the main track, in track
+   * order**. A sparse or reordered selection is rejected rather than normalized:
+   * a sparse selection has no single stretch to swap, so the insert index, the
+   * positional speech remap, and the resulting order would each need a different
+   * arbitrary choice. Mirrors the agent tool's own contract ("must be a
+   * contiguous main-track sequence listed in timeline order").
+   */
+  validateReplaceVideoClipSequence(input: ReplaceVideoClipSequenceInput, doc: SnapshotReadable): void;
   validateAdjustVideoClipDuration(input: AdjustVideoClipDurationInput, doc: SnapshotReadable): void;
   validateAdjustSpeechVolume(input: AdjustSpeechVolumeInput, doc: SnapshotReadable): void;
   validateAdjustBgmVolume(input: AdjustBgmVolumeInput, doc: SnapshotReadable): void;
@@ -987,7 +1614,7 @@ declare class SchemaValidator {
  * side-effect payload contract in
  * `docs/projects/medeo-integration/results/phase-4-side-effect-payload-contract.md`.
  */
-type ImplementedSemanticOpKind = 'MoveVideoClips' | 'DeleteVideoClips' | 'AddVideoClips' | 'AdjustVideoClipVolume' | 'SetVideoClipSpeedShift' | 'ReplaceVideoClipContent' | 'AdjustVideoClipDuration' | 'AddSpeeches' | 'DeleteSpeeches' | 'MoveSpeeches' | 'ChangeSpeechScript' | 'ChangeSpeechVoice' | 'AdjustSpeechVolume' | 'SetCaptionVisibility' | 'SetCaptionStyle' | 'SetBgm' | 'DeleteBgm' | 'AdjustBgmVolume';
+type ImplementedSemanticOpKind = 'MoveVideoClips' | 'MoveVideoClipsByAnchor' | 'DeleteVideoClips' | 'AddVideoClips' | 'AdjustVideoClipVolume' | 'SetVideoClipSpeedShift' | 'ReplaceVideoClipContent' | 'ReplaceVideoClipSequence' | 'AdjustVideoClipDuration' | 'AddSpeeches' | 'DeleteSpeeches' | 'MoveSpeeches' | 'ChangeSpeechScript' | 'ChangeSpeechVoice' | 'AdjustSpeechVolume' | 'SetCaptionVisibility' | 'SetCaptionStyle' | 'SetBgm' | 'DeleteBgm' | 'AdjustBgmVolume';
 /**
  * Operations on the roadmap but NOT yet implemented by `SemanticEditor`. Empty:
  * Phase 4 covers every op with a real entry point. Kept as a named type so the
@@ -1007,24 +1634,56 @@ declare const IMPLEMENTED_SEMANTIC_OP_KINDS: readonly ImplementedSemanticOpKind[
 declare function isImplementedSemanticOpKind(kind: string): kind is ImplementedSemanticOpKind;
 //#endregion
 //#region src/editor/semantic-editor.d.ts
+/**
+ * Who authored an op, recorded in the commit message alongside `semantic_op`.
+ *
+ * Rides the Loro commit message rather than a wire field or a storage column,
+ * for the same reason the semantic metadata does (`rfc/05 §5`): the message
+ * travels inside the update bytes, so attribution cannot disagree with the ops
+ * it describes, and it survives log truncation — a normal snapshot carries the
+ * full history, so folding and deleting update rows keeps every Change's message
+ * readable. A per-row column would lose the attribution at the first re-snapshot
+ * and could only record one author per push, while one push may carry several
+ * Changes.
+ *
+ * `role` deliberately mirrors the legacy `video_draft_op_records.operator_role`
+ * enum (`'user' | 'agent'`) so the two engines answer "was this a person or the
+ * agent" with the same vocabulary. It is declared rather than inferred from the
+ * Loro peer id: peer ranges separate the writers today, but that is an audit aid
+ * by convention, not an enforced fact, and peer ids are deliberately NOT derived
+ * from identity (`PeerId != userid`, adr/0012).
+ *
+ * A deliberately narrow shape: no client/platform field. That is telemetry, and
+ * document history is permanent and undeletable — the wrong place for it. Adding
+ * one later costs nothing (the message is JSON; older Changes simply lack the
+ * key), so the omission does not close the door.
+ *
+ * **Self-reported.** The client writes this and no server verifies it. The
+ * authorization principal is the `medeo-user-id` header, which mengine-server
+ * owner-checks; this field is the author, which it does not. The two hold the
+ * same value today but answer different questions — see the harness's mengine
+ * repository for why they are passed separately.
+ */
+interface OpActor {
+  user_id: string;
+  role: 'user' | 'agent';
+}
 interface CommitOptions {
-  /**
-   * Caller-supplied intent attached to the op's audit message.
-   *
-   * Typed as `unknown` to match `TransactAudit.intent`. The wire (real
-   * mengine-server and the in-memory test double) only surfaces **string**
-   * intents onto the audit log — non-string values stay in the Loro commit
-   * message but parse to `null`. Agent callers should pass a string.
-   */
-  intent?: unknown;
+  intent?: {
+    kind: string;
+    payload: unknown;
+  };
+  /** Author of this op; omitted for writes with no acting user (bootstrap, repair). */
+  actor?: OpActor;
 }
-type SemanticOpInput = MoveVideoClipsInput | DeleteVideoClipsInput | AddVideoClipsInput | AdjustVideoClipVolumeInput | AdjustSpeechVolumeInput | AdjustBgmVolumeInput | SetVideoClipSpeedShiftInput | ReplaceVideoClipContentInput | AdjustVideoClipDurationInput | AddSpeechesInput | DeleteSpeechesInput | MoveSpeechesInput | SetCaptionVisibilityInput | SetCaptionStyleInput | SetBgmInput | DeleteBgmInput;
+type SemanticOpInput = MoveVideoClipsInput | MoveVideoClipsByAnchorInput | DeleteVideoClipsInput | AddVideoClipsInput | AdjustVideoClipVolumeInput | AdjustSpeechVolumeInput | AdjustBgmVolumeInput | SetVideoClipSpeedShiftInput | ReplaceVideoClipContentInput | ReplaceVideoClipSequenceInput | AdjustVideoClipDurationInput | AddSpeechesInput | DeleteSpeechesInput | MoveSpeechesInput | SetCaptionVisibilityInput | SetCaptionStyleInput | SetBgmInput | DeleteBgmInput;
 type SemanticOpName = ImplementedSemanticOpKind;
 /** Audit metadata committed alongside an op's writes. */
 interface TransactAudit {
   kind: SemanticOpName;
   payload: unknown;
   intent?: unknown;
+  actor?: OpActor;
 }
 /**
  * Narrow write surface the `SemanticEditor` drives (ADR 0008 / 0009). It stays
@@ -1058,11 +1717,46 @@ interface SemanticDocumentAdapter extends SnapshotReadable {
 declare class SemanticEditor {
   private readonly doc;
   private readonly validator;
-  private readonly idFactory;
-  constructor(doc: SemanticDocumentAdapter, validator?: SchemaValidator, idFactory?: PartIdFactory);
+  constructor(doc: SemanticDocumentAdapter, validator?: SchemaValidator);
   moveVideoClips(input: MoveVideoClipsInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Reorder main-track clips relative to an anchor clip, moving them as one block.
+   *
+   * The ordinal sibling of `moveVideoClips`: main-track clips are
+   * `sequential`-positioned, so their order is the authoritative fact and absolute
+   * time is derived on read (RFC 02 §4/§7). A caller that already knows "put these
+   * after that one" should say so, instead of computing a timeline offset that this
+   * editor would only have to resolve back into an index.
+   *
+   * `on_anchored` decides the speech treatment and is required. Note the asymmetry
+   * in cost: `follow` writes nothing to the speeches (their `{ anchorPartId,
+   * offsetMs }` facts stay valid and the derived absolute time moves with the host),
+   * while `keep_absolute` runs the extra re-parent pass that preserves each
+   * speech's absolute landing. `moveVideoClips` is permanently `keep_absolute`,
+   * matching the FE timeline it serves.
+   */
+  moveVideoClipsByAnchor(input: MoveVideoClipsByAnchorInput, options?: CommitOptions): Promise<void>;
   deleteVideoClips(input: DeleteVideoClipsInput, options?: CommitOptions): Promise<void>;
   addVideoClips(input: AddVideoClipsInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Swap a contiguous run of main-track clips for a new run, in one transaction.
+   *
+   * Composite by necessity, not convenience: with `on_anchored: 'remap'` each
+   * surviving speech is re-anchored to the new clip in the **same position of the
+   * sequence** (old[i] → new[i]), which needs both id sets live at once. Splitting
+   * it into `deleteVideoClips` + `addVideoClips` would leave the caller holding the
+   * anchor re-wiring — the cascade-in-the-caller mistake ADR 0009 retires.
+   *
+   * Positional pairing, not by count: when there are fewer new clips than old, the
+   * unmatched old clips have no counterpart, so their anchored subtrees are deleted
+   * (there is nothing to anchor to). When there are more new clips than old, the
+   * extra ones simply arrive with no children.
+   *
+   * The new clips are inserted where the run started, so surrounding order is
+   * preserved. Every position is derived on read (RFC 02 §7) — this writes only the
+   * facts: track order, the trim windows, and the surviving anchors.
+   */
+  replaceVideoClipSequence(input: ReplaceVideoClipSequenceInput, options?: CommitOptions): Promise<void>;
   adjustVideoClipVolume(input: AdjustVideoClipVolumeInput, options?: CommitOptions): Promise<void>;
   setVideoClipSpeedShift(input: SetVideoClipSpeedShiftInput, options?: CommitOptions): Promise<void>;
   adjustSpeechVolume(input: AdjustSpeechVolumeInput, options?: CommitOptions): Promise<void>;
@@ -1105,12 +1799,23 @@ declare class SemanticEditor {
   /**
    * Set the document BGM. The media's stable result arrives materialized.
    *
-   * KNOWN GAP (non-blocking): when the BGM comes from the public library, the
-   * Director must also register project-level stock media ownership. That is a
-   * separate "register-only, no draft write" side effect Director does not yet
-   * expose; until it does, a public-library BGM set here will not auto-appear in
-   * the project media library. The document edit itself is complete and correct.
-   * See `docs/projects/medeo-integration/results/phase-4-op-side-effect-classification.md`.
+   * KNOWN GAP (non-blocking, FE callers only): a public-library BGM also needs
+   * project-level media ownership registered, or it plays but never appears in
+   * the project's media library. This editor deliberately does not do it — the
+   * document edit is complete and correct, and ownership is a side effect owned
+   * by whoever holds the authoritative media data (memota), not by a CRDT write.
+   *
+   * Who is affected, as of 2026-08-13: the agent harness registers it on BOTH
+   * its legacy and mengine paths (shared `resolveMutation` calls memota
+   * `attachMedia` directly), and FE's legacy REST path gets it from Director.
+   * Only FE's mengine path is missing it. FE cannot call memota directly:
+   * `attachMedia` is exposed on memota's internal contract only, so the fix is a
+   * Director proxy route — NOT a new Director business endpoint, since Director
+   * stopped owning media ownership entirely (`a2951355`, 2026-08-05).
+   *
+   * Tracked as a Phase 7 gate (it must land before "new documents default to
+   * mengine" makes public-library BGM a routine operation). See
+   * `docs/projects/medeo-integration/results/phase-6-m4-legacy-refresh-isolation.md`.
    */
   setBgm(input: SetBgmInput, options?: CommitOptions): Promise<void>;
   /** Remove the document BGM; clears the bgm lane and removes the part. */
@@ -1183,57 +1888,6 @@ declare class MirrorVideoDocumentAdapter implements SemanticDocumentAdapter {
 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;
-/** 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
-/**
- * A `TransactAudit` widened with the ordered ids minted during that transact.
- * `generated_ids` is empty when the op never called the id factory.
- */
-interface JournalEntry extends TransactAudit {
-  /** Ids produced by the adapter's id factory during this transact, in mint order. */
-  generated_ids: string[];
-}
-interface PlainMemoryAdapterOptions {
-  /** Underlying id mint; wrapped so each call inside a transact is journaled. */
-  idFactory?: PartIdFactory;
-}
-/**
- * Pure in-memory `SemanticDocumentAdapter` — no Loro/WASM. Holds a
- * `VideoDocumentDraft` object and applies each `transact` via immer `produce`,
- * journaling every audit that actually mutated state (plus any ids minted
- * during that transact).
- *
- * Known benign difference vs `MirrorVideoDocumentAdapter`: the editor's
- * `setPart` assigns a fresh part object on every call, so a same-value rewrite
- * produces a new immer state and IS journaled here, while the mirror's deep
- * diff emits no commit. Terminal `snapshot()` stays equal; replay is idempotent.
- */
-declare class PlainMemoryAdapter implements SemanticDocumentAdapter {
-  private state;
-  private readonly _journal;
-  private readonly baseIdFactory;
-  /** Non-null only while a `transact` edit callback is running. */
-  private pendingIds;
-  /**
-   * Recording wrapper around the underlying factory. Callers (sandbox editor)
-   * use this so every minted id is appended to the current transact's list.
-   */
-  readonly idFactory: PartIdFactory;
-  constructor(document: VideoDocument, options?: PlainMemoryAdapterOptions);
-  get journal(): readonly JournalEntry[];
-  hasContent(): boolean;
-  snapshot(): VideoDocument;
-  /**
-   * Apply one op via immer. A throw in `edit` discards the draft (state and
-   * journal unchanged). When `produce` returns the same reference, there was
-   * no structural change — skip journal, matching mirror "no change, no commit".
-   */
-  transact(edit: (draft: VideoDocumentDraft) => void, audit: TransactAudit): void;
-}
-/** Build a `PlainMemoryAdapter` seeded with `document`. */
-declare function createPlainMemoryAdapter(document: VideoDocument, options?: PlainMemoryAdapterOptions): PlainMemoryAdapter;
 //#endregion
 //#region src/document/mirror-read.d.ts
 /**
@@ -1418,4 +2072,4 @@ declare const videoDocumentSchema: z.ZodObject<{
   }, z.core.$loose>]>>>;
 }, z.core.$loose>;
 //#endregion
-export { VideoClipPart as $, TrackItemDraft as A, derivePositionFromAbs as B, isImplementedSemanticOpKind as C, PartIdFactory as D, ValidationError as E, assertValidVideoDocument as F, PartKind as G, toVideoDocument as H, validateVideoDocument as I, Timeline as J, PartUnion as K, DerivedItemPosition as L, VideoDocumentMirrorSchema as M, videoDocumentMirrorSchema as N, generatePartId as O, VideoDocumentValidationError as P, VIDEO_DOCUMENT_SCHEMA_VERSION as Q, SpeechHostMap as R, SemanticOpKind as S, SnapshotReadable as T, BgmPart as U, fromVideoDocument as V, CaptionPart as W, TrackItem as X, Track as Y, TrackItemTimePosition as Z, SemanticOpName as _, PlainMemoryAdapter as a, effectiveVideoClipDurationMs as at, ImplementedSemanticOpKind as b, MirrorVideoDocumentAdapter as c, CaptionPart$1 as ct, createMirrorVideoDocumentAdapter as d, SpeedShift as dt, VideoDocument as et, writeVideoDocumentToDraft as f, Timeline$1 as ft, SemanticOpInput as g, SemanticEditor as h, JournalEntry as i, VideoDraft as it, VideoDocumentDraft as j, TrackDraft as k, MirrorVideoDocumentOptions as l, CaptionStyle as lt, SemanticDocumentAdapter as m, TrackItem$1 as mt, videoDocumentSchema as n, VideoDocumentValidationIssue as nt, PlainMemoryAdapterOptions as o, speedOf as ot, CommitOptions as p, Track$1 as pt, SpeechPart as q, readVideoDocumentFromDraft as r, VideoDocumentValidationIssueCode as rt, createPlainMemoryAdapter as s, Attachment as st, partUnionSchema as t, VideoDocumentSchemaVersion as tt, createMirrorVideoDocument as u, PartAggregation as ut, TransactAudit as v, SchemaValidator as w, PlannedSemanticOpKind as x, IMPLEMENTED_SEMANTIC_OP_KINDS as y, buildSpeechHostMap as z };
+export { VideoDocumentValidationIssue as $, assertValidVideoDocument as A, BgmPart as B, index_d_exports as C, VideoDocumentMirrorSchema as D, VideoDocumentDraft as E, SpeechHostMap as F, Timeline as G, PartKind as H, buildSpeechHostMap as I, TrackItemTimePosition as J, Track as K, derivePositionFromAbs as L, InitialDocumentFacts as M, buildInitialVideoDocument as N, videoDocumentMirrorSchema as O, DerivedItemPosition as P, VideoDocumentSchemaVersion as Q, fromVideoDocument as R, ValidationError as S, TrackItemDraft as T, PartUnion as U, CaptionPart as V, SpeechPart as W, VideoClipPart as X, VIDEO_DOCUMENT_SCHEMA_VERSION as Y, VideoDocument as Z, PlannedSemanticOpKind as _, MirrorVideoDocumentOptions as a, CaptionStyle as at, SchemaValidator as b, CommitOptions as c, Timeline$1 as ct, SemanticEditor as d, VideoDocumentValidationIssueCode as et, SemanticOpInput as f, ImplementedSemanticOpKind as g, IMPLEMENTED_SEMANTIC_OP_KINDS as h, MirrorVideoDocumentAdapter as i, CaptionPart$1 as it, validateVideoDocument as j, VideoDocumentValidationError as k, OpActor as l, Track$1 as lt, TransactAudit as m, videoDocumentSchema as n, VideoDraftPartUnion as nt, createMirrorVideoDocument as o, PartAggregation as ot, SemanticOpName as p, TrackItem as q, readVideoDocumentFromDraft as r, Attachment as rt, createMirrorVideoDocumentAdapter as s, SpeedShift as st, partUnionSchema as t, VideoDraft as tt, SemanticDocumentAdapter as u, TrackItem$1 as ut, SemanticOpKind as v, TrackDraft as w, SnapshotReadable as x, isImplementedSemanticOpKind as y, toVideoDocument as z };