@mengine/medeo-client 2.1.0 → 2.1.1-dsl.1

package/dist/index-B7fC7q7P.d.ts

@@ -0,0 +1,728 @@
+import { M as DslDiagnostic, o as VideoDraftContent, p as CommitOptions } from "./video-draft-types-c_shaRyq.js";
+import { LoroDoc, PeerID, VersionVector } 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 MengineDraftResponse {
+  content: VideoDraftContent;
+  diagnostics: readonly DslDiagnostic[];
+  version: MengineDocumentVersion;
+}
+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>;
+  /** Read-only compatibility content and diagnostics at the same causal version. */
+  fetchDraft(): Promise<MengineDraftResponse>;
+  fetchDraftAt(updateSeq: number): Promise<MengineDraftResponse>;
+  /**
+   * 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/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-transport.d.ts
+interface ManualSyncDocOptions {
+  client: MengineHttpClient;
+  peerId?: PeerID;
+}
+/** Shared explicit pull/push lifecycle; model-specific editors never implement transport. */
+declare class ManualSyncTransport {
+  private readonly client;
+  protected readonly doc: LoroDoc;
+  private watermark;
+  private disposed;
+  protected constructor(client: MengineHttpClient, doc: LoroDoc, watermark: VersionVector);
+  editorPeerId(): PeerID;
+  protected assertActive(): void;
+  dispose(): void;
+  /**
+   * 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. The editor 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-mutation-guard.d.ts
+/**
+ * @internal
+ * Shared by synchronous mutation entry points for one document. The session
+ * closes it before teardown callbacks can attempt another write.
+ */
+declare class DocumentMutationGuard {
+  private readonly readonlyMode;
+  private running;
+  private closed;
+  constructor(readonlyMode?: boolean);
+  run<T>(mutation: () => T): T;
+  close(): void;
+}
+//#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/document-session.d.ts
+interface DocumentSessionUpdateEvent<Snapshot> {
+  source: 'remote' | 'local';
+  snapshot: Snapshot;
+}
+/**
+ * Raised by {@link DocumentSession.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;
+  /**
+   * Keep remote synchronization read-only: pull snapshot/diffs and subscribe to
+   * SSE updates, but never POST local Loro updates to the server.
+   */
+  readonlyMode?: boolean;
+}
+interface DocumentSessionBinding<Snapshot, Editor, Document> {
+  doc: LoroDoc;
+  document: Document;
+  editor: Editor;
+  snapshot(): Snapshot;
+  subscribe(listener: (source: 'local' | 'remote') => void): () => void;
+  dispose(): void;
+}
+type DocumentSessionModel<Snapshot, Editor, Document> = (doc: LoroDoc, guard: DocumentMutationGuard) => DocumentSessionBinding<Snapshot, Editor, Document>;
+/** Shared binary synchronization lifecycle. Models attach only after initial loading succeeds. */
+declare class DocumentSession<Snapshot, Editor, Document> {
+  private readonly options;
+  private readonly model;
+  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, model: DocumentSessionModel<Snapshot, Editor, Document>);
+  /**
+   * 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(): Editor;
+  /**
+   * Opaque version token of the local oplog (base64 `VersionVector.encode`).
+   * Equality-comparable only: equal means no observed change (local or
+   * remote-arrived) since the token was taken. Throws when not started.
+   */
+  version(): string;
+  protected get document(): Document;
+  /** Current document snapshot (read model). */
+  snapshot(): Snapshot;
+  /** 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<Snapshot>;
+  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: DocumentSessionUpdateEvent<Snapshot>) => 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
+export { MengineAuditResponse as A, base64ToBytes as B, MengineEventStreamOptions as C, MengineHttpRequestError as D, MengineHttpClientOptions as E, MengineRejectedResponse as F, MengineSnapshotResponse as I, MengineSseUpdateEvent as L, MengineDraftResponse as M, MenginePushResponse as N, MenginePushRejectedError as O, MenginePushUpdateResponse as P, MengineSyncResponse as R, PushResultKind as S, MengineHttpClient as T, bytesToBase64 as V, encodeDocVersionMark as _, MengineDocSessionOptions as a, PullResult as b, DocStorageLike as c, MedeoHttpDocStorageOptions as d, PushOutcome as f, decodeDocVersionMark as g, ManualSyncTransport as h, MengineAckFailedError as i, MengineDocumentVersion as j, MengineAuditEntry as k, MengineUndoState as l, ManualSyncDocOptions as m, DocumentSession as n, MengineDocSyncState as o, PushOutcomeKind as p, DocumentSessionUpdateEvent as r, WaitForServerAckOptions as s, MemoryDocStorage as t, MedeoHttpDocStorage as u, DocVersionMark as v, readMengineEventStream as w, PushResult as x, PullFailureReason as y, MengineUpdateMeta as z };