@kition/sync 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,484 @@
1
+ /**
2
+ * The open sync protocol, `kition-sync/1` (Kition platform docs/platform/reference/sync-protocol.md): JSON-RPC 2.0 messages over a
3
+ * WebSocket. Binary payloads (KDM change bytes, snapshots, blobs) travel as separate binary
4
+ * frames; see `./framing`. These are the JSON-visible shapes, with binary fields as `Uint8Array`
5
+ * (the wire's `{"$bin": n}` markers are an encoding detail `./framing` and `./client` handle).
6
+ */
7
+ import type { SaveFailure, SaveState, SaveTrigger } from './saveMachine.js';
8
+ export declare const SYNC_PROTOCOL = "kition-sync/1";
9
+ /**
10
+ * A room's role for one principal: `owner` and `editor` may push any change, `commenter` (protocol
11
+ * 1.6) only changes that touch comment objects (KitModel rule M23), `viewer` none.
12
+ */
13
+ export type Role = 'owner' | 'editor' | 'commenter' | 'viewer';
14
+ /** Roles by what they allow: `viewer` < `commenter` < `editor` < `owner`. */
15
+ export declare const ROLE_RANK: Record<Role, number>;
16
+ /**
17
+ * `error.data.code` (never the JSON-RPC `code`/`message`, which are for logs and people).
18
+ * `collab-limit`: the room is at the server's limit of people co-editing at once
19
+ * (`error.data.limit`); the person can still open, edit, and save alone.
20
+ */
21
+ export type ErrorCode = 'unauthorized' | 'forbidden' | 'not-found' | 'conflict' | 'invalid' | 'unavailable' | 'rate-limited' | 'collab-limit';
22
+ export type ClientInfo = {
23
+ name: string;
24
+ version: string;
25
+ };
26
+ export type ServerInfo = {
27
+ name: string;
28
+ version: string;
29
+ };
30
+ export type Principal = {
31
+ id: string;
32
+ name: string;
33
+ };
34
+ /** One peer's presence in a room; `state` is a kit's own ephemeral cursor/selection shape. */
35
+ export type Presence = {
36
+ principalId: string;
37
+ name: string;
38
+ color: string;
39
+ state: unknown;
40
+ };
41
+ export type HelloParams = {
42
+ protocol: string;
43
+ token: string;
44
+ client: ClientInfo;
45
+ capabilities: string[];
46
+ };
47
+ export type HelloResult = {
48
+ server: ServerInfo;
49
+ principal: Principal;
50
+ capabilities: string[];
51
+ open?: OpenScope;
52
+ };
53
+ /** The capability a server lists when it takes open tokens and keeps one room per file generation (protocol 1.10, `KitCollab 1.4`). */
54
+ export declare const OPEN_ROOMS_CAPABILITY = "open-rooms";
55
+ /**
56
+ * What an open-token connection reaches (protocol 1.10, managed-collab.md RM1): exactly one file
57
+ * generation's room, `(tenant, iss, file, docKey)`, at the role its permissions grant (never `owner`).
58
+ */
59
+ export type OpenScope = {
60
+ tenant: string;
61
+ iss: string;
62
+ file: string;
63
+ docKey: string;
64
+ role: Exclude<Role, 'owner'>;
65
+ perms: {
66
+ edit: boolean;
67
+ comment: boolean;
68
+ download: boolean;
69
+ share: boolean;
70
+ export: boolean;
71
+ };
72
+ };
73
+ /**
74
+ * `room/resolve` (protocol 1.10, open-token connections): the room of the connection's file
75
+ * generation (`docId`, or `null`), and with `claim` the seed claim when there is none (RM5):
76
+ * `claimed` is true for exactly one editor at a time, for 60 seconds.
77
+ */
78
+ export type RoomResolveParams = {
79
+ claim?: boolean;
80
+ };
81
+ export type RoomResolveResult = {
82
+ docId: string | null;
83
+ claimed: boolean;
84
+ save: SaveState | null;
85
+ };
86
+ /** `room/resolved` (server to client, protocol 1.10): the connection's file generation now has a room. */
87
+ export type RoomResolvedParams = {
88
+ docId: string;
89
+ };
90
+ /**
91
+ * Catch-up is by the room's own server sequence, not a KDM version, so the server never needs a
92
+ * replica of its own to answer it. `since` is the highest `seq` the caller already has (`null`:
93
+ * none, catch up from the room's snapshot). A room can have more changes than fit in one
94
+ * message's binary frames, so the result pages: `limit` caps how many changes come back (a
95
+ * server may cap it lower still; omitted asks for the server's own default). When `more` is
96
+ * `true`, `seq` is the last included change's `seq` (not the room's latest) and the caller
97
+ * repeats `room/join` with `since` set to it; when `more` is `false`, `seq` is the room's latest.
98
+ */
99
+ export type RoomJoinParams = {
100
+ docId: string;
101
+ since: number | null;
102
+ limit?: number;
103
+ shallow?: boolean;
104
+ prefer?: SnapshotPreference;
105
+ };
106
+ /**
107
+ * `snapshot` (protocol 1.5): `since` was older than the history the server keeps change by change,
108
+ * so `changes[0]` is a snapshot of the document (imported like any change set) and the rest follow it.
109
+ * `shallow` (protocol 1.8): answered to a `since: null` join that asked for a shallow start;
110
+ * `changes[0]` is a shallow snapshot of the room's latest state, which the client loads as a new
111
+ * replica (`Replica.load`), never imports into an existing one.
112
+ */
113
+ export type RoomJoinResult = {
114
+ changes: Uint8Array[];
115
+ seq: number;
116
+ more: boolean;
117
+ presence: Presence[];
118
+ role: Role;
119
+ snapshot?: boolean;
120
+ shallow?: boolean;
121
+ };
122
+ export type ChangesPushParams = {
123
+ docId: string;
124
+ changes: Uint8Array;
125
+ };
126
+ export type ChangesPushResult = {
127
+ seq: number;
128
+ };
129
+ /** Server to client, notification. */
130
+ export type ChangesPullParams = {
131
+ docId: string;
132
+ changes: Uint8Array;
133
+ seq: number;
134
+ from: string;
135
+ };
136
+ /** Client to server, notification: ephemeral, never persisted. */
137
+ export type PresenceSetParams = {
138
+ docId: string;
139
+ state: unknown;
140
+ };
141
+ /** Server to client, notification: replaces the room's peer list. */
142
+ export type PresenceUpdateParams = {
143
+ docId: string;
144
+ peers: Presence[];
145
+ };
146
+ /**
147
+ * Blobs are scoped to documents (protocol 1.5): `blob/put` records that `docId` references the
148
+ * blob, and `blob/has`/`blob/get` answer only blobs `docId` references, for a principal that may
149
+ * read its room. A blob another document references is `missing` here until this one uploads it.
150
+ */
151
+ export type BlobHasParams = {
152
+ docId: string;
153
+ hashes: string[];
154
+ };
155
+ export type BlobHasResult = {
156
+ missing: string[];
157
+ };
158
+ export type BlobPutParams = {
159
+ docId: string;
160
+ hash: string;
161
+ mime: string;
162
+ data: Uint8Array;
163
+ };
164
+ export type BlobPutResult = Record<string, never>;
165
+ export type BlobGetParams = {
166
+ docId: string;
167
+ hash: string;
168
+ };
169
+ export type BlobGetResult = {
170
+ data: Uint8Array;
171
+ mime: string;
172
+ };
173
+ /**
174
+ * Protocol 1.8: the kind of snapshot a client would rather start from when the server may choose:
175
+ * `shallow` for a document past the server's size threshold (a full one otherwise), or `full`.
176
+ */
177
+ export type SnapshotPreference = 'shallow' | 'full';
178
+ /**
179
+ * `shallow` (protocol 1.8) asks for a shallow snapshot of the room's latest state (standard 2.0
180
+ * rule M16a): its current state with only recent history; `prefer: 'shallow'` lets the server
181
+ * choose one for a large document.
182
+ */
183
+ export type SnapshotGetParams = {
184
+ docId: string;
185
+ shallow?: boolean;
186
+ prefer?: SnapshotPreference;
187
+ };
188
+ /** `shallow` (protocol 1.8): `snapshot` is shallow; the history before its root stays on the server (`history/get`). */
189
+ export type SnapshotGetResult = {
190
+ snapshot: Uint8Array;
191
+ seq: number;
192
+ shallow?: boolean;
193
+ };
194
+ /** `private` (protocol 1.9): a private room, synced to its owner's own devices, with no share link. */
195
+ export type RoomCreateParams = {
196
+ docId: string;
197
+ snapshot: Uint8Array;
198
+ name: string;
199
+ kit: string;
200
+ private?: boolean;
201
+ };
202
+ export type RoomCreateResult = {
203
+ shareLink: string;
204
+ };
205
+ /** A private room has no share link until its owner mints one (`room/link`), protocol 1.9. */
206
+ export type PrivateRoomCreateResult = {
207
+ shareLink: null;
208
+ };
209
+ /**
210
+ * One room in a principal's document list (protocol 1.9): `updated` is when it last changed
211
+ * (milliseconds since the Unix epoch), `size` about how many bytes the server keeps for its
212
+ * current state, `private` whether only its owner's devices sync it.
213
+ */
214
+ export type RoomListing = {
215
+ docId: string;
216
+ name: string;
217
+ kit: string;
218
+ role: Role;
219
+ updated: number;
220
+ size: number;
221
+ private: boolean;
222
+ };
223
+ /** `rooms/list` (protocol 1.9): one page of the caller's rooms, most recently changed first. */
224
+ export type RoomsListParams = {
225
+ cursor?: string;
226
+ limit?: number;
227
+ };
228
+ /** `cursor` is `null` on the last page. */
229
+ export type RoomsListResult = {
230
+ rooms: RoomListing[];
231
+ cursor: string | null;
232
+ };
233
+ /** `rooms/changed` (protocol 1.9): an entry of the receiver's list now, or `null` when it left the list. */
234
+ export type RoomsChangedParams = {
235
+ docId: string;
236
+ room: RoomListing | null;
237
+ };
238
+ /**
239
+ * A principal's account settings (protocol 1.9, `account/settings`, `account/update`,
240
+ * `account/changed`): `syncAll`, every document the person opens syncs to their devices.
241
+ */
242
+ export type AccountSettings = {
243
+ syncAll: boolean;
244
+ };
245
+ /**
246
+ * Resolves a share link (`RoomCreateResult.shareLink`) to the room it points to and the role the
247
+ * caller would join it with; it does not itself join the room (send `room/join` with `docId` for
248
+ * that).
249
+ */
250
+ export type RoomOpenParams = {
251
+ shareLink: string;
252
+ };
253
+ export type RoomOpenResult = {
254
+ docId: string;
255
+ name: string;
256
+ kit: string;
257
+ role: Role;
258
+ };
259
+ /**
260
+ * Mints another share link to a room the caller is a member of (protocol 1.4), granting `role`
261
+ * (`editor`, `commenter` since 1.6, or `viewer`, never more than the caller's own role): a view-only link, say, next to
262
+ * the editing link `room/create` answered.
263
+ */
264
+ export type RoomLinkParams = {
265
+ docId: string;
266
+ role: Exclude<Role, 'owner'>;
267
+ };
268
+ export type RoomLinkResult = {
269
+ shareLink: string;
270
+ };
271
+ /** A member of a room (protocol 1.6): `name` is the display name they last joined with. */
272
+ export type Member = {
273
+ principalId: string;
274
+ name: string;
275
+ role: Role;
276
+ };
277
+ /** A share link that still works (protocol 1.6): the role it grants and who minted it. */
278
+ export type ShareLink = {
279
+ shareLink: string;
280
+ role: Exclude<Role, 'owner'>;
281
+ createdBy: string;
282
+ };
283
+ /** `room/members` (protocol 1.6): for the room's owner or an editor. */
284
+ export type RoomMembersParams = {
285
+ docId: string;
286
+ };
287
+ export type RoomMembersResult = {
288
+ members: Member[];
289
+ links: ShareLink[];
290
+ };
291
+ /** `room/setRole` (protocol 1.6): the owner changes another member's role. */
292
+ export type RoomSetRoleParams = {
293
+ docId: string;
294
+ principalId: string;
295
+ role: Exclude<Role, 'owner'>;
296
+ };
297
+ /** `room/removeMember` (protocol 1.6): the owner removes another member. */
298
+ export type RoomRemoveMemberParams = {
299
+ docId: string;
300
+ principalId: string;
301
+ };
302
+ /** `room/revokeLink` (protocol 1.6): the owner revokes a share link. */
303
+ export type RoomRevokeLinkParams = {
304
+ docId: string;
305
+ shareLink: string;
306
+ };
307
+ /** Server to client, notification (protocol 1.6): the receiver's role changed; `null`: removed. */
308
+ export type RoomAccessParams = {
309
+ docId: string;
310
+ role: Role | null;
311
+ };
312
+ /** Client to server, notification. */
313
+ export type RoomLeaveParams = {
314
+ docId: string;
315
+ };
316
+ /** `history/list` (protocol 1.5): checkpoints newest first, before `before` (omitted: the latest). */
317
+ export type HistoryListParams = {
318
+ docId: string;
319
+ before?: number;
320
+ limit?: number;
321
+ };
322
+ /**
323
+ * A point the document's history can be read at or restored to: a run of changes one principal
324
+ * pushed (`kind: 'changes'`, `firstSeq`..`seq`), or a snapshot older history was compacted into.
325
+ * `time` is milliseconds since the Unix epoch.
326
+ */
327
+ export type Checkpoint = {
328
+ seq: number;
329
+ firstSeq: number;
330
+ time: number;
331
+ principalId: string | null;
332
+ changes: number;
333
+ kind: 'changes' | 'snapshot';
334
+ };
335
+ /** `more`: older checkpoints remain; ask again with `before` set to the last one's `firstSeq`. */
336
+ export type HistoryListResult = {
337
+ checkpoints: Checkpoint[];
338
+ more: boolean;
339
+ };
340
+ /** `history/get` (protocol 1.5): the document as of `seq` (or the nearest snapshot before it, which `seq` names). */
341
+ export type HistoryGetParams = {
342
+ docId: string;
343
+ seq: number;
344
+ };
345
+ export type HistoryGetResult = {
346
+ snapshot: Uint8Array;
347
+ seq: number;
348
+ };
349
+ /**
350
+ * `history/restore` (protocol 1.5): an owner or editor of a joined room restores the document as of
351
+ * `seq` as one new change, which every member, the caller too, receives as `changes/pull`. `seq` is
352
+ * that change's (`null`: the document was already in that state); `restored` is the state's `seq`.
353
+ */
354
+ export type HistoryRestoreParams = {
355
+ docId: string;
356
+ seq: number;
357
+ };
358
+ export type HistoryRestoreResult = {
359
+ seq: number | null;
360
+ restored: number;
361
+ };
362
+ /**
363
+ * A lease on one scope of a room (protocol 1.5, section 8): who holds it, the holder's session
364
+ * (opaque; it tells a client its own leases from others'), and `ttl`, the milliseconds it had left
365
+ * when sent (informational: a lease ends only when `lease/changed` drops it).
366
+ */
367
+ export type Lease = {
368
+ scope: string;
369
+ principalId: string;
370
+ name: string;
371
+ session: string;
372
+ ttl: number;
373
+ };
374
+ /** `lease/acquire`: `ttl` in milliseconds (omitted: the server's default, 30 000; a server clamps it). */
375
+ export type LeaseAcquireParams = {
376
+ docId: string;
377
+ scope: string;
378
+ ttl?: number;
379
+ };
380
+ export type LeaseAcquireResult = {
381
+ lease: Lease;
382
+ };
383
+ export type LeaseReleaseParams = {
384
+ docId: string;
385
+ scope: string;
386
+ };
387
+ /** Server to client, notification: replaces the room's lease list. */
388
+ export type LeaseChangedParams = {
389
+ docId: string;
390
+ leases: Lease[];
391
+ };
392
+ /** `save/begin` (protocol 1.10, D3): an editor of a joined room starts a save. */
393
+ export type SaveBeginParams = {
394
+ docId: string;
395
+ trigger: SaveTrigger;
396
+ };
397
+ /** Someone whose changes a save holds. */
398
+ export type SaveAuthor = {
399
+ principalId: string;
400
+ name: string;
401
+ };
402
+ /**
403
+ * The room's state after the call (`force-save` by the caller, or unchanged for a clean room), the
404
+ * change to write, who made the changes since the last version (the server's own log), and the
405
+ * server's signed save receipt of those (I6), which the host verifies and takes the authors from.
406
+ */
407
+ export type SaveBeginResult = {
408
+ save: SaveState;
409
+ seq: number;
410
+ authors: SaveAuthor[];
411
+ receipt: string;
412
+ };
413
+ /** `save/end` (protocol 1.10): the save of `seq` wrote `version`, or failed with `error`. */
414
+ export type SaveEndParams = {
415
+ docId: string;
416
+ seq: number;
417
+ version: string | null;
418
+ error?: SaveFailure;
419
+ };
420
+ /** `save/changed` (server to client, protocol 1.10): after every transition. */
421
+ export type SaveChangedParams = {
422
+ docId: string;
423
+ save: SaveState;
424
+ };
425
+ /** The capability a server lists in `sync/hello` when it runs kits headless (protocol 1.7, section 8a). */
426
+ export declare const HEADLESS_CAPABILITY = "headless";
427
+ /**
428
+ * `preview/get` (protocol 1.7): a picture of the room's document as of its latest change, rendered
429
+ * by the kit on the server. `page` is zero-based, for a kit that pages; `size` the longest side in
430
+ * pixels (the server's default when omitted, and capped).
431
+ */
432
+ export type PreviewGetParams = {
433
+ docId: string;
434
+ page?: number;
435
+ size?: number;
436
+ };
437
+ export type PreviewGetResult = {
438
+ image: Uint8Array;
439
+ mimeType: string;
440
+ width: number;
441
+ height: number;
442
+ seq: number;
443
+ };
444
+ /** `export/get` (protocol 1.7): the room's document as a file in `format` (the kit's native one when omitted). */
445
+ export type ExportGetParams = {
446
+ docId: string;
447
+ format?: string;
448
+ };
449
+ export type ExportGetResult = {
450
+ data: Uint8Array;
451
+ name: string;
452
+ format: string;
453
+ seq: number;
454
+ };
455
+ /**
456
+ * `agent/run` (protocol 1.7): an object-model batch (`{ ops, load? }`) the server runs on the
457
+ * joined room's document in its headless kit, as an agent acting for the caller (an owner or
458
+ * editor); the server sets the origin. What it changed arrives as `changes/pull` like anyone
459
+ * else's change; `seq` is that change's (`null` when the batch changed nothing).
460
+ */
461
+ export type AgentRunParams = {
462
+ docId: string;
463
+ batch: unknown;
464
+ prompt?: string;
465
+ };
466
+ export type AgentRunResult = {
467
+ seq: number | null;
468
+ result: unknown;
469
+ };
470
+ /** A JSON-RPC error; `data.code` is an [[ErrorCode]] for every error this protocol itself defines. */
471
+ export declare class SyncRpcError extends Error {
472
+ readonly code: number;
473
+ readonly data?: unknown | undefined;
474
+ constructor(code: number, message: string, data?: unknown | undefined);
475
+ /**
476
+ * The room a `room/create` refused `conflict` names (protocol 1.10, RM6): an open-token
477
+ * connection's file generation already has that room, which the caller joins instead.
478
+ */
479
+ get boundDocId(): string | undefined;
480
+ /** The limit of people co-editing at once a `collab-limit` error names (`error.data.limit`). */
481
+ get collabLimit(): number | undefined;
482
+ /** This error's [[ErrorCode]], when it carries one. */
483
+ get reason(): ErrorCode | undefined;
484
+ }
@@ -0,0 +1,52 @@
1
+ import type { SyncClient } from './client.js';
2
+ import type { Presence, RoomJoinResult } from './protocol.js';
3
+ import type { ReplicaVersions } from './replicaVersions.js';
4
+ import type { ConnectionState } from './transport.js';
5
+ /** The replica side: a mounted kit's `KitConnection.replica` (`@kition/kit-host`), or a host editor's. */
6
+ export type RelayReplica = {
7
+ version: () => Promise<ArrayBuffer>;
8
+ exportChanges: (since: ArrayBuffer) => Promise<{
9
+ changes: ArrayBuffer;
10
+ blobs: ArrayBuffer;
11
+ }>;
12
+ importChanges: (changes: ArrayBuffer, blobs: ArrayBuffer) => Promise<unknown>;
13
+ onChanged: (listener: (version: ArrayBuffer) => void) => () => void;
14
+ };
15
+ /** The sync side: the page's `SyncClient`. */
16
+ export type RelaySync = Pick<SyncClient, 'join' | 'leave' | 'push' | 'onChanges' | 'onState' | 'blobs'> & Partial<Pick<SyncClient, 'onAccess'>> & {
17
+ readonly state: ConnectionState;
18
+ };
19
+ export type RelayOptions = {
20
+ docId: string;
21
+ replica: RelayReplica;
22
+ sync: RelaySync;
23
+ versions: ReplicaVersions;
24
+ /** What the room is known to hold from this replica already (from an earlier session), if anything. */
25
+ lastSent?: Uint8Array;
26
+ /** The room took a push: `version` is what it now holds from here (to keep for next time). */
27
+ onSent?: (version: Uint8Array) => void;
28
+ /** The server `seq` to join the room from (an earlier session's `onSeen`); absent or `null`: from its snapshot. */
29
+ since?: number | null;
30
+ /** The replica has every change of the room up to `seq`, and is at `version` (to keep for next time). */
31
+ onSeen?: (seen: {
32
+ seq: number;
33
+ version: Uint8Array;
34
+ }) => void;
35
+ /** Joined (or re-joined) the room: its presence and this person's role. */
36
+ onJoined?: (result: {
37
+ presence: Presence[];
38
+ role: RoomJoinResult['role'];
39
+ }) => void;
40
+ /**
41
+ * This person's role changed while joined (protocol 1.6, `room/access`); `null`: they were
42
+ * removed from the room, and the relay stops sending.
43
+ */
44
+ onAccess?: (role: RoomJoinResult['role'] | null) => void;
45
+ onError?: (error: unknown) => void;
46
+ };
47
+ export type Relay = {
48
+ stop: () => void;
49
+ /** Settles once every step queued so far has run (for tests). */
50
+ idle: () => Promise<void>;
51
+ };
52
+ export declare function startRelay(options: RelayOptions): Relay;
@@ -0,0 +1,11 @@
1
+ export type ReplicaVersions = {
2
+ /** Whether `changes` (a KDM change export) carries no change at all. */
3
+ isEmpty: (changes: Uint8Array) => boolean;
4
+ /** The version holding every change of `a` and of `b`. */
5
+ merge: (a: Uint8Array, b: Uint8Array) => Uint8Array;
6
+ /** The version `changes` reaches for each author it carries changes of; `null` if unreadable. */
7
+ endOf: (changes: Uint8Array) => Uint8Array | null;
8
+ /** Whether `version` holds every change `other` holds. */
9
+ includes: (version: Uint8Array, other: Uint8Array) => boolean;
10
+ };
11
+ export declare const LORO_REPLICA_VERSIONS: ReplicaVersions;
@@ -0,0 +1,38 @@
1
+ import { decodeImportBlobMeta as a, VersionVector as s } from "loro-crdt";
2
+ import { openEnvelope as u } from "@kition/kdm";
3
+ function n(e) {
4
+ return e.length ? new Map(s.decode(e).toJSON()) : /* @__PURE__ */ new Map();
5
+ }
6
+ const p = {
7
+ isEmpty: (e) => {
8
+ try {
9
+ return a(u(e).engine, !1).changeNum === 0;
10
+ } catch {
11
+ return !1;
12
+ }
13
+ },
14
+ merge: (e, o) => {
15
+ const r = n(e);
16
+ for (const [t, c] of n(o)) r.set(t, Math.max(c, r.get(t) ?? 0));
17
+ return s.parseJSON(r).encode();
18
+ },
19
+ endOf: (e) => {
20
+ try {
21
+ return a(u(e).engine, !1).partialEndVersionVector.encode();
22
+ } catch {
23
+ return null;
24
+ }
25
+ },
26
+ includes: (e, o) => {
27
+ try {
28
+ const r = n(e);
29
+ for (const [t, c] of n(o)) if ((r.get(t) ?? 0) < c) return !1;
30
+ return !0;
31
+ } catch {
32
+ return !1;
33
+ }
34
+ }
35
+ };
36
+ export {
37
+ p as LORO_REPLICA_VERSIONS
38
+ };
@@ -0,0 +1,83 @@
1
+ /**
2
+ * The save state machine of a co-edited room (managed co-editing,
3
+ * Kition platform docs/platform/managed-collab.md section 3): one state per room, kept by the sync
4
+ * server and broadcast to every connection (`save/changed`), so every editor shows the same saved
5
+ * state and exactly one session saves at a time. `saveTransition` is the whole rule set: Kition
6
+ * Server applies it (the Rust twin is `kition_sync_protocol::save`), `FakeServer` too, and both
7
+ * are held to `crates/kition-sync-protocol/tests/save-transitions.json`.
8
+ */
9
+ /**
10
+ * `editing`: people edit (`dirty` says whether the room is ahead of the last version);
11
+ * `force-save`: one session saves now; `must-save`: the last editor left with unsaved changes,
12
+ * the next editor saves first; `corrupted`: a save was rejected as corrupt, saving stops until a
13
+ * good save; `closed`: everyone left and the room is clean.
14
+ */
15
+ export type SaveStatus = 'editing' | 'force-save' | 'must-save' | 'corrupted' | 'closed';
16
+ /** What started a save: the person (Save), the autosave timer, or a command (an agent, the host, an API). */
17
+ export type SaveTrigger = 'user' | 'timer' | 'command';
18
+ /** Why a save ended without a version. */
19
+ export type SaveFailure = 'conflict' | 'failed' | 'corrupted';
20
+ export type SaveState = {
21
+ status: SaveStatus;
22
+ dirty: boolean;
23
+ /** The room's latest change. */
24
+ headSeq: number;
25
+ /** The change the last version holds. */
26
+ savedSeq: number;
27
+ /** The host's last version. */
28
+ version: string | null;
29
+ /** The running or last save's trigger. */
30
+ trigger: SaveTrigger | null;
31
+ /** The session (connection) running the save now (`force-save`), or that ran the last one; not a person (I5). */
32
+ by: string | null;
33
+ /** The last failure, until a save succeeds. */
34
+ reason: SaveFailure | null;
35
+ /** The change the running save writes (`force-save` only). */
36
+ savingSeq: number | null;
37
+ };
38
+ export type SaveEvent =
39
+ /** A change the room took, from `by`. */
40
+ {
41
+ type: 'change';
42
+ seq: number;
43
+ by: string;
44
+ }
45
+ /** An editor joined the room. */
46
+ | {
47
+ type: 'joined';
48
+ by: string;
49
+ }
50
+ /** `save/begin`. */
51
+ | {
52
+ type: 'begin';
53
+ by: string;
54
+ trigger: SaveTrigger;
55
+ }
56
+ /** `save/end`: `version` on success, else `error`. */
57
+ | {
58
+ type: 'end';
59
+ by: string;
60
+ seq: number;
61
+ version: string | null;
62
+ error?: SaveFailure;
63
+ }
64
+ /** An editor's connection left; `last` when no editor remains. */
65
+ | {
66
+ type: 'left';
67
+ by: string;
68
+ last: boolean;
69
+ };
70
+ /** `refused`: `conflict` (another save runs), `forbidden` (not this session's save), `invalid` (bad `seq`, or no version and no error). */
71
+ export type SaveOutcome = {
72
+ state: SaveState;
73
+ refused?: 'conflict' | 'forbidden' | 'invalid';
74
+ changed: boolean;
75
+ };
76
+ /** The longest host version a save may report (I6). */
77
+ export declare const SAVE_VERSION_LIMIT = 256;
78
+ /** A new room's save state: its creation snapshot is the version it was seeded from. */
79
+ export declare function initialSaveState(version?: string | null): SaveState;
80
+ /** The room's next save state after `event` (section 3); a refused event leaves it as it was. */
81
+ export declare function saveTransition(state: SaveState, event: SaveEvent): SaveOutcome;
82
+ /** Whether a session joining a room in `state` must save before anything else (SV4). */
83
+ export declare function mustSave(state: SaveState): boolean;