edytor 0.0.11 → 0.1.0-next.16

package/dist/cloudflare/DocumentRoom.d.ts

@@ -0,0 +1,586 @@
+/**
+ * `DocumentRoom` — the Cloudflare Durable Object that coordinates ONE
+ * edytor document (one object per document) over hibernatable
+ * WebSockets. Clients are the shipped `WebsocketProvider` /
+ * `createWebsocketSync`; the host Worker reaches the room only through
+ * {@link routeDocumentSocket}, which authorizes the request and forwards
+ * the verified identity in the `X-Edytor-*` headers (and nothing the
+ * client sent).
+ *
+ * Built on the Worker-safe CRDT entry only (`crdt/index.ts` + the vendored
+ * engine). Entry point by entry point:
+ *
+ * - `fetch` (upgrade): read the verified identity, bind the socket's
+ *   replica to its user (a replica another user owns is accepted, then
+ *   closed `4409`), `ctx.acceptWebSocket` with the identity in the
+ *   attachment, then our SyncStep1 (a read-only socket gets the
+ *   read-only notice instead) and every present peer.
+ * - `webSocketMessage`: ADMIT first — the generation word, then the
+ *   identity: a read-only socket's Step2/Update is refused (permission
+ *   denied, the socket stays), and new structs under a client id its user
+ *   does not own are stripped from the frame (a relay of an id the room
+ *   holds nothing of is kept, unowned) — no attribution spoofing, and the
+ *   sender's own edits still land. Then the inbound schema refusal
+ *   (`sync.applyRemote`, which also judges what the engine holds pending:
+ *   a pending forged stamp the update would release is discarded, never
+ *   integrated). A refused frame
+ *   is never applied, stored or relayed. Every sync message is answered
+ *   with `messageSaved` (the room's state vector, and the deletes of the
+ *   message it stored), sent after the write (store-before-ack). Presence
+ *   is relayed through the instance-free codec, only for the socket's own
+ *   replica. Only bytes that do not decode are refused `malformed`
+ *   (1008); a storage or engine fault closes the socket 1011 (its
+ *   provider redials), after rebuilding the document where it may hold
+ *   what storage does not.
+ * - every INTEGRATED update is appended to SQLite as one record split into
+ *   rows ≤ `maxRowBytes` (2 MB row cap) in one `transactionSync`, then
+ *   broadcast; after `compactAfter` update records the rows are merged
+ *   (`mergeUpdates`) into one snapshot record, after the message is
+ *   acknowledged — never inside the engine's `update` observer, where one
+ *   throw would silence every later emit. Memory never runs ahead of
+ *   storage: when an append fails, nothing is relayed or acknowledged, the
+ *   live doc is rebuilt from the stored rows and the sender's socket is
+ *   closed (1011) so its provider reconnects and resends.
+ * - a delete of an item the room lacks waits in the engine and is stored
+ *   as a `pending` record (not the entries its frame's waiting rewrites
+ *   replace: those deletes wait with them, in memory); compaction keeps
+ *   the pending records apart, and rewrites them as the deletes still
+ *   waiting; a frame that discards a forged stamp drops them. At most
+ *   {@link MAX_WAITING_DELETES} ranges wait, stored or in memory: a frame
+ *   that would pass it has its waiting deletes dropped (refusal `waiting`,
+ *   left out of the ack), the rest applied. Compaction reclaims the
+ *   waiting deletes of client ids no user registered and no socket holds;
+ *   `dropWaitingDeletes()` every one.
+ * - a Step2 serves the STORED state: the engine's pending structs (waiting
+ *   for a dependency, never stored) are not served.
+ * - a frame larger than `maxFrameBytes` (32 MiB) goes out as chunks the
+ *   client applies only when complete (`chunkFrame`).
+ * - `webSocketClose`/`webSocketError`: the departure the client may not
+ *   have announced, read from the attachment (survives hibernation).
+ * - constructor: restore from SQLite alone under `blockConcurrencyWhile`
+ *   (verify the generation record, merge, `admission.admitUpdate`); a
+ *   container that cannot be restored (another generation, a torn record,
+ *   a refused `onLoad` payload) refuses every socket (1008); a read of the
+ *   rows that fails is the storage's fault, retried at the next dial
+ *   (1011). It never throws out of the constructor (the platform would
+ *   reset the object on every request).
+ *
+ * No entry point schedules a timer: each runs under {@link noTimers}
+ * (a Durable Object with a pending timer never hibernates). Keepalive is
+ * the runtime's: a text `ping` is answered `pong` without waking the
+ * object (`ctx.setWebSocketAutoResponse`, installed unless the host set
+ * its own pair; `webSocketMessage` answers it otherwise).
+ *
+ * Extending (subclass it, export the subclass):
+ *
+ * - `onLoad()` — retrieve: seed a room that stores nothing yet from your
+ *   own store (JSON, a v14 update, or `{ update, replicas }` from
+ *   `onSave`). Runs before any socket is served; nothing is stored until
+ *   it settles.
+ * - `onSave(document)` — save: mirror the document to your own store,
+ *   `saveAfter` ms after the first unsaved change (a Durable Object alarm,
+ *   so hibernation is unaffected; a throw is retried by the platform).
+ *   SQLite stays the room's source of truth: acks never wait on `onSave`.
+ * - `transact(fn)` — manipulate: edit through the document facade on the
+ *   server; persisted and broadcast to every socket like a client's edit
+ *   (one transaction, not a rollback: a throw from `fn` keeps its writes).
+ *   `read()` returns the document as JSON (both RPC-callable wrappers are
+ *   yours to define).
+ */
+import { DurableObject } from 'cloudflare:workers';
+import * as E from '../crdt/index.js';
+import type { AwarenessEntry, DocumentSemanticsConfig, EdytorDoc, JSONDoc, YDoc } from '../crdt/index.js';
+/** Under SQLite-backed Durable Objects' 2 MB row cap, with room for the other columns. */
+export declare const DEFAULT_MAX_ROW_BYTES: number;
+/** Update records before the rows are merged into one snapshot. */
+export declare const DEFAULT_COMPACT_AFTER = 500;
+/** ms between the first unsaved change and `onSave`. */
+export declare const DEFAULT_SAVE_AFTER = 2000;
+/**
+ * Delete ranges the room keeps waiting for items it does not hold (a
+ * relayer's delete of an author's edit a restore lost). Every update the
+ * engine applies re-reads them, so they are capped.
+ */
+export declare const MAX_WAITING_DELETES = 1024;
+/** Refusals kept in `refusals` (the newest); `refusalCounts` counts every one. */
+export declare const MAX_REFUSALS = 100;
+/**
+ * A client id and the user who owns it (the room's replica registry). An
+ * empty `user` marks an id a restore without a registry left unowned: its
+ * first authenticated writer claims it.
+ */
+export type ReplicaOwner = {
+    replica: number;
+    user: string;
+};
+/** The document as `onSave` receives it. */
+export type SavedDocument = {
+    /** The document as JSON. */
+    value: JSONDoc;
+    /** The full v14 state (`onLoad` takes it back). */
+    update: Uint8Array;
+    /**
+     * Who owns each client id, read with `update`. Store it beside `update`
+     * and return both from `onLoad`: without it, a restored room cannot
+     * tell which user wrote under which id.
+     */
+    replicas: ReplicaOwner[];
+};
+/** What `onLoad` may return: JSON, a bare v14 update, or `{ update, replicas }` (a `SavedDocument`). */
+export type LoadedDocument = JSONDoc | Uint8Array | Pick<SavedDocument, 'update' | 'replicas'>;
+/** The transaction origin of the room's own edits (`transact`, `onLoad` seeds). */
+export declare const ROOM_ORIGIN: unique symbol;
+/**
+ * Headers carrying the identity `routeDocumentSocket` verified — never the
+ * client's. The user id is percent-encoded (`encodeURIComponent`): a header
+ * value is trimmed and cannot carry every character, and a user id is any
+ * string.
+ */
+export declare const IDENTITY_HEADERS: {
+    readonly user: "X-Edytor-User";
+    readonly replica: "X-Edytor-Replica";
+    readonly access: "X-Edytor-Access";
+};
+/**
+ * Optional knobs (strings, as `vars` arrive): row size, outgoing frame
+ * limit and compaction threshold. The defaults are the platform limits.
+ */
+export type DocumentRoomEnv = {
+    EDYTOR_MAX_ROW_BYTES?: string | number;
+    EDYTOR_MAX_FRAME_BYTES?: string | number;
+    EDYTOR_COMPACT_AFTER?: string | number;
+    EDYTOR_SAVE_AFTER?: string | number;
+};
+/** What a socket is bound to: its verified user, its replica (Yjs client id), its access. */
+export type SocketIdentity = {
+    user: string;
+    /** `null` until bound — by `authorize`, or by the socket's first presence entry. */
+    replica: number | null;
+    readOnly: boolean;
+};
+/** A socket's attachment (survives hibernation): its identity and its presence clock. */
+export type Attachment = SocketIdentity & {
+    clock: number | null;
+};
+export type Refusal = {
+    reason: 'generation' | 'schema' | 'malformed' | 'container' | 'identity' | 'replica' | 'read-only' | 'waiting' | 'storage' | 'internal' | 'orphan' | 'relayed';
+    detail: unknown;
+};
+/** `pending`: deletes of items the room does not hold yet (they wait for them). */
+type RowKind = 'generation' | 'update' | 'snapshot' | 'pending';
+/**
+ * An upgrade accepted and closed at once, so the client reads `code`: a
+ * browser sees an HTTP error at the upgrade only as `1006`, which a
+ * provider cannot tell from a network failure. Refuse a dial your Worker
+ * turns away itself with it: the provider stops at `1008` or `4xxx`
+ * (except `4401`, redialed), and redials after anything else (`CLOSE`,
+ * `isRefusal` in `crdt/providers/room.ts`).
+ */
+export declare const closedSocket: (code: number, reason: string) => Response;
+/** Run an entry point with timers forbidden — a pending timer keeps a Durable Object from hibernating. */
+export declare const noTimers: <T>(fn: () => T) => T;
+/** A Yjs client id (a non-negative safe integer), or `null`. */
+export declare const parseReplica: (raw: unknown) => number | null;
+/** An awareness frame carrying `entries` — no `Awareness` instance involved. */
+export declare const presenceFrame: (entries: AwarenessEntry[]) => Uint8Array;
+/** What {@link attachDocument} (and `DocumentRoom`) takes. */
+export type AttachDocumentOptions = {
+    /**
+     * Retrieve: the document for a room that stores nothing yet. Return
+     * JSON, `{ update, replicas }` from `onSave` (a bare `update` restores
+     * the content, but not who owns which client id), or nothing for an
+     * empty room. Nothing is stored until it settles, so it is asked again
+     * at each start (and after a throw, at the next dial) until something
+     * is stored. A payload the room refuses (another generation or schema,
+     * undecodable bytes, another shape) refuses every socket (1008).
+     */
+    onLoad?: () => Promise<LoadedDocument | null | undefined> | LoadedDocument | null | undefined;
+    /**
+     * Save: mirror the document to your own store, `saveAfter` ms after the
+     * first unsaved change, on the object's alarm (a throw is retried by the
+     * platform). Without it no alarm is ever set.
+     */
+    onSave?: (document: SavedDocument) => Promise<void> | void;
+    /** ms between the first unsaved change and `onSave` (default {@link DEFAULT_SAVE_AFTER}). */
+    saveAfter?: number;
+    /** Update records before the rows are merged into one snapshot (default {@link DEFAULT_COMPACT_AFTER}). */
+    compactAfter?: number;
+    /** Largest stored row; can only be lowered (default {@link DEFAULT_MAX_ROW_BYTES}). */
+    maxRowBytes?: number;
+    /** Largest frame sent whole; can only be lowered (default 32 MiB). */
+    maxFrameBytes?: number;
+    /** Prefix of the document's SQL tables, beside your own (default `'edytor_'`). */
+    tablePrefix?: string;
+    /**
+     * The block roles `transact` edits obey — the document semantics your
+     * clients' plugins declare (`defaultType` also names the block an empty
+     * room is seeded with). Default
+     * {@link E.defaultSemantics} (the bundled rich-text, code and image kinds).
+     */
+    semantics?: DocumentSemanticsConfig;
+};
+/** The tag of the document's sockets: other sockets of the object are left to you. */
+export declare const SOCKET_TAG = "edytor";
+/**
+ * One edytor document living in a Durable Object's storage: the room
+ * logic, independent of the class that hosts it. Create it with
+ * {@link attachDocument} (any Durable Object) or extend `DocumentRoom`.
+ * The socket handlers ignore sockets without {@link SOCKET_TAG} and
+ * return `false` for them.
+ */
+export declare class AttachedDocument {
+    readonly ctx: DurableObjectState;
+    readonly maxRowBytes: number;
+    readonly maxFrameBytes: number;
+    readonly compactAfter: number;
+    readonly saveAfter: number;
+    private live;
+    /** Why the stored container was refused (another generation, a torn record, `onLoad`…). */
+    failure: Error | null;
+    /** Latest presence entry per replica, for join snapshots (memory: refills after a wake). */
+    presence: Map<number, E.AwarenessEntry>;
+    /** The newest {@link MAX_REFUSALS} refusals since this instance started (diagnostics; memory only). */
+    refusals: Refusal[];
+    /** Every refusal since this instance started, by reason. */
+    refusalCounts: Partial<Record<Refusal['reason'], number>>;
+    /** How this instance came to be: a fresh container, or a restore of N stored records. */
+    origin: {
+        kind: 'fresh';
+    } | {
+        kind: 'restored';
+        records: number;
+    };
+    private nextRecord;
+    private updates;
+    /** A failed append: the live doc holds what storage does not, until it is rebuilt. */
+    private unstored;
+    /** Inside `transact`, its commit included (a nested call is refused but while `fn` runs). */
+    private transacting;
+    /** Inside `transact`'s `fn`: a nested call joins the enclosing transaction. */
+    private running;
+    /** Inside a client frame's apply, its events included: the frame's handler settles it. */
+    private handling;
+    /** The waiting deletes stored as `pending` records (the engine may hold more, in memory). */
+    private storedWaiting;
+    /** The failure is the storage's (a failed read, `onLoad`'s store down): the next dial starts again. */
+    private retryable;
+    private readonly sql;
+    private _facade;
+    private saveScheduled;
+    /** Alarms in a row that found the rows unreadable: each re-arms later. */
+    private saveRetries;
+    private readonly options;
+    private readonly rowsTable;
+    private readonly replicasTable;
+    private _lookups;
+    constructor(ctx: DurableObjectState, options?: AttachDocumentOptions);
+    /**
+     * Restore from storage, or seed from `onLoad`. Never throws: a throw
+     * out of `blockConcurrencyWhile` resets the object on every request.
+     */
+    private start;
+    /** A read of the rows or `onLoad` failed (storage was down): start again. */
+    private retryStart;
+    private fail;
+    /** The room's block roles, read at first use (a subclass's fields exist by then). */
+    private get lookups();
+    /** A facade over `doc` obeying the room's block roles (`semantics`). */
+    private facadeOf;
+    /**
+     * The live document; `null` when the stored container was refused.
+     * Like {@link facade}, reading it first drops a direct write whose
+     * append failed (`heal`, only while the room is idle), so the next
+     * write through it is stored (HX-12).
+     */
+    get doc(): YDoc | null;
+    /**
+     * The facade over the live document. Read while the room is idle, it
+     * first drops a direct write whose append failed (`heal`), so the next
+     * write through it is stored (GX-09).
+     */
+    get facade(): EdytorDoc;
+    /**
+     * Inside a room `transact` (its commit included), a client frame's apply
+     * or any transaction's events: a write now could not be stored before
+     * it returns, and a failed append belongs to what is being handled.
+     */
+    private get busy();
+    /**
+     * Manipulate: run `fn` on the facade in one transaction. The edit is
+     * stored, then broadcast to every socket. It is not a rollback, like
+     * every client-side `transact`: when `fn` throws, what it wrote before
+     * the throw is kept (stored and broadcast) and its error is rethrown —
+     * validate before writing, or apply one `facade.prepare.*` plan. When
+     * the append fails, the storage error is thrown instead and nothing is
+     * kept (the live doc is rebuilt from the stored rows). A call inside
+     * `fn` joins the enclosing one. An empty room is first seeded with one
+     * empty block, as a client with no `value` would. Called anywhere else
+     * inside a transaction or its events — a `facade.onChange` subscriber
+     * (of a client's frame or of the room's own `transact`), a
+     * `doc.on('afterAllTransactions')` listener during a frame — it throws
+     * without writing: the engine would queue the write until that one
+     * ends, so it could not be stored before returning (DR-rest-1, HX-04).
+     */
+    transact<T>(fn: (facade: EdytorDoc) => T): T;
+    /** The document as JSON. */
+    read(): JSONDoc;
+    /**
+     * Runs `onSave` — the object's alarm, `saveAfter` ms after the first
+     * unsaved change. While the rows cannot be read (a retryable failure),
+     * it starts the room again; if that fails too, the save stays due: the
+     * alarm is set again, later at each failure (up to 5 minutes), so the
+     * mirror never silently lags what the room stored.
+     */
+    alarm(): Promise<void>;
+    /** The first unsaved change arms the save alarm; a wake keeps one already armed (`start`). */
+    private scheduleSave;
+    /**
+     * Generation cutover: drop the stored document (both tables) of a room
+     * whose storage belongs to another edytor generation, and start again
+     * from `onLoad` — reseed it from JSON. Refused for any other room.
+     */
+    reset(): Promise<void>;
+    /**
+     * Seed a fresh room from `onLoad`. Nothing is stored before it settles:
+     * a throw or nothing leaves the room fresh, asked again at the next
+     * start (after a throw, also at the next dial). The payload is admitted
+     * like a stored container, then stored as one snapshot record with its
+     * registry, atomically. The deletes it carries of items it lacks (an
+     * `onSave` mirror holds the waiting ones) are stored apart, as one
+     * `pending` record, as a frame's are: acknowledged by id, reclaimed by
+     * compaction.
+     */
+    private seed;
+    /**
+     * Restore the live doc from the stored rows. A read of the rows that
+     * fails is the storage's fault: retryable, the next dial loads again
+     * (at cold start, at a retry, after a rebuild). A container that reads
+     * but cannot be restored (a torn record, another generation, bytes the
+     * engine refuses) is refused for good.
+     */
+    private load;
+    /** Reassembled logical records in write order; a torn record throws. */
+    records(): Array<{
+        kind: RowKind;
+        bytes: Uint8Array<ArrayBuffer>;
+    }>;
+    /**
+     * One logical record split into rows ≤ `maxRowBytes` (callers run it in
+     * a transaction). The first record of an empty container brings the
+     * generation record with it.
+     */
+    private insert;
+    /**
+     * Compaction: the rows become the generation record + one chunked
+     * snapshot, `mergeUpdates` of every stored record, atomically, + one
+     * `pending` record of the stored deletes still waiting. A waiting delete
+     * of a client id no user registered and no socket holds is reclaimed,
+     * in memory too: nothing can deliver its item (a made-up id) — the
+     * registrations of ids with waiting deletes are kept. The registry
+     * keeps the ids holding content and those bound to an open socket; the
+     * others (page loads that never wrote) are dropped, and re-register at
+     * their next dial or write. Runs by itself after `compactAfter` update
+     * records; callable over RPC (e.g. from the host's own alarm).
+     */
+    compact(): {
+        rows: number;
+    };
+    /**
+     * Drop every waiting delete, stored or in memory (callable over RPC):
+     * the way out when a writer filled {@link MAX_WAITING_DELETES} with
+     * deletes of registered ids' items, which compaction keeps. A dropped
+     * delete's item shows if it ever arrives — but for an entry a waiting
+     * rewrite replaces, which that rewrite deletes should it integrate.
+     * Returns how many ranges were dropped.
+     */
+    dropWaitingDeletes(): {
+        ranges: number;
+    };
+    /**
+     * A fault of the room while it handled `ws`'s frame, never the client's
+     * doing (so never a refusal): a failed append (`unstored`) or registry
+     * write (`storage`), the engine or a send (`internal`). After a failed
+     * append or an engine fault the live doc may hold what storage does
+     * not: it is rebuilt from the stored rows alone (as a restart would),
+     * so nothing unstored is ever served or acknowledged. The socket is
+     * closed 1011: its provider redials, the join rule finds what the room
+     * lacks, and the edit is resent and stored.
+     */
+    private fault;
+    /**
+     * Automatic compaction, once the message that made it due is
+     * acknowledged. A failure is logged and retried after half the
+     * threshold; the edit is already stored and nobody is closed.
+     */
+    private compactIfDue;
+    /**
+     * Drop the live doc for the stored rows (a failed append, an engine
+     * fault): `doc` and `facade` are replaced, and subscriptions on the old
+     * ones end. A read that fails now is retryable: the next dial loads
+     * again. The room's own writes (`waiting`) change nothing the engine
+     * holds waiting (updates missing a dependency, deletes kept in memory):
+     * that is carried over, not lost as at a restart.
+     */
+    private rebuild;
+    /**
+     * A room-side write outside `transact` (straight through `facade`)
+     * whose append failed left the live doc ahead of storage: rebuild it
+     * before anything is served, read or acknowledged. Only while the room
+     * is idle (not `busy`): from inside a transaction, a frame's apply or
+     * their events (a `facade.onChange` subscriber, a
+     * `doc.on('afterAllTransactions')` listener), the failure stays for
+     * the handler — a frame's faults its sender, `transact` throws it
+     * (SW16-room-1, HX-03).
+     */
+    private heal;
+    /** Run a frame's apply: nothing its listeners do heals it (HX-03). */
+    private handle;
+    private requireDoc;
+    private adopt;
+    /** A registry read or write, its SQLite fault tagged (the socket closes 1011, never 1008). */
+    private registry;
+    /** Who owns `client`: a user, `''` (unowned: its dial claims it), or `undefined` (unregistered). */
+    private ownerOf;
+    /** Register `owners` in one transaction; an unowned (`''`) row never replaces an owner. */
+    private register;
+    /**
+     * May `user` bind `replica` to a socket (its dial, or its first presence
+     * entry)? Its own id; an unregistered id with no content in the room,
+     * registered now whatever the socket's access (so a viewer's id cannot be
+     * taken before it is granted edit); an unowned id (`''`), which a
+     * `writer` claims (logged `orphan`). Not another user's id, nor
+     * unregistered history.
+     */
+    private bind;
+    /**
+     * Which new writers of an update a socket may deliver; returns those
+     * stripped from its frame (the rest of the frame is applied: never
+     * refused whole). Written: its user's ids, and its own replica (the
+     * dialed or bound one), which claims an unowned id or a fresh one, as
+     * `bind` would. A socket with no replica claims fresh ids it writes.
+     * Any other id is relayed — another replica's structs, which a restore
+     * from a lagging snapshot may have lost: kept, and left unowned (`''`,
+     * claimable only by its own dial), when the room holds none of that id's
+     * clocks and no user owns it; stripped otherwise (logged `replica`).
+     * Ownership never moves to a relayer.
+     */
+    private attribute;
+    fetch(request: Request): Promise<Response>;
+    /** Is `ws` one of this document's sockets? */
+    owns(ws: WebSocket): boolean;
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): boolean;
+    webSocketClose(ws: WebSocket, code: number, reason: string): boolean;
+    webSocketError(ws: WebSocket): boolean;
+    /** The departure the client may not have announced — from the attachment, so it works after a wake. */
+    private depart;
+    private onSync;
+    /**
+     * A delete of items the room does not hold (a relayer's delete of an
+     * author's edit a restore lost) waits in the engine for them: it is
+     * stored as it arrives, so it survives eviction and compaction and
+     * applies when the author's edit returns. Except the entries the frame's
+     * own still-waiting rewrites replace (`stay`): those deletes wait with
+     * the rewrites in memory, as the rewrites may never integrate. A frame
+     * that released a pending forged stamp discarded every waiting delete
+     * (`applyRemote`): the stored ones go too. The deletes the frame applied
+     * from the waiting ones go back to its sender, whom the relay of the
+     * update skips; they are returned. The cap holds here too: deletes of
+     * the frame's own structs that wait for an origin (stored, or kept in
+     * memory with its rewrites) pass the check before applying; when the
+     * frame's new waiting deletes take the room past
+     * {@link MAX_WAITING_DELETES}, they are all dropped (refusal `waiting`,
+     * the sender's), unstored and unacknowledged. A replaced entry is
+     * deleted by its rewrite anyway, should that integrate.
+     */
+    private settleDeletes;
+    /**
+     * Of `deletes`, those the room stored — applied, or waiting in a
+     * `pending` record — and so acknowledges by id: never one it dropped
+     * (the waiting cap, a stripped rewrite's replaced entry) or keeps
+     * waiting in memory only.
+     */
+    private storedDeletes;
+    /**
+     * Presence through the instance-free codec, for the socket's own replica
+     * only (bound by `authorize`, else by its first entry): the newest clock
+     * wins, the attachment records the clock, the accepted entry is relayed
+     * — to its sender too (a no-op for it), so a lone socket hears from the
+     * room at every renewal and is never torn down as silent.
+     * Entries for other replicas (a client re-sending what it heard) are dropped.
+     */
+    private onPresence;
+    /** Log a refusal: the newest {@link MAX_REFUSALS} are kept, every reason is counted. */
+    private note;
+    /** A refused frame is dropped whole and its socket closed (1008 policy violation). */
+    private refuse;
+    private close;
+    /**
+     * No document to serve: a container that cannot be restored is
+     * refused for good (1008, the provider stops dialing); a failed read of
+     * the rows or an `onLoad` that threw is retried at the next dial (1011,
+     * the provider redials).
+     */
+    private refuseContainer;
+    /** Send one frame — as chunks when it exceeds `maxFrameBytes` (bounded catch-up). */
+    private send;
+    private broadcast;
+}
+/**
+ * Attach an edytor document to any Durable Object (`attachDocument(this,
+ * opts)`, in the constructor or a field). Its tables (`edytor_rows`,
+ * `edytor_replicas`) live beside yours and its sockets carry
+ * {@link SOCKET_TAG}. Each handler your class does not define —
+ * `fetch`, `webSocketMessage`, `webSocketClose`, `webSocketError`, and
+ * `alarm` when `onSave` is set — is installed on the object; a class that
+ * defines one delegates to the returned document's method (which returns
+ * `false` for a socket that is not the document's).
+ */
+export declare const attachDocument: (host: DurableObject<any>, options?: AttachDocumentOptions) => AttachedDocument;
+/**
+ * The ready-made room: a Durable Object hosting one document, configured
+ * by `vars` ({@link DocumentRoomEnv}). Subclass it to override `onLoad` and
+ * `onSave`, and add your own RPC methods over `transact`/`read`. Its tables
+ * are `rows` and `replicas` (no prefix).
+ */
+export declare class DocumentRoom<Env = DocumentRoomEnv> extends DurableObject<Env> {
+    readonly room: AttachedDocument;
+    constructor(ctx: DurableObjectState, env: Env);
+    /** Retrieve — see {@link AttachDocumentOptions.onLoad}. */
+    protected onLoad(): Promise<LoadedDocument | null | undefined>;
+    /** Save — see {@link AttachDocumentOptions.onSave}. Not overridden: no alarm is ever set. */
+    protected onSave(_document: SavedDocument): Promise<void>;
+    /**
+     * Block roles — see {@link AttachDocumentOptions.semantics}. Read once,
+     * at first use (after construction: it may return a subclass field).
+     */
+    protected semantics(): DocumentSemanticsConfig;
+    fetch(request: Request): Promise<Response>;
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void;
+    webSocketClose(ws: WebSocket, code: number, reason: string): void;
+    webSocketError(ws: WebSocket): void;
+    /** Runs `onSave`. Call `super.alarm()` if you override it. */
+    alarm(): Promise<void>;
+    /** Compaction, also over RPC. */
+    compact(): {
+        rows: number;
+    };
+    /** Drop the stored waiting deletes, also over RPC — see {@link AttachedDocument.dropWaitingDeletes}. */
+    dropWaitingDeletes(): {
+        ranges: number;
+    };
+    /** Generation cutover, also over RPC — see {@link AttachedDocument.reset}. */
+    reset(): Promise<void>;
+    /** Server-side edit — see {@link AttachedDocument.transact}. */
+    transact<T>(fn: (facade: EdytorDoc) => T): T;
+    /** The document as JSON. */
+    read(): JSONDoc;
+    get facade(): EdytorDoc;
+    get doc(): YDoc | null;
+    get failure(): Error | null;
+    get refusals(): Refusal[];
+    get refusalCounts(): AttachedDocument['refusalCounts'];
+    get presence(): Map<number, AwarenessEntry>;
+    get origin(): AttachedDocument['origin'];
+    records(): ReturnType<AttachedDocument['records']>;
+}
+export {};