@mengine/medeo-client 2.0.1 → 2.1.1-dsl.0

package/dist/index.d.ts

@@ -1,1122 +1,5 @@
-import { $ as VideoDraft, A as assertValidVideoDocument, B as CaptionPart, C as index_d_exports, D as VideoDocumentMirrorSchema, E as VideoDocumentDraft, F as buildSpeechHostMap, G as Timeline, H as PartKind, I as derivePositionFromAbs, J as TrackItemTimePosition, K as Track, L as fromVideoDocument, M as buildInitialVideoDocument, N as DerivedItemPosition, O as videoDocumentMirrorSchema, P as SpeechHostMap, Q as VideoDocumentValidationIssueCode, R as toVideoDocument, S as ValidationError, T as TrackItemDraft, U as PartUnion, V as DEFAULT_UNIT_TIME_MS, W as SpeechPart, X as VideoDocument, Y as VideoClipPart, Z as VideoDocumentValidationIssue, _ as PlannedSemanticOpKind, a as MirrorVideoDocumentOptions, at as PartAggregation, b as SchemaValidator, c as CommitOptions, ct as Track$1, d as SemanticEditor, et as VideoDraftContent, f as SemanticOpInput, g as ImplementedSemanticOpKind, h as IMPLEMENTED_SEMANTIC_OP_KINDS, i as MirrorVideoDocumentAdapter, it as CaptionStyle, j as validateVideoDocument, k as VideoDocumentValidationError, l as OpActor, lt as TrackItem$1, m as TransactAudit, n as videoDocumentSchema, nt as Attachment, o as createMirrorVideoDocument, ot as SpeedShift, p as SemanticOpName, q as TrackItem, r as readVideoDocumentFromDraft, rt as CaptionPart$1, s as createMirrorVideoDocumentAdapter, st as Timeline$1, t as partUnionSchema, tt as VideoDraftPartUnion, u as SemanticDocumentAdapter, v as SemanticOpKind, w as TrackDraft, x as SnapshotReadable, y as isImplementedSemanticOpKind, z as BgmPart } from "./index-CnZ9l3rb.js";
-import { LoroDoc, PeerID } from "loro-crdt";
-import { DocState } from "@mengine/sync";
-import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
-
-//#region src/client/base64.d.ts
-declare function bytesToBase64(bytes: Uint8Array): string;
-declare function base64ToBytes(base64: string): Uint8Array;
-//#endregion
-//#region src/client/wire.d.ts
-interface MengineDocumentVersion {
-  update_seq: number;
-  /** base64 `VersionVector.encode` of the server oplog — the sync anchor. */
-  server_vv: string;
-  /** base64 `encodeFrontiers` of the server oplog heads. */
-  frontiers: string;
-}
-interface MengineSnapshotResponse {
-  snapshot: string;
-  version: MengineDocumentVersion;
-}
-/** Business + causal metadata for one update (audit / rollback anchor). */
-interface MengineUpdateMeta {
-  semantic_op: string | null;
-  payload: unknown;
-  intent: string | null;
-  /**
-   * Who authored the op, as recorded in the Loro commit message (see `OpActor`).
-   * Null for writes with no acting user — bootstrap, repair — and for Changes
-   * written before attribution existed. Self-reported by the authoring client;
-   * the server does not verify it against the request identity.
-   */
-  actor: {
-    user_id: string;
-    role: string;
-  } | null;
-  message: string | null;
-  parse_error: boolean;
-  peer: string;
-  counter: number;
-  lamport: number;
-  timestamp: number;
-  frontiers: string;
-}
-/**
- * Response to `GET .../sync?from=<vv b64>`: the ops the caller is missing as one
- * merged Loro update blob (`export({mode:'update', from})`) plus the server's
- * current oplog VV. Loro resolves the causal partial order inside the blob, so
- * there is no per-update envelope; `import` is idempotent, so an already-current
- * caller gets a framing-only blob that applies as a no-op. Mirrors the server's
- * `SyncWireResponse`.
- */
-interface MengineSyncResponse {
-  /** base64 merged Loro update blob (empty string when the caller is current). */
-  update: string;
-  server_vv: string;
-}
-interface MengineAuditEntry extends MengineUpdateMeta {
-  update_seq: number;
-}
-interface MengineAuditResponse {
-  entries: MengineAuditEntry[];
-}
-interface MenginePushUpdateResponse {
-  kind: 'ack' | 'duplicate';
-  update_seq: number | null;
-  version: MengineDocumentVersion;
-}
-interface MengineRejectedResponse {
-  kind: 'rejected';
-  code: string;
-  message: string;
-  server_version: MengineDocumentVersion;
-}
-interface MengineSseUpdateEvent {
-  update_seq: number;
-  updates: string[];
-  meta: MengineUpdateMeta;
-  version: MengineDocumentVersion;
-}
-type MenginePushResponse = MenginePushUpdateResponse | MengineRejectedResponse;
-//#endregion
-//#region src/client/http-client.d.ts
-interface MengineHttpClientOptions {
-  docId: string;
-  httpOrigin: string;
-  /**
-   * Bearer token for the `authorization` header. Accepts a static string or a
-   * getter evaluated per request — prefer the getter in the browser editor so
-   * each request carries the current login JWT (same credential the REST link
-   * sends), rather than a value snapshotted before login hydrates or gone stale
-   * after a refresh. A literal `user_dev` is the local dev/relay-test stub.
-   */
-  authToken?: string | (() => string | undefined);
-  /**
-   * The end-user id sent as the `medeo-user-id` header. Accepts either a static
-   * string or a getter evaluated per request. Prefer the getter when the login
-   * state hydrates asynchronously (e.g. the browser editor): the client is
-   * constructed eagerly but each request reads the latest id, so an id that is
-   * not yet ready at construction time is picked up once it settles — no need to
-   * defer client/session creation until auth is ready.
-   */
-  userId?: string | (() => string | undefined);
-  fetchImpl?: typeof fetch;
-}
-declare class MengineHttpRequestError extends Error {
-  readonly status: number;
-  readonly payload: unknown;
-  constructor(status: number, payload: unknown);
-}
-/**
- * A push the server refused on its merits (`kind: 'rejected'`), as opposed to a
- * transport failure. Carries the server's machine `code` so callers can branch on
- * *why* rather than on an HTTP status:
- *
- * - `missing_dependency` (server answers 409) — retryable: the update depends on
- *   ops the server log lacks, so catching up and re-exporting resolves it.
- * - `corrupt_update` (server answers 422) — never valid, retrying cannot help.
- *
- * Distinct from {@link MengineHttpRequestError} (transport/status-level failure)
- * and from a raw `fetch` rejection (network down): the three are separate classes
- * so a caller can tell "the server said no" from "the server never answered".
- */
-declare class MenginePushRejectedError extends Error {
-  readonly code: string;
-  readonly serverMessage: string;
-  readonly serverVersion: MengineDocumentVersion | undefined;
-  readonly status: number | undefined;
-  constructor(code: string, serverMessage: string, serverVersion: MengineDocumentVersion | undefined, status: number | undefined);
-}
-declare class MengineHttpClient {
-  private readonly options;
-  private readonly fetchImpl;
-  constructor(options: MengineHttpClientOptions);
-  fetchSnapshot(): Promise<MengineSnapshotResponse>;
-  /**
-   * Loro VV-diff pull: send the caller's oplog `VersionVector.encode` as `from`
-   * (omit for a full pull) and receive exactly the updates it is missing plus
-   * the server's current VV. Replaces the old integer `after_update_id` cursor.
-   */
-  sync(fromVV?: Uint8Array): Promise<MengineSyncResponse>;
-  /** Audit trail: extracted metadata per accepted update, in log order. */
-  audit(): Promise<MengineAuditResponse>;
-  /**
-   * Append one Loro update to the server log.
-   *
-   * Resolves for both accepted outcomes and hands the verdict back verbatim —
-   * `ack` (appended, `update_seq` allocated) and `duplicate` (already known, no
-   * row appended). A `duplicate` is NOT an error, but it is also not an ack: it
-   * means the bytes contributed nothing, so a caller waiting for its own write to
-   * land must be able to tell them apart. Hence the verdict is returned rather
-   * than collapsed into `void`.
-   *
-   * Rejections raise {@link MenginePushRejectedError} carrying the server's
-   * machine `code`. The server answers them with 409/422, so the failure arrives
-   * as a non-ok response; this method re-reads the parsed body to recover `code` /
-   * `server_version` instead of leaving the caller a bare status. Transport-level
-   * failures stay {@link MengineHttpRequestError}, and a dead network keeps
-   * surfacing as the underlying `fetch` rejection.
-   */
-  pushUpdate(update: Uint8Array): Promise<MenginePushUpdateResponse>;
-  eventsUrl(): string;
-  headers(): Headers;
-  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
-  private requestJson;
-  private endpoint;
-}
-//#endregion
-//#region src/client/sse.d.ts
-interface MengineEventStreamOptions {
-  client: MengineHttpClient;
-  signal?: AbortSignal;
-  /** Fired once the stream response is established (HTTP ok, body readable). */
-  onOpen?(): void;
-  onUpdate(event: MengineSseUpdateEvent): void;
-  /** A committed update omitted from live transport; fetch the missing operations by VV. */
-  onResync?(): void;
-}
-declare function readMengineEventStream(options: MengineEventStreamOptions): Promise<void>;
-//#endregion
-//#region src/editor/id-gen.d.ts
-/**
- * Part-id generation, aligned with the online ecosystem.
- *
- * 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.
- *
- * 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;
-//#endregion
-//#region src/editor/snapshot-utils.d.ts
-/** Main-track item identity read from a raw snapshot (only `part_id` is needed). */
-interface MainTrackItemRef {
-  part_id: string | undefined;
-}
-declare function isMap(value: unknown): value is Map<unknown, unknown>;
-declare function snapshotToPlain(value: unknown): unknown;
-declare function getAt(snapshot: unknown, ...keys: string[]): unknown;
-declare function readMainTrackItems(snapshot: unknown): MainTrackItemRef[];
-/**
- * The effective timeline duration of a part read from a raw snapshot. No part
- * stores a derived `duration_ms` in authoritative state (reference/17 §5): a
- * video clip's length is its trim window `play_out - play_in` over the speed
- * multiplier; a speech's is its intrinsic `media_duration_ms`; a caption's is its
- * `initial_duration_ms`. Falls back to `fallback` when no source value is
- * resolvable (e.g. an unknown/raw part).
- */
-declare function readPartDurationMs(snapshot: unknown, partId: string, fallback?: number): number;
-declare function readPart(snapshot: unknown, partId: string): (Record<string, unknown> & {
-  part_kind?: PartKind;
-}) | null;
-//#endregion
-//#region src/manual-sync/types.d.ts
-/**
- * Opaque marker for "the document state I last looked at".
- *
- * Deliberately not a number. Under mengine there is no monotonic document
- * version to compare: `meta.version` is stamped once at legacy ingest and then
- * frozen, and the server's `update_seq` counts every writer's pushes, so neither
- * can answer "has this document changed since I last read it". The answer comes
- * from comparing version vectors.
- *
- * Opaque means: no arithmetic, no ordering, no comparison other than handing it
- * back to {@link ManualSyncDoc.hasChangedSince}. Two version vectors are only
- * partially ordered — concurrent ones are neither greater nor equal, and Loro's
- * own `compare` returns `undefined` for them — so `mark1 > mark2` or sorting a
- * list of marks has no meaning to get wrong.
- *
- * Persisting one IS supported, via {@link encodeDocVersionMark} /
- * {@link decodeDocVersionMark}. Storing an opaque blob and reading it back does
- * not order or compute anything, and callers that compare across turns (rather
- * than within one process) need it: the legacy integer version this replaces was
- * itself persisted between agent turns.
- */
-interface DocVersionMark {
-  readonly __brand: 'mengine-doc-version-mark';
-  /** Encoded oplog `VersionVector` at the moment the mark was taken. */
-  readonly encoded: Uint8Array;
-}
-/** Why a `pull()` did not complete. Mirrors the push failure taxonomy. */
-type PullFailureReason = 'failed';
-/**
- * Result of a `pull()`.
- *
- * `ok: false` is a first-class outcome, not an exception: per the M2/A ruling a
- * failed pull must not hard-fail the tool call, matching legacy's tolerance for
- * read failures (`getDraftVersion` swallows to null, `DraftVersionDetector`
- * catches and skips). The caller decides whether to proceed on a possibly-stale
- * document, so the degradation has to be visible in the return value.
- */
-type PullResult = {
-  ok: true; /** True when the pull actually advanced the local document. */
-  changed: boolean;
-} | {
-  ok: false;
-  reason: PullFailureReason;
-  error: Error;
-};
-/**
- * What the server did with a `push()`.
- *
- * The first four mirror the server's verdict taxonomy (see `PushOutcomeKind`);
- * `nothing_to_push` is a local short-circuit — no request was made because the
- * document holds no ops the server lacks.
- */
-type PushResultKind = 'ack' | 'duplicate' | 'rejected' | 'failed' | 'nothing_to_push';
-/**
- * Result of a `push()`.
- *
- * `collaborated` is the load-bearing field. The legacy Drizzle path fails loudly
- * on concurrent writes (`Optimistic lock failed`); mengine merges silently by
- * design (M0/S2 accepted CRDT merge semantics). Migrating without surfacing this
- * would replace a path that reports conflicts with one that hides them, so every
- * successful push says whether the server held ops the local document did not.
- *
- * Its meaning is "the server has ops you don't", NOT "there was a conflict" — the
- * same user's other browser tab counts. It is therefore suitable for driving a
- * re-pull and for informing the caller, but not for raising an alarm on its own.
- */
-interface PushResult {
-  kind: PushResultKind;
-  /** Server document sequence observed after a successful `ack` or `duplicate`. */
-  mengineUpdateSeq?: number | undefined;
-  /** @deprecated Ack-only sequence retained until consumers adopt `mengineUpdateSeq`. */
-  updateSeq?: number | undefined;
-  /** Whether the server held ops the local document lacked. See above. */
-  collaborated: boolean;
-  /** Server machine code for `rejected` (`missing_dependency` / `corrupt_update`). */
-  code?: string | undefined;
-  /** Underlying error for `rejected` / `failed`. */
-  error?: Error | undefined;
-}
-//#endregion
-//#region src/manual-sync/doc-version-mark.d.ts
-/**
- * Encode a {@link DocVersionMark} for storage or transport.
- *
- * The mark stays opaque across the round trip — the string is not a version
- * number and must not be compared, ordered, or parsed. Its only use is
- * {@link decodeDocVersionMark} followed by `hasChangedSince`.
- *
- * Callers that persist this should know the encoded length grows with the number
- * of peers that have ever written to the document (one counter each), and the FE
- * mints a fresh peer per page load. Still small in practice (a few hundred bytes
- * for dozens of peers), but it grows with document age rather than size; version
- * vector compaction is deferred to a later phase.
- */
-declare function encodeDocVersionMark(mark: DocVersionMark): string;
-/**
- * Rebuild a mark from {@link encodeDocVersionMark}'s output.
- *
- * Returns `undefined` for input this did not produce (a legacy integer version,
- * a truncated value, an empty string). That is the honest answer — "I cannot
- * establish what you last saw" — and callers should treat it as "no baseline"
- * rather than as "unchanged". Decoding does not validate the bytes as a version
- * vector; `hasChangedSince` reports "changed" for an undecodable mark, which is
- * the conservative direction.
- */
-declare function decodeDocVersionMark(encoded: string): DocVersionMark | undefined;
-//#endregion
-//#region src/manual-sync/manual-sync-doc.d.ts
-interface ManualSyncDocOptions {
-  client: MengineHttpClient;
-  /**
-   * Peer id for this writer. Every writer needs a distinct one: two writers
-   * sharing a peer and branching from the same base emit identical
-   * `(peer, counter)` pairs, the server classifies the second as `duplicate` and
-   * drops it, and the write is silently lost. Callers mint a random one (see the
-   * harness's `mintHarnessPeerId`).
-   */
-  peerId?: PeerID;
-}
-/**
- * Agent-facing document with explicit `pull()` / `push()` over one Loro
- * document, with no background sync (ADR 0015 D1–D4).
- *
- * It deliberately does NOT reuse `MengineDocSession`'s stack. That stack —
- * SSE + local `DocStorage` + `ClientServerSynchronizer` + `DocManager` — is
- * correct for a browser editor and actively wrong here:
- *
- * - Its retry backoff lands *outside* the tool-call lifetime, so a write can
- *   settle seconds after the tool already told the LLM what happened.
- * - It has no durable local queue in the harness, so pending pushes die with the
- *   process — that is lost data, reported as success.
- * - Agent semantics require the document to change only at points the agent can
- *   name. If it converged on its own between tool calls, "what state was this
- *   decision based on" would be unanswerable, and a remote change could land
- *   mid-edit.
- *
- * What replaces the whole background job queue is one variable: the **watermark**,
- * the version the server has confirmed. `push()` exports `{mode:'update', from:
- * watermark}` and only advances it on a confirmed verdict, so a failed push is
- * retried implicitly — the next push carries both the failed ops and any new
- * ones, in one blob. No queue, no timer, no retry bookkeeping.
- *
- * Two non-obvious properties of that watermark, both verified against a real
- * server in the ADR 0015 spike:
- *
- * - It can legitimately *lead* the local document (it carries other peers'
- *   counters). Exporting `from` a leading watermark does not error; the blob
- *   correctly contains only the local peer's new ops. So a collaborative merge
- *   does not force a pull before pushing.
- * - Therefore every emptiness/coverage test must be one-directional containment,
- *   never equality. See {@link covers}.
- *
- * Lifecycle: one `LoroDoc` per document, shared across agent loops with a
- * refcount held by the caller's session registry. Rebuilding the doc per tool
- * call would mint a new peer each time and permanently inflate the document's
- * version vector for every future reader.
- *
- * Not thread-safe by design and it does not need to be: harness tool calls run
- * serially (`execToolCalls` is a `for` + `await`).
- */
-declare class ManualSyncDoc {
-  private readonly client;
-  private readonly doc;
-  private readonly adapter;
-  readonly editor: SemanticEditor;
-  /**
-   * The version the server is known to hold. Starts empty (nothing confirmed)
-   * and only ever moves forward on a verdict that proves the server took our ops.
-   */
-  private watermark;
-  private constructor();
-  /**
-   * Open an existing server document.
-   *
-   * Fetches the snapshot up front rather than starting empty and converging: the
-   * agent's first act is to read the document, so there is no useful state before
-   * the snapshot lands. This also fails fast and loudly on a document that does
-   * not exist or whose first snapshot is incomplete or invalid.
-   */
-  static open(options: ManualSyncDocOptions): Promise<ManualSyncDoc>;
-  /** Current document read model (authoritative shape). */
-  snapshot(): VideoDocument;
-  /**
-   * The Loro peer this document writes as.
-   *
-   * Exposed because the peer is an externally-meaningful fact, not an internal
-   * detail: it is the identity every op this document emits is attributed to, and
-   * callers mint it under rules of their own (the harness reserves a range so a
-   * peer id alone says "Agent wrote this"). Being able to read it back means those
-   * rules can be verified against the live document rather than against whatever
-   * was passed to the constructor.
-   */
-  editorPeerId(): PeerID;
-  /** Current content projected into the compatible track and part read shape. */
-  content(): VideoDraftContent;
-  /**
-   * Mark the document state the caller has just observed, for a later
-   * {@link hasChangedSince}.
-   *
-   * This pair replaces the legacy integer-version comparison that
-   * `DraftVersionDetector` used to tell the LLM "the draft was modified
-   * externally, reload before editing". Comparing Loro version vectors covers
-   * all collaborative edits without a business revision field in the document.
-   *
-   * Same capability, not a stronger one: like the legacy detector, this only
-   * reports what changed between two moments the caller chose to sample.
-   */
-  versionMark(): DocVersionMark;
-  /**
-   * Has the document moved since `mark` was taken?
-   *
-   * Reports any advance, whoever caused it — including this document's own edits.
-   * The caller decides what is interesting: a detector sampling once per turn is
-   * asking "did anything happen", and its own edits legitimately count.
-   */
-  hasChangedSince(mark: DocVersionMark): boolean;
-  /**
-   * Fetch and merge everything the server has that this document lacks.
-   *
-   * Must run *before* the editor on each tool call. `SemanticEditor` validates
-   * against the local document, so editing a stale one validates against a world
-   * that no longer exists: the ADR 0015 spike confirmed that without pull-first
-   * an edit to a clip another writer had already deleted passes validation and is
-   * accepted by the server. Pulling afterwards cannot undo that.
-   *
-   * A failure is returned, not thrown — a transient network blip must not make
-   * the tool unusable (M2/A ruling; legacy tolerates read failures the same way).
-   * The caller proceeds on a possibly-stale document knowingly.
-   */
-  pull(): Promise<PullResult>;
-  /**
-   * Push every local op the server has not confirmed, and report the verdict.
-   *
-   * The return value is the durability answer a tool needs before claiming
-   * success: only `ack` / `duplicate` mean the server holds the ops. This is why
-   * this class exists rather than an ack-waiter — with a direct call, "did it
-   * land" is simply the result.
-   *
-   * `duplicate` counts as durable: the bytes added nothing *because* the server
-   * already had them.
-   */
-  push(): Promise<PushResult>;
-  /** Decode a wire `server_vv`, tolerating absence/corruption (never throws). */
-  private serverVVFrom;
-}
-//#endregion
-//#region src/storage/medeo-http-doc-storage.d.ts
-interface MedeoHttpDocStorageOptions {
-  docId: string;
-  client: MengineHttpClient;
-  sseReconnectDelayMs?: number;
-  readonlyMode?: boolean;
-}
-/**
- * What the server did with one pushed update, as observed by this storage.
- *
- * `ack` / `duplicate` mirror the server verdict. `rejected` is a refusal on the
- * merits (carrying the machine `code`: `missing_dependency` is retryable after
- * catch-up, `corrupt_update` never is). `failed` is everything else — transport
- * error, non-2xx status, dead network — i.e. the server's answer is unknown.
- *
- * The four are kept distinct because the recovery differs per case, and because
- * the whole point of M1 is that a caller can tell "written" from "not written".
- */
-type PushOutcomeKind = 'ack' | 'duplicate' | 'rejected' | 'failed';
-interface PushOutcome {
-  kind: PushOutcomeKind;
-  /** Server-allocated sequence number; only present for `ack`. */
-  updateSeq?: number | undefined;
-  /**
-   * The server oplog version vector *after* handling this push (`ack` and
-   * `duplicate` both carry it; encoded `VersionVector`).
-   *
-   * This is what an "is my write durable" waiter keys on, and it is deliberately
-   * the ONLY correlation handle here. An earlier revision also carried the pushed
-   * bytes so a waiter could match its own update; that was removed because byte
-   * identity is not a reliable match — the same ops can reach the server either
-   * as the individual blob the push job carried or as a merged
-   * `export({from: serverVV})` blob produced by the synchronizer's sync path.
-   * Version coverage is reliable, and it makes `duplicate` satisfy a waiter
-   * correctly: the bytes appended nothing precisely because the server already
-   * held them. Offering both invited the wrong one.
-   */
-  serverVV?: Uint8Array | undefined;
-  /** Server machine code for `rejected` (e.g. `missing_dependency`). */
-  code?: string | undefined;
-  /** The underlying error for `rejected` / `failed`. */
-  error?: Error | undefined;
-}
-/**
- * Adapts the mengine-server HTTP/SSE protocol to the engine `DocStorage`
- * contract so `ClientServerSynchronizer` can treat it as a remote peer.
- *
- * Deliberately thin (mirrors the socket `DocStorage` in the playground): it
- * forwards live SSE updates and exposes a version-vector diff, and keeps NO
- * sync state of its own.
- *
- * - `getDocDiff(docId, knownVersion)` pulls the server-computed VV-diff via
- *   `GET /sync?from=<vv>` — the synchronizer passes the real `doc.version()`, so
- *   the response carries exactly the ops the doc is missing. `getDoc` (full
- *   `/snapshot`) stays for cold start, when the caller holds no version yet.
- * - `pushDocUpdate` forwards a Loro update; the server appends it.
- * - `subscribeDocUpdate` registers a callback for live SSE updates. It does no
- *   catch-up and keeps no cursor: after an SSE drop the connection reports a
- *   status change, and the synchronizer re-runs its cycle to catch up via
- *   `getDocDiff(doc.version())`. `LoroDoc.import` is idempotent (OpId/VV), so
- *   re-forwarded or echoed updates are harmless.
- *
- * It is bound to a single `docId` because `MengineHttpClient` is per-document.
- */
-declare class MedeoHttpDocStorage implements DocStorage {
-  private readonly options;
-  readonly connection: Connection;
-  private readonly client;
-  private readonly docId;
-  private readonly events;
-  constructor(options: MedeoHttpDocStorageOptions);
-  get isReadonly(): boolean;
-  getDoc(docId: string): Promise<DocSnapshotRecord | null>;
-  getDocDiff(docId: string, knownVersion?: Uint8Array): Promise<DocDiff | null>;
-  /**
-   * Forward one update to the server, returning what the server says it now holds.
-   *
-   * The returned `server_vv` is the server's own statement about itself, computed
-   * inside the write transaction. A caller tracking "what the remote has" can
-   * adopt it directly, which is strictly better than inferring that bound from
-   * the pushed blob: it also covers ops other peers wrote, so those stop being
-   * re-sent on every later push. `ack` and `duplicate` both carry it.
-   *
-   * The verdict itself stays on {@link subscribePushOutcome}, which reports
-   * failures too — a return value cannot. Previously the verdict was read and
-   * dropped, so a `duplicate` (bytes contributed nothing) was indistinguishable
-   * from a successful write.
-   *
-   * The error is still rethrown after being published: the synchronizer treats a
-   * throw as "retry this cycle", and swallowing it here would strand the update.
-   * Publishing is therefore additive observability, not error handling.
-   */
-  pushDocUpdate(update: DocUpdate, _origin: unknown): Promise<DocPushReceipt>;
-  /**
-   * Observe the server's verdict for every pushed update, including failures.
-   *
-   * This is the loud channel the `void`-returning `DocStorage.pushDocUpdate`
-   * cannot express. Consumers that need "did my write land" (the agent's
-   * tool-level ack wait) subscribe here.
-   */
-  subscribePushOutcome(callback: (outcome: PushOutcome) => void): () => void;
-  /** Observe live hints that require VV catch-up without replacing the SSE connection. */
-  subscribeResync(callback: () => void): () => void;
-  /** Authoritative HTTP reads and accepted pushes, never inferred from SSE bytes. */
-  subscribeServerVersion(callback: (version: Uint8Array) => void): () => void;
-  private reportServerVersion;
-  deleteDoc(_docId: string): Promise<void>;
-  subscribeDocUpdate(callback: (update: DocUpdate, origin: unknown) => void): () => void;
-  private assertDocId;
-  private emitUpdate;
-}
-//#endregion
-//#region src/session/document-undo-manager.d.ts
-/** Availability for this document's current editing session, not server revisions. */
-interface MengineUndoState {
-  readonly canUndo: boolean;
-  readonly canRedo: boolean;
-}
-//#endregion
-//#region src/session/types.d.ts
-/**
- * Local storage contract the runtime depends on. Aliased to the engine
- * `DocStorage` so browsers can inject `IndexedDBDocStorage` and Node can inject
- * `MemoryDocStorage` without medeo-client taking a hard dependency on either
- * concrete implementation.
- */
-type DocStorageLike = DocStorage;
-//#endregion
-//#region src/session/mengine-doc-session.d.ts
-interface MengineDocSessionUpdateEvent {
-  source: 'remote' | 'local';
-  snapshot: VideoDocument;
-}
-/**
- * Raised by {@link MengineDocSession.waitForServerAck} when the local edits it
- * was asked to confirm were not acknowledged as durable.
- *
- * Named `...AckFailed`, not `...AckTimeout`: two of the three `reason` values are
- * not timeouts, and the earlier name made callers reach for a retry-after-delay
- * that is wrong for `rejected`.
- *
- * The distinction the caller needs is "was it written": if this throws, treat the
- * write as NOT durable. `reason` says which failure it was, and `code` carries the
- * server's machine code when the push was rejected on its merits:
- *
- * - `timeout` — no verdict within the deadline. Ambiguous by nature: the push may
- *   still land later. The caller should surface it as unconfirmed, not as "failed".
- * - `rejected` — the server refused. `missing_dependency` is retryable after
- *   catch-up; `corrupt_update` never is.
- * - `failed` — transport/network failure; the server's answer is unknown.
- */
-declare class MengineAckFailedError extends Error {
-  readonly reason: 'timeout' | 'rejected' | 'failed';
-  readonly code: string | undefined;
-  readonly cause: Error | undefined;
-  constructor(reason: 'timeout' | 'rejected' | 'failed', code: string | undefined, cause: Error | undefined, message: string);
-}
-interface WaitForServerAckOptions {
-  /** Deadline in ms. Rejects with reason `timeout` when it elapses. */
-  timeoutMs?: number;
-}
-/** Document-level confirmation is independent of local operation completion. */
-interface MengineDocSyncState {
-  /** Remote-only imports do not create a new local confirmation obligation. */
-  readonly confirmation: 'unknown' | 'pending' | 'confirmed';
-  /** Transport/activity phase. Idle does not imply confirmation; failure details
-   * remain available through push outcomes and confirmation wait errors. */
-  readonly phase: 'connecting' | 'idle' | 'syncing' | 'offline' | 'failed';
-}
-interface MengineDocSessionOptions {
-  docId: string;
-  client: MengineHttpClient;
-  peerId?: PeerID;
-  /**
-   * Local storage peer. Defaults to in-memory so the session works in Node.
-   * Browsers should pass an `IndexedDBDocStorage` for refresh/cross-tab support.
-   */
-  localStorage?: DocStorageLike;
-  sseReconnectDelayMs?: number;
-}
-/**
- * A live editing session for one Medeo document — the single entry point clients
- * (FE draft driver, Agent, embeds) use to open, edit, and observe a document.
- *
- * SemanticEditor writes through MirrorVideoDocumentAdapter directly, while
- * DocumentUndoManager observes the same LoroDoc independently. Both mutation
- * paths use the session's DocumentMutationGuard, closed before teardown.
- *
- * `DocManager` owns the `LoroDoc`: local edits committed on the adapter are
- * picked up via `subscribeLocalUpdates`, saved to local storage, then pushed to
- * the server by the synchronizer. Remote SSE updates flow server → synchronizer
- * → local storage → manager → `LoroDoc`. A single `LoroDoc.subscribe` turns any
- * resulting change into a snapshot event, so callers never track update ids by
- * hand.
- *
- * Replaces the per-consumer hand-written pull/SSE loops that previously lived in
- * the standalone client session and `MengineDraftDriver` with one verified path.
- */
-declare class MengineDocSession {
-  private readonly options;
-  private readonly docId;
-  private readonly local;
-  private readonly server;
-  private readonly synchronizer;
-  private readonly manager;
-  private readonly events;
-  private readonly disposables;
-  private readonly mutationGuard;
-  private adapterValue;
-  private editorValue;
-  private undoManagerValue;
-  private started;
-  private startTask;
-  private destroyed;
-  private lifetime;
-  private hasConnected;
-  private initialVersionValue;
-  private localVersionValue;
-  private pushErrorValue;
-  /**
-   * Latest server oplog version seen on an authoritative HTTP response. Lets `waitForServerAck`
-   * return without waiting when the server is already known to cover the local
-   * doc (e.g. nothing was edited since the last confirmed push).
-   */
-  private serverVVValue;
-  constructor(options: MengineDocSessionOptions);
-  /**
-   * Observe every push verdict, including `duplicate` and failures.
-   *
-   * Exposed so a host can log/meter the four outcomes (rfc/05 §3 asks for
-   * explicit ack/rejected semantics). Most callers want the higher-level
-   * {@link waitForServerAck} instead.
-   */
-  subscribePushOutcome(callback: (outcome: PushOutcome) => void): () => void;
-  /**
-   * Resolve once the server has durably accepted the local commits as of
-   * *now* — the capability an Agent tool needs to answer "did my edit land?"
-   * before reporting success.
-   *
-   * Call it right after the editor ops whose durability matters. It snapshots the
-   * latest local commit's version (or the loaded baseline before any edit) and
-   * resolves when an authoritative server version covers it. Remote-only
-   * imports do not extend this target, matching the displayed confirmation state.
-   *
-   * Version coverage, not byte identity, is the acceptance test — for two reasons:
-   * the ops may reach the server inside a merged blob rather than as the exact
-   * bytes a push job carried, and a `duplicate` verdict then correctly satisfies
-   * the wait (the bytes appended nothing *because* the server already had them).
-   * A `rejected` / `failed` outcome rejects immediately with that reason rather
-   * than burning the whole timeout, since neither will resolve by waiting.
-   *
-   * Returns early when the server is already known to be current, so a caller
-   * with nothing outstanding does not block.
-   *
-   * @throws {MengineAckFailedError} on timeout, rejection, or transport failure.
-   */
-  waitForServerAck(options?: WaitForServerAckOptions): Promise<void>;
-  /**
-   * The editor for local edits. Each op method validates, writes, and commits
-   * itself as one SemanticOp (single commit carrying its audit message), so
-   * callers just call `session.editor.someOp(...)` — there is no separate commit
-   * step. The committed change drives DocManager's local-update push.
-   */
-  get editor(): SemanticEditor;
-  /** Current document snapshot (read model). */
-  snapshot(): VideoDocument;
-  /** Current-session undo/redo availability. Loading and closed sessions report false. */
-  getUndoState(): MengineUndoState;
-  /**
-   * Supplies current availability immediately, then coalesces stack changes in a
-   * microtask. Session teardown publishes empty availability synchronously.
-   */
-  subscribeUndoState(cb: (state: MengineUndoState) => void): () => void;
-  /**
-   * Undo a local edit immediately; server confirmation remains asynchronous.
-   * On a shared LWW field this writes its prior value, potentially overwriting a
-   * later remote edit to that same field. Returns false if no update is produced.
-   */
-  undo(options?: CommitOptions): boolean;
-  /**
-   * Restore the state visible before undo without rerunning external side effects.
-   * Returns false if no update is produced; durable confirmation is separate.
-   */
-  redo(options?: CommitOptions): boolean;
-  /**
-   * Combine existing semantic operations (e.g. trim a clip and adjust its volume)
-   * or repeated commits during one drag gesture into a single undo step. A gesture
-   * that only previews locally and commits once on release needs no group.
-   * Each commit is immediately visible locally and enters sync independently;
-   * a later failure does not roll it back.
-   * Always pair with endUndoGroup in a finally block. Conflicting remote imports
-   * can end/split the group early, and unrelated local edits would join it.
-   * Complete asynchronous asset preparation before opening the group.
-   */
-  beginUndoGroup(): void;
-  /** End a gesture, including one already split by a conflicting remote import. */
-  endUndoGroup(): void;
-  /**
-   * Start the sync stack and connect the document.
-   *
-   * Returns after DocManager loads a local snapshot, or after the first remote
-   * sync when no local snapshot exists. A valid empty document is ready too.
-   * Cached documents can open before SSE connects; subsequent remote changes
-   * surface through `subscribe`.
-   */
-  start(): Promise<VideoDocument>;
-  private open;
-  getSyncState(): MengineDocSyncState;
-  private confirmationTarget;
-  /** Immediately supplies current state; unsubscribe when the host changes docs. */
-  subscribeSyncState(cb: (state: MengineDocSyncState) => void): () => void;
-  private emitSyncState;
-  subscribe(cb: (event: MengineDocSessionUpdateEvent) => void): () => void;
-  onStateChange(cb: (state: DocState) => void): () => void;
-  getState(): DocState;
-  destroy(): void;
-  /** Local absence needs a remote sync; empty business content does not. */
-  private waitForInitialLoad;
-}
-//#endregion
-//#region src/storage/memory-doc-storage.d.ts
-/**
- * Runtime-neutral local `DocStorage` backed by in-process memory.
- *
- * `IndexedDBDocStorage` is the browser-side local storage, but it requires
- * `indexedDB`/`idb`, which is absent in Node (FE/agent tests, unit tests, SSR).
- * The mengine runtime injects this implementation as the local peer in those
- * environments so the same `DocManager` + `ClientServerSynchronizer` wiring
- * works without a browser. It mirrors the merge-on-read and update-sequence
- * behavior of `IndexedDBDocStorage` so sync semantics are identical.
- */
-declare class MemoryDocStorage extends BaseDocStorage {
-  readonly connection: Connection;
-  private readonly entries;
-  constructor(options?: DocStorageOptions);
-  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<DocPushReceipt>;
-  deleteDoc(docId: string): Promise<void>;
-  protected getDocSnapshot(docId: string): Promise<DocSnapshotRecord | null>;
-  protected setDocSnapshot(snapshot: DocSnapshotRecord): Promise<boolean>;
-  protected getDocUpdates(docId: string): Promise<DocUpdateRecord[]>;
-  protected markUpdatesMerged(docId: string, updates: DocUpdateRecord[]): Promise<number>;
-  private entry;
-  private now;
-}
-//#endregion
-//#region src/timeline-core/types.d.ts
-/** Total document duration when there is no real content (matches FE bgm fallback). */
-declare const TIMELINE_SKELETON_DURATION_MS = 20000;
-/**
- * Plain-JSON working shape the timeline-core cascade functions operate on.
- *
- * It is a flat, lane-as-array view of the document — close to agent-harness's
- * `NormalizedDraftRow` and to the legacy `VideoDraft`, deliberately *not* the
- * mirror's keyed-track-map storage shape. The editor converts a
- * `VideoDocumentDraft` into this view, runs the cascade, and writes the result
- * back (see `timeline-core/index.ts`). Keeping the algorithms on a structured
- * shape makes them readable and 1:1 comparable with the canonical reference.
- *
- * All times are integer milliseconds (ADR 0009 §4): callers normalize on the
- * way in and the cascade preserves that.
- */
-interface TimelineDoc {
-  main_track: TimelineItem[];
-  /** speech lane (below main). */
-  speech_track: TimelineItem[];
-  /** caption lane (above main). */
-  caption_track: TimelineItem[];
-  /** bgm lane (below main). */
-  bgm_track: TimelineItem[];
-  part_library: Record<string, PartUnion>;
-  /** body_part_id -> { attachment part_id -> relative_time_position }. */
-  aggregations: Aggregation[];
-  timeline: {
-    duration_ms: number;
-    unit_time_ms: number;
-  };
-}
-/**
- * Working item the cascade solves over. `part_id` is the placement identity
- * (unique per lane). `time_position` is the authoritative input read from the
- * draft; `abs_time_position` is the cascade's solve variable (derived output),
- * seeded from `time_position` (or `fallback_abs_ms`) on read.
- *
- * `fallback_abs_ms` is the authoritative orphan-recovery snapshot carried beside
- * `time_position` (RFC 02 §11.1). On read it seeds the solve variable for
- * `anchored` items; on write it is refreshed to the freshly solved absolute
- * position.
- */
-interface TimelineItem {
-  part_id: string;
-  time_position: TrackItemTimePosition;
-  abs_time_position: number;
-  fallback_abs_ms?: number | undefined;
-}
-interface Aggregation {
-  body_part_id: string;
-  attachments: Array<{
-    part_id: string;
-    relative_time_position: number;
-  }>;
-}
-/** Empty placeholder clip marker: a video_clip part with no backing media. */
-declare function isEmptyVideoClip(part: PartUnion | undefined): boolean;
-/** Clamp a duration to a non-negative integer (NaN/Infinity/negative → 0). */
-declare function safeDurationMs(value: number | undefined): number;
-declare function partDurationMs(doc: TimelineDoc, partId: string): number;
-//#endregion
-//#region src/timeline-core/cascade.d.ts
-/**
- * Canonical timeline cascade primitives (ADR 0009).
- *
- * Single source of truth for "how an edit's connected regions move": main-track
- * seamless layout, aggregation position sync + reassignment, total-duration
- * recompute, speech-overlap resolution, gap filling. Reconciled per ADR 0009 §4:
- *
- * - product behavior follows the FE current implementation;
- * - all times are integer ms — positions/durations are rounded, never floated;
- * - function decomposition follows agent-harness (the Python-derived structure).
- *
- * Every function mutates the `TimelineDoc` in place (the editor runs them inside
- * one immer `transact`, so in-place edits diff correctly).
- */
-/**
- * Lay the main track out head-to-tail from 0, rewriting each item's
- * `abs_time_position`. Items whose part is missing from the library are dropped.
- */
-declare function arrangeMainTrackSeamlessly(doc: TimelineDoc): void;
-/**
- * Sync attached parts' absolute positions from their host:
- *   speech.abs   = host_video.abs + relative_time_position
- *   caption.abs  = speech.abs + caption.start_ms
- */
-declare function syncAggregatedClipsTimePosition(doc: TimelineDoc): void;
-/**
- * Reassign each speech to the video clip whose time range contains its start,
- * rebuilding `aggregations`. A speech before the first clip or after the last
- * falls back to the first / last clip respectively (FE: see §4 note — FE falls
- * back to last only; we keep the harness two-sided fallback because a speech
- * dragged before clip 0 belonging to the last clip is clearly wrong, and the FE
- * single-sided rule is an acknowledged rough edge). `relative_time_position` is
- * clamped to a non-negative integer.
- */
-declare function reassignSpeechesToVideoClipsByTime(doc: TimelineDoc): void;
-/**
- * Recompute `timeline.duration_ms` as the max end (abs + duration) across main,
- * speech, and caption lanes (BGM does not extend the timeline).
- *
- * BGM has no authoritative duration (RFC 02 / `reference/16` §0b): its effective
- * length is always the timeline total, so it is not written back here — the
- * projection derives it from `timeline.duration_ms` on read (`partDurationMs`
- * returns the timeline total for a bgm part). The empty-document 20s skeleton is
- * applied at that read step, not stored.
- */
-declare function recalculateTimelineDuration(doc: TimelineDoc): void;
-/**
- * Resolve one speech overlap by shifting the overlapping speech's host video
- * (and every clip after it) right. Returns true when one overlap was resolved;
- * callers loop until it returns false. The compared range is the speech merged
- * with its captions: start = min(speech.start, captions.start) (FE behavior),
- * end = max(speech.end, captions.end).
- */
-declare function resolveSpeechOverlapByShiftingVideos(doc: TimelineDoc): boolean;
-/**
- * Resolve speech overlaps for one cascade pass. Mirrors the authoritative FE
- * `ensureNoOverlappingClips`, which is documented to resolve AT MOST ONE overlap
- * per cascade and is invoked exactly once at every FE call site — the supported
- * ops each produce at most one new overlap. It is NOT a fixpoint loop: shifting a
- * host right also moves every speech anchored to it, so two speeches sharing a
- * host can never be separated by shifting. Looping to a "fixed point" there does
- * not converge — it accumulates the same overlap every iteration and pushes the
- * clip arbitrarily far right (e.g. a sped-up clip landing at ~287k ms instead of
- * its seamless slot). A single pass matches FE product behavior and terminates.
- */
-declare function resolveAllSpeechOverlaps(doc: TimelineDoc): void;
-/**
- * Make the main track gapless by adjusting/merging empty placeholder clips or
- * inserting new ones between real clips. Mirrors the harness four-case rule, but
- * the merge of two adjacent empty clips keeps the earlier clip (harness Case 4).
- * Requires `makeEmptyPart` to mint a placeholder part (the editor supplies an
- * id generator).
- */
-declare function fillMainTrackTimeGaps(doc: TimelineDoc, makeEmptyPart: (durationMs: number) => {
-  partId: string;
-}): void;
-//#endregion
-//#region src/timeline-core/entrypoints.d.ts
-/**
- * The composed cascade the read-side projection runs (RFC 02 §7): the ordered
- * step sequence `solveVideoDocument` applies to derive every absolute position,
- * aggregation, gap filler, and the total duration from the position-only facts.
- *
- * `makeEmptyPart` mints placeholder clips for gap filling; the projection
- * supplies a bounded id generator.
- */
-type MakeEmptyPart = (durationMs: number) => {
-  partId: string;
-};
-/**
- * The full solve pipeline: arrange → sync → reassign → resolve-overlap →
- * fill-gaps → recalc. The single cascade the read-side projection runs; ops
- * never call it (they write only facts — RFC 02 §7/§10).
- */
-declare function cascadeAfterVideoClipChanges(doc: TimelineDoc, makeEmptyPart: MakeEmptyPart): void;
-//#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>;
-}
-/**
- * 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): 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/timeline-core/locate.d.ts
-/**
- * Forward positioning for write-time ops (RFC 02 §9.1) — NOT a cascade.
- *
- * The authoritative model stores only `position`; absolute time is derived at
- * read time by the projection. But two write-time ops legitimately need to turn
- * an *absolute target* into a `relative` `position` fact:
- *
- * - moving / reordering main-track video clips re-parents each affected speech
- *   to the video clip its (unchanged) absolute landing now falls in (§9.1);
- * - moving a speech places it at a new absolute time, then anchors it to the
- *   host clip it lands in.
- *
- * Both need one forward computation: lay out the main track from flow order +
- * effective durations, find the clip whose range contains the target ms, and
- * emit `{ mode:'anchored', anchorPartId, offsetMs }`. This reads the current
- * facts and writes one new fact — it never solves and writes back the whole
- * layout (that stays the projection's job, read-side only).
- */
-interface MainClipRange {
-  partId: string;
-  startMs: number;
-  endMs: number;
-}
-/**
- * The flow-ordered main-track clip ranges (cumulative effective durations from
- * 0). Empty-media gap fillers are not in authoritative state, so this reflects
- * only the real clips the draft stores.
- */
-declare function mainTrackRanges(draft: VideoDocumentDraft): MainClipRange[];
-/**
- * Pick the host video clip an absolute time lands in, with the harness two-sided
- * fallback: before the first clip → first clip; after the last → last clip.
- * Returns null only when there is no clip at all (caller leaves the item as-is).
- */
-declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipRange | null;
-/**
- * Build an `anchored` time position anchoring `absMs` to the host clip it lands
- * in (offset clamped to a non-negative integer). Falls back to `absolute` when
- * there is no host clip. Pair with `fallbackAbsMs = absMs` on the item.
- */
-declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
-//#endregion
-export { type Aggregation, type Attachment, type BgmPart, type CaptionPart, type CaptionStyle, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImplementedSemanticOpKind, LANE_KINDS_IN_STACK_ORDER, type LaneKind, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocSyncState, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type OpActor, type PartAggregation, type PartKind, type PartUnion, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, SchemaValidator, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftContent, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type WaitForServerAckOptions, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };
+import { $ as Track, A as ContainNode, B as Media, C as Caption, D as CaptionText, E as CaptionStyle, F as EntityTable, G as ResourceSystem, H as RelationTable, I as EntityTables, J as TextEdit, K as RichTextSnapshot, L as EntityValues, M as DslDiagnostic, N as DslMutation, O as Clip, P as EntityMutation, Q as TimeAnchor, R as FieldPatch, S as AudioScript, T as CaptionSelection, U as RelationTables, V as RelationMutation, W as RelationValues, X as TextMutation, Y as TextMark, Z as TextRun, _ as defaultIdFactory, a as VideoDraftCaptionStyle, b as tupleHash, c as VideoDraftInput, d as VideoDraftTrack, et as TrackRole, f as VideoDraftTrackItem, g as EntityIdKind, h as DslIdFactory, i as VideoDraft, j as DeepReadonly, k as ContainMutation, l as VideoDraftPartUnion, m as OpActor, n as DEFAULT_UNIT_TIME_MS, o as VideoDraftContent, p as CommitOptions, q as TextDelta, r as VideoCreationSettings, s as VideoDraftContentPartUnion, t as CaptionDisplayCue, tt as Voice, u as VideoDraftTimeline, v as relationId, w as CaptionContent, x as Asset, y as resourceId, z as MedeoDslSnapshot } from "./video-draft-types-c_shaRyq.js";
+import { A as AddDslClip, C as MedeoDslDraft, D as captionContentCodec, E as InvalidAtomic, F as ReplaceDslClipsInput, I as ClipPlacement, M as ClipSource, N as DslClipUpdate, O as isInvalidAtomic, P as MoveDslClipsInput, S as documentFormat, T as medeoDslLoroShape, _ as MedeoDsl, a as toVideoDraft, b as UnsupportedDocumentFormatError, c as DslLayout, d as createInitialMedeoDsl, f as DslEditor, g as CreateMedeoDslOptions, h as VoiceoverResult, i as VideoDraftProjection, j as AddDslClipsInput, k as timeAnchorCodec, l as DslProjectionError, m as VoiceoverCaptionInput, n as ImportedVideoDraft, o as resolveDslLayout, p as ApplyVoiceoverInput, r as fromVideoDraft, s as DslClipLayout, t as FromVideoDraftOptions, u as DslTrackLayout, v as DslAudit, w as MedeoDslLoroState, x as assertDslDocument, y as DslTransaction } from "./index-DKDMTXUe.js";
+import { A as MengineAuditResponse, B as base64ToBytes, C as MengineEventStreamOptions, D as MengineHttpRequestError, E as MengineHttpClientOptions, F as MengineRejectedResponse, I as MengineSnapshotResponse, L as MengineSseUpdateEvent, M as MengineDraftResponse, N as MenginePushResponse, O as MenginePushRejectedError, P as MenginePushUpdateResponse, R as MengineSyncResponse, S as PushResultKind, T as MengineHttpClient, V as bytesToBase64, _ as encodeDocVersionMark, a as MengineDocSessionOptions, b as PullResult, c as DocStorageLike, d as MedeoHttpDocStorageOptions, f as PushOutcome, g as decodeDocVersionMark, i as MengineAckFailedError, j as MengineDocumentVersion, k as MengineAuditEntry, l as MengineUndoState, m as ManualSyncDocOptions, o as MengineDocSyncState, p as PushOutcomeKind, s as WaitForServerAckOptions, t as MemoryDocStorage, u as MedeoHttpDocStorage, v as DocVersionMark, w as readMengineEventStream, x as PushResult, y as PullFailureReason, z as MengineUpdateMeta } from "./index-B7fC7q7P.js";
+import { n as MengineDocSessionUpdateEvent, r as ManualSyncDoc, t as MengineDocSession } from "./index-DQZUkrpg.js";
+export { type AddDslClip, type AddDslClipsInput, type ApplyVoiceoverInput, type Asset, type AudioScript, type Caption, type CaptionContent, type CaptionDisplayCue, type CaptionSelection, type CaptionStyle, type CaptionText, type Clip, type ClipPlacement, type ClipSource, type CommitOptions, type ContainMutation, type ContainNode, type CreateMedeoDslOptions, DEFAULT_UNIT_TIME_MS, type DeepReadonly, type DocStorageLike, type DocVersionMark, type DslAudit, type DslClipLayout, type DslClipUpdate, type DslDiagnostic, DslEditor, type DslIdFactory, type DslLayout, type DslMutation, DslProjectionError, type DslTrackLayout, type DslTransaction, type EntityIdKind, type EntityMutation, type EntityTable, type EntityTables, type EntityValues, type FieldPatch, type FromVideoDraftOptions, type ImportedVideoDraft, type InvalidAtomic, ManualSyncDoc, type ManualSyncDocOptions, MedeoDsl, type MedeoDslDraft, type MedeoDslLoroState, type MedeoDslSnapshot, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type Media, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocSyncState, type MengineDocumentVersion, type MengineDraftResponse, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, type MengineUpdateMeta, type MoveDslClipsInput, type OpActor, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type RelationMutation, type RelationTable, type RelationTables, type RelationValues, type ReplaceDslClipsInput, type ResourceSystem, type RichTextSnapshot, type TextDelta, type TextEdit, type TextMark, type TextMutation, type TextRun, type TimeAnchor, type Track, type TrackRole, UnsupportedDocumentFormatError, type VideoCreationSettings, type VideoDraft, type VideoDraftCaptionStyle, type VideoDraftContent, type VideoDraftContentPartUnion, type VideoDraftInput, type VideoDraftPartUnion, type VideoDraftProjection, type VideoDraftTimeline, type VideoDraftTrack, type VideoDraftTrackItem, type Voice, type VoiceoverCaptionInput, type VoiceoverResult, type WaitForServerAckOptions, assertDslDocument, base64ToBytes, bytesToBase64, captionContentCodec, createInitialMedeoDsl, decodeDocVersionMark, defaultIdFactory, documentFormat, encodeDocVersionMark, fromVideoDraft, isInvalidAtomic, medeoDslLoroShape, readMengineEventStream, relationId, resolveDslLayout, resourceId, timeAnchorCodec, toVideoDraft, tupleHash };