@ghostlytools/sdk 1.2.4 → 1.3.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.
Files changed (32) hide show
  1. package/dist/app.js +10 -4
  2. package/dist/app.js.map +1 -1
  3. package/dist/core.js +2 -2
  4. package/dist/{fakes-JOzOFxn3.js → fakes-BlpK1WuW.js} +2 -2
  5. package/dist/{fakes-JOzOFxn3.js.map → fakes-BlpK1WuW.js.map} +1 -1
  6. package/dist/fakes.js +1 -1
  7. package/dist/index.js +2 -2
  8. package/dist/{keet-identity-key-BLli1rE4.js → keet-identity-key-GE5nr3zt.js} +2 -2
  9. package/dist/{keet-identity-key-BLli1rE4.js.map → keet-identity-key-GE5nr3zt.js.map} +1 -1
  10. package/dist/{src-BqHTnRWH.js → src-JQitqFJD.js} +769 -108
  11. package/dist/src-JQitqFJD.js.map +1 -0
  12. package/dist/testing.js +3 -3
  13. package/dist/types/core/src/appBundle.d.ts +28 -0
  14. package/dist/types/core/src/chatFiles.d.ts +41 -1
  15. package/dist/types/core/src/datalink.d.ts +13 -7
  16. package/dist/types/core/src/dhtDelivery.d.ts +5 -0
  17. package/dist/types/core/src/frames.d.ts +5 -0
  18. package/dist/types/core/src/ghostlink.d.ts +56 -3
  19. package/dist/types/core/src/groupCommunity.d.ts +35 -5
  20. package/dist/types/core/src/groupFiles.d.ts +6 -2
  21. package/dist/types/core/src/groupSession.d.ts +38 -5
  22. package/dist/types/core/src/groupSignals.d.ts +2 -0
  23. package/dist/types/core/src/link.d.ts +15 -0
  24. package/dist/types/core/src/miniApp.d.ts +10 -4
  25. package/dist/types/core/src/pairedCapabilities.d.ts +6 -1
  26. package/dist/types/core/src/pkarr.d.ts +6 -0
  27. package/dist/types/core/src/relay.d.ts +38 -4
  28. package/dist/types/core/src/transport.d.ts +5 -0
  29. package/dist/{verify-RjMx7eW6.js → verify-afQj9kHW.js} +2 -2
  30. package/dist/{verify-RjMx7eW6.js.map → verify-afQj9kHW.js.map} +1 -1
  31. package/package.json +1 -1
  32. package/dist/src-BqHTnRWH.js.map +0 -1
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
1
- import { $l as emptyIdentityLedger, Fi as isBitcoinAddress, Hl as IDENTITY_MAX_EVIDENCE, Zl as IdentityExchange, au as newIdentityBinding, nu as identityStatement, oa as decodeBolt11, zb as createIdentity } from "./src-BqHTnRWH.js";
1
+ import { Bi as isBitcoinAddress, Ql as IDENTITY_MAX_EVIDENCE, da as decodeBolt11, ex as createIdentity, fu as identityStatement, hu as newIdentityBinding, lu as emptyIdentityLedger, su as IdentityExchange } from "./src-JQitqFJD.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-RjMx7eW6.js";
4
- import { _ as fakeAddress, a as fakeAccount, b as fakeOnchain, c as fakeKeySign, d as fakeRecord, f as fakeRecordText, g as TEST_PROVIDERS_FLAG, h as FakeOnchainProvider, i as TEST_IDENTITIES_FLAG, l as fakeKeySubject, m as FakeLightningProvider, n as FAKE_ISSUER, o as fakeAccountToken, p as testIdentitiesEnabled, r as FAKE_RECORD_HOST, s as fakeKey, t as FAKE_IDENTITY_PROVIDERS, u as fakeKeyring, v as fakeInvoice, x as testProvidersEnabled, y as fakeLightning } from "./fakes-JOzOFxn3.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-afQj9kHW.js";
4
+ import { _ as fakeAddress, a as fakeAccount, b as fakeOnchain, c as fakeKeySign, d as fakeRecord, f as fakeRecordText, g as TEST_PROVIDERS_FLAG, h as FakeOnchainProvider, i as TEST_IDENTITIES_FLAG, l as fakeKeySubject, m as FakeLightningProvider, n as FAKE_ISSUER, o as fakeAccountToken, p as testIdentitiesEnabled, r as FAKE_RECORD_HOST, s as fakeKey, t as FAKE_IDENTITY_PROVIDERS, u as fakeKeyring, v as fakeInvoice, x as testProvidersEnabled, y as fakeLightning } from "./fakes-BlpK1WuW.js";
5
5
  import { afterEach, describe, expect, it, vi } from "vitest";
6
6
  //#region ../browser/src/engine/paymentAdapters/providers/contractSuite.ts
7
7
  var WAIT = 1e4;
@@ -150,8 +150,36 @@ export type AppBundleReading = {
150
150
  reason: AppBundleRefusal;
151
151
  detail?: string;
152
152
  };
153
+ /**
154
+ * Lets the thread go for one turn: what waits (input, drawing, timers, port messages, IndexedDB answers) runs, then the
155
+ * caller goes on. A message to itself, queued behind the page's other tasks. Never `scheduler.yield()`: in Chromium its
156
+ * continuation outranks every normal task, so a paced read of 4096 revocations held the page's timers, its apps' broker
157
+ * ports and IndexedDB for the whole 1.8 s. Never `setTimeout(0)` but as the last resort: from the fifth nested timer on
158
+ * the browser waits at least 4 ms (HTML's clamp), which made that read take 60% longer than the work, and a hidden tab
159
+ * runs timers once a second.
160
+ */
161
+ export declare function yieldThread(): Promise<void>;
162
+ /**
163
+ * A pause for a loop of short steps: `await pause()` after each step lets the thread go once `sliceMs` of work has
164
+ * run since the last time, and answers at once otherwise.
165
+ */
166
+ export declare function pacer(sliceMs: number): () => Promise<void> | undefined;
167
+ /**
168
+ * SHA-256 of bytes that may be a whole bundle, for a client whose engine shares its page's thread: `sha256` in
169
+ * JavaScript takes about 12 ms per MiB on a desktop CPU, so 16 MiB in one run is a page that draws nothing and takes no
170
+ * input for 200 ms. With `crypto.subtle` the bytes are hashed off the thread; without it (a page not served over
171
+ * HTTPS), a slice at a time with a pause between slices. The bytes must not change until it answers.
172
+ */
173
+ export declare function sha256Paced(bytes: Uint8Array): Promise<Uint8Array>;
153
174
  /** Reads and checks a bundle (the order of the checks is part of the format: see above). */
154
175
  export declare function readAppBundle(bytes: Uint8Array): AppBundleReading;
176
+ /**
177
+ * `readAppBundle` for a client whose engine shares its page's thread: the same checks in the same order, with the same
178
+ * refusals, and each file hashed by `sha256Paced`, one after the other, with the thread let go between files every
179
+ * `HASH_SLICE_MS` (64 files of 64 KiB, each hashed at once, held it for 50 ms). The bytes must not change until it
180
+ * answers.
181
+ */
182
+ export declare function readAppBundleAsync(bytes: Uint8Array): Promise<AppBundleReading>;
155
183
  /** Puts a bundle's parts together, checking nothing: for builders, and for tests that need a broken bundle. */
156
184
  export declare function assembleAppBundle(manifestBytes: Uint8Array, statementBytes: Uint8Array, files: Uint8Array[]): Uint8Array;
157
185
  /** What a publisher writes: every manifest field but `publisher` and `files`, which the bundle's contents decide. */
@@ -28,6 +28,11 @@ export declare const FILE_LIMITS: {
28
28
  readonly chunkBytes: number;
29
29
  /** Bytes a sender has sent and not seen confirmed: throughput is this per round trip. */
30
30
  readonly windowBytes: number;
31
+ /**
32
+ * Bytes all of a chat's files have sent and not seen confirmed, together. Three files' windows at once were 3 MiB, and
33
+ * as base64 text past what a session's receive queue holds (`SESSION_RECEIVE_PENDING`, 3.75 MiB).
34
+ */
35
+ readonly chatWindowBytes: number;
31
36
  /** A receiver asks its person before taking a file larger than this. */
32
37
  readonly askAboveBytes: number;
33
38
  /** Files taken without asking, per contact, while stored. Past it, every file is asked about. */
@@ -134,6 +139,11 @@ export type RefuseReason = "declined" | "no-room" | "too-many" | "damaged" | "ca
134
139
  export interface ChatFilesHost {
135
140
  /** Sends a frame on the open session; false when there is none. */
136
141
  send(frame: Record<string, unknown>): boolean;
142
+ /**
143
+ * Sends a file's bytes at `offset` in the form the open session agreed (WISP 501 § files/4): a binary message, or
144
+ * the `pf-data` frame; false when there is no session or it has no room. A host without it gets `pf-data` through `send`.
145
+ */
146
+ sendData?(id: string, offset: number, data: Uint8Array): boolean;
137
147
  /**
138
148
  * A new offer from the contact: take it, ask the person, or refuse it. `again`: a file taken here without asking
139
149
  * that ended (failed, or stopped by the sender) and is offered again; it counts against the same limits as a new one.
@@ -162,6 +172,21 @@ export interface ChatFilesHost {
162
172
  resend?(record: FileTransferRecord, sent: number): boolean;
163
173
  now?(): number;
164
174
  }
175
+ /**
176
+ * files/4 (WISP 501 § files/4): a chunk as one binary message of the session, in place of the base64url text of a
177
+ * `pf-data` frame, which is a third more than the bytes it carries:
178
+ *
179
+ * kind 0x04 (1) | id length (1) | id (ASCII) | offset (8, big endian) | data (1 to `FILE_LIMITS.chunkBytes`)
180
+ */
181
+ export declare const FILE_DATA_KIND = 4;
182
+ /** The binary message for the bytes of file `id` at `offset`. Throws on what no receiver would take. */
183
+ export declare function encodeFileData(id: string, offset: number, data: Uint8Array): Uint8Array;
184
+ /** What a binary message from the contact says, or null when it is not a well-formed file data message. `data` is a view of `message`. */
185
+ export declare function decodeFileData(message: Uint8Array): {
186
+ id: string;
187
+ offset: number;
188
+ data: Uint8Array;
189
+ } | null;
165
190
  /** What a refusal means to the sender's person. */
166
191
  export declare function refusalText(why: string, room?: number): {
167
192
  state: TransferState;
@@ -170,6 +195,10 @@ export declare function refusalText(why: string, room?: number): {
170
195
  export declare class ChatFiles {
171
196
  private readonly host;
172
197
  private readonly entries;
198
+ /** Files sending that may have bytes not confirmed yet: what `inFlight` adds up (the rest are left out as it goes). */
199
+ private readonly moving;
200
+ /** Files that stopped sending for the chat's window alone: they go on once another's bytes are confirmed. */
201
+ private readonly held;
173
202
  private attached;
174
203
  private peerRoomValue;
175
204
  constructor(host: ChatFilesHost);
@@ -188,6 +217,7 @@ export declare class ChatFiles {
188
217
  private moved;
189
218
  private changed;
190
219
  private send;
220
+ private sendData;
191
221
  /** A session that agreed files/3 is open: say what fits here, then offer again what is not finished. */
192
222
  attach(): void;
193
223
  /** The session went: nothing moves until the next one. What was received is made durable. */
@@ -202,7 +232,13 @@ export declare class ChatFiles {
202
232
  private armStall;
203
233
  private source;
204
234
  private chunkAt;
235
+ /** Whether this file's own window lets it send more. */
236
+ private fileMayPump;
205
237
  private shouldPump;
238
+ /** Bytes this chat's files sent and have not seen confirmed. */
239
+ private inFlight;
240
+ /** Bytes were confirmed, or a file stopped sending: the files the chat's window held go on, before the one that freed it. */
241
+ private wakeHeld;
206
242
  /**
207
243
  * Whether the next `length` bytes go. Within the file's size they always do; past it the receiver is having parts
208
244
  * sent again, which nothing it says bounds, so this side does.
@@ -220,7 +256,11 @@ export declare class ChatFiles {
220
256
  */
221
257
  private discardStored;
222
258
  private target;
223
- /** An accepted file goes when a session is open and fewer than three others arrive at once. */
259
+ /**
260
+ * An accepted file goes when a session is open and fewer than three others arrive at once. One whose target is still
261
+ * being opened counts among the three: counted only once active, every file offered or queued meanwhile went too, and
262
+ * the windows of ten files and more at once overflowed the session's receive queue.
263
+ */
224
264
  private startIncoming;
225
265
  /** The next file waiting its turn, once one ends. */
226
266
  private startNext;
@@ -66,7 +66,9 @@ export declare const CONNECT_TIMEOUT_MS = 90000;
66
66
  * settle); where they do not, every offer of a first pairing waited the full 5 s, twice when the inviter offered too
67
67
  * (One's e2e runs: 13 offers of 89 at 5 s, 9 more at 1.3-3 s, 2026-10-05). An offer without one still connects to most
68
68
  * contacts (their checks learn this side's address from its own); behind a restricted NAT on the contact's side it may
69
- * not, and the next offer of the chat then waits as long as it takes (`fullGather`).
69
+ * not, and the next offer of the chat then waits as long as it takes (`fullGather`). An answer is bounded the same way:
70
+ * it waited the full 5 s, and two CLI daemons whose STUN server swallowed every request went live 10 s after the offer
71
+ * rather than 2 s (calls bug hunt, 2026-10-12).
70
72
  */
71
73
  export declare const OFFER_HOST_GATHER_MS = 2000;
72
74
  /** The data link keeps collecting this long after the candidate it waited for came (a call keeps 400 ms). */
@@ -101,12 +103,13 @@ export declare class DataLink {
101
103
  private pc;
102
104
  private myOfferTs;
103
105
  /**
104
- * An offer of this side's that went without a public candidate came to nothing (it was answered, and no path
105
- * connected): the next one waits for its STUN servers as long as it takes (`ICE_GATHERING_TIMEOUT_MS`).
106
+ * An offer or answer of this side's that went without a public candidate came to nothing (both descriptions were
107
+ * exchanged, and no path connected): the next one waits for its STUN servers as long as it takes
108
+ * (`ICE_GATHERING_TIMEOUT_MS`).
106
109
  */
107
110
  private fullGather;
108
- /** The offer out has no public candidate (as it went: the connection's description gains any that come later). */
109
- private offerLacksPublic;
111
+ /** The offer or answer out has no public candidate (as it went: the connection's description gains any that come later). */
112
+ private sentLacksPublic;
110
113
  private lastSignalTs;
111
114
  /** The peer's description as this connection was given it: Chrome shows it as `remoteDescription` only once applied. */
112
115
  private remoteSdp;
@@ -148,7 +151,10 @@ export declare class DataLink {
148
151
  */
149
152
  get fingerprints(): [string, string] | null;
150
153
  close(): void;
151
- /** This side's offer went with no public candidate, was answered, and came to nothing: the next offer gathers for as long as it takes. */
154
+ /**
155
+ * This side's offer went with no public candidate and was answered, or its answer went with none, and it came to
156
+ * nothing: the next offer or answer gathers for as long as it takes.
157
+ */
152
158
  private noteNoPublic;
153
159
  /**
154
160
  * What this attempt says about direct connections if it ends now without opening: nothing unless both descriptions
@@ -159,7 +165,7 @@ export declare class DataLink {
159
165
  /**
160
166
  * The attempt on this connection failed (it timed out, ICE failed or closed, its channel closed). An answer the
161
167
  * offerer may not have read yet is made again for the same offer while it still stands (`REANSWERS`); anything
162
- * else goes back to idle.
168
+ * else goes back to idle. `byConnection`: the connection said so itself, rather than a timer of this link's.
163
169
  */
164
170
  private failed;
165
171
  /** The answer to this side's offer did not go in (`ANSWER_REFUSED_REDIALS`): the attempt ends, and the caller may offer again now. */
@@ -155,6 +155,7 @@ export declare class DhtDelivery {
155
155
  private fastUntil;
156
156
  private live;
157
157
  private active;
158
+ private readonly startedAt;
158
159
  /** The next read was asked for (a refresh, a fresh packet of the contact): it is not a background one. */
159
160
  private urgent;
160
161
  /** Reads left that are signaling: the contact is leaving DHT only, and the live link waits on them (`expect`). */
@@ -239,6 +240,8 @@ export declare class DhtDelivery {
239
240
  * burst of an app coming back (bug hunt r7a). A text, a receipt, a new mode or a new capability revision still go at once.
240
241
  */
241
242
  firstControlAfterMs?: number;
243
+ /** This side made the invite, then: once no longer awaited, its mailbox is read less often while nobody uses it (`unusedInviteWait`). */
244
+ inviteMadeAt?: number;
242
245
  });
243
246
  get view(): DhtDeliveryView;
244
247
  /**
@@ -385,6 +388,8 @@ export declare class DhtDelivery {
385
388
  private publishOnTick;
386
389
  /** How long until the next read of the contact's mailbox (WISP 403, poll pace). */
387
390
  get pollMs(): number;
391
+ /** How long ago this side's invite was made, while nobody used it and it is no longer awaited (`AWAITING_PEER_MS`). */
392
+ private unusedInviteAge;
388
393
  private schedule;
389
394
  }
390
395
  export declare const DHT_TEXT_REFUSED = "Your contact's app does not accept text over the DHT. It is sent when you are live.";
@@ -202,6 +202,11 @@ export interface FrameChannel {
202
202
  * WebRTC data channel does, and a sender only keeps under `LIMITS.sendHighWaterMark`.
203
203
  */
204
204
  readonly sendBudget?: number;
205
+ /**
206
+ * It carries binary messages as well as text (WISP 100 § Text and binary messages): a WebRTC data channel does.
207
+ * Absent: text only, as the Iroh channels are, and nothing binary is offered or sent on it.
208
+ */
209
+ readonly binary?: boolean;
205
210
  close(): void;
206
211
  onMessage: ((data: string | Uint8Array) => void) | null;
207
212
  onClose: (() => void) | null;
@@ -46,6 +46,14 @@ export declare const CROSSED_WAIT_MS = 500;
46
46
  * takes over.
47
47
  */
48
48
  export declare const CROSSED_FRESH_MS = 10000;
49
+ /**
50
+ * A dial of the contact's that meets such a session waits this long for that session to answer a ping. It answers when
51
+ * the dials crossed (the contact holds this side's dial too); it does not when the contact's app ended since and is
52
+ * back: its dial then takes over. Refused outright, that dial left the contact waiting for the dead session's end, 16.6
53
+ * to 18.9 s (CLI daemons over HyperDHT, the contact killed 1 to 3 s after this side's knock, 5 of 5). A round trip is
54
+ * 7 ms on loopback and under 0.5 s over a relayed Iroh.
55
+ */
56
+ export declare const CROSSED_PROBE_MS = 1500;
49
57
  /** A joiner gathers its offer while it first looks for the inviter (`dialEarly`) only this soon after the join. */
50
58
  export declare const EARLY_DIAL_JOIN_MS = 60000;
51
59
  /** What a joiner is told when someone else used the invite first (`DhtDeliveryView.inviteTaken`). */
@@ -366,7 +374,10 @@ export interface GhostLinkEvents {
366
374
  onFileProgress?(fileId: string, transferred: number, direction: "in" | "out"): void;
367
375
  onFileComplete?(fileId: string, direction: "in" | "out"): void;
368
376
  onFileFailed?(fileId: string, reason: string, direction: "in" | "out"): void;
369
- /** A files/3 frame (`FILE_FRAMES`), only while both sides agreed `files/3` on the open session. */
377
+ /**
378
+ * A files/3 frame (`FILE_FRAMES`), only while both sides agreed `files/3` on the open session. A file's data that came
379
+ * as a binary message (`files/4`) is the `pf-data` frame it stands for, its `data` the bytes themselves.
380
+ */
370
381
  onFilesFrame?(frame: Record<string, unknown>): void | Promise<void>;
371
382
  /**
372
383
  * files/3 can flow (a session agreed it and is open), or no longer can. Said again, open, after a live
@@ -424,6 +435,11 @@ export interface GhostLinkOptions {
424
435
  servicesSupport?: boolean;
425
436
  /** Offer `files/3` on paired sessions: files of any size, offered, resumed and checked (`chatFiles.ts`). */
426
437
  largeFilesSupport?: boolean;
438
+ /**
439
+ * With `largeFilesSupport`, offer `files/4` on a session whose channel carries binary messages: a file's bytes as
440
+ * they are, not as text (WISP 501 § files/4). The owner's `onFilesFrame` then takes a `pf-data` whose `data` is bytes.
441
+ */
442
+ binaryFilesSupport?: boolean;
427
443
  /** Offer `typing/1` on paired sessions: say and show when either side is writing (1:1 chats, not group edges). */
428
444
  typingSupport?: boolean;
429
445
  /** Offer `react/1` on paired sessions: reactions to messages (1:1 chats, not group edges). */
@@ -1121,6 +1137,16 @@ export declare class GhostLink {
1121
1137
  * fast looks for the member's `_tr` end after a few (`PACKET_TRANSPORTS_FAST_ATTEMPTS`).
1122
1138
  */
1123
1139
  private anythingToDial;
1140
+ /**
1141
+ * Neither side can dial the other until something changes, past a first pairing: what the contact runs is known, and
1142
+ * no transport both run has WebRTC on both sides or an endpoint up on both (this side's, and the one its record
1143
+ * describes). A chat that gave its listener up to another (`yieldEndpoint`), or whose contact did, is so. It dials
1144
+ * again when that changes (a listener taken back, `registerEndpoint`; the record describing one, `learnPeerTransports`),
1145
+ * and reads at its own pace meanwhile: looks every 20 s for a dial with nothing to try, and the contact's fast looks
1146
+ * for an offer that could not come, read its key 2.5x to 4x as often as the background pace, for good (bug hunt,
1147
+ * 2026-10-12). A first pairing keeps both: the records are what it is reading for.
1148
+ */
1149
+ private nothingToDialEitherWay;
1124
1150
  private clearRace;
1125
1151
  /**
1126
1152
  * The offer is still unanswered: the transports ranked after WebRTC that are due are dialled now, each once in this
@@ -1295,6 +1321,8 @@ export declare class GhostLink {
1295
1321
  get supportsServices(): boolean;
1296
1322
  /** Both sides offer `files/3` on the open session: files of any size, offered and resumed. */
1297
1323
  get supportsLargeFiles(): boolean;
1324
+ /** Both sides offer `files/4` beside `files/3` on the open session: a file's bytes go as binary messages. */
1325
+ get supportsBinaryFiles(): boolean;
1298
1326
  /** Both sides offer `typing/1` on the open session: typing can be said and shown. */
1299
1327
  get supportsTyping(): boolean;
1300
1328
  /** Both sides offer `react/1` on the open session: reactions can be said and confirmed here. */
@@ -1361,7 +1389,10 @@ export declare class GhostLink {
1361
1389
  closeApp(app: string): void;
1362
1390
  /**
1363
1391
  * One data frame of an app open on both sides, on the live session only. An error when it did not go: nothing is
1364
- * kept to send later.
1392
+ * kept to send later. While the channel already holds a quarter of what it may queue (its send budget, or the high
1393
+ * water mark of a WebRTC channel), the frame is refused with `too-fast`, so the chat's messages and pings never wait
1394
+ * behind an app's data on a link slower than it sends (WISP 1200 § In a chat). While a file goes, that quarter sits
1395
+ * above what files may hold (`filesWritable`): files keep the channel at their own line for the whole transfer.
1365
1396
  */
1366
1397
  sendAppData(app: string, data: unknown): AppSendError | null;
1367
1398
  /** What the contact had open is gone (`apps/1` is no longer agreed, or this link stopped): each app hears it now. */
@@ -1378,10 +1409,20 @@ export declare class GhostLink {
1378
1409
  private emitFilesSession;
1379
1410
  /** A files/3 frame to the contact, on the open session. False when files/3 cannot flow now. */
1380
1411
  sendFilesFrame(frame: Record<string, unknown>): boolean;
1412
+ /**
1413
+ * A file's bytes to the contact, on the open session: one binary message while both sides agreed `files/4` on it,
1414
+ * the `pf-data` frame with them as base64url text otherwise (WISP 501 § files/4). The form is chosen for each chunk,
1415
+ * so a transfer follows the session it is on. False when files/3 cannot flow now, or the channel has no room.
1416
+ */
1417
+ sendFileData(id: string, offset: number, data: Uint8Array): boolean;
1418
+ /** Files on a channel: when they last wrote on it, and how many wait for room. An app's data gets room above theirs. */
1419
+ private filesUse;
1420
+ private filesUsing;
1381
1421
  /**
1382
1422
  * Resolves once the open session can take another files/3 data frame; undefined when it can now. A channel with a send budget (native and
1383
1423
  * iroh ones throw past 120 KiB) gives files a quarter of it, so a ping, a message or any other frame still fits
1384
- * while a file goes; others keep under the high water mark, as files/2 does.
1424
+ * while a file goes; others keep under the high water mark, as files/2 does. An app's data gets a quarter above that
1425
+ * line meanwhile (`sendAppData`).
1385
1426
  */
1386
1427
  filesWritable(): Promise<void> | undefined;
1387
1428
  /** What each side offers on the open session, for showing why something is unavailable. `peer` is null until it says. */
@@ -1435,6 +1476,18 @@ export declare class GhostLink {
1435
1476
  * Before the pin a held session keeps the chat, as it always did.
1436
1477
  */
1437
1478
  private attachReplacement;
1479
+ private replaceWith;
1480
+ /**
1481
+ * The contact dialled in while this side's own fresh dial holds the chat (`CROSSED_FRESH_MS`): the dials crossed, or
1482
+ * the contact's app ended since that dial and is back. The held session is pinged; heard from within
1483
+ * `CROSSED_PROBE_MS`, the contact holds this side's dial too and its own closes. Not heard from, the contact's dial
1484
+ * takes over.
1485
+ */
1486
+ private crossedProbe;
1487
+ /** Frames heard on the open session, counted from its start: whether the contact answered `probeCrossed`. */
1488
+ private framesHeard;
1489
+ private probeCrossed;
1490
+ private dropCrossedProbe;
1438
1491
  /**
1439
1492
  * Connections that came in on this side's native endpoints. Their address was in the capability record, which before
1440
1493
  * the pin anyone holding a copy of the invite could read: a key other than the pinned one on such a connection proves
@@ -59,6 +59,8 @@ export declare const COMMUNITY_LIMITS: {
59
59
  /** Commits in one welcome or chain piece. */
60
60
  readonly chainPiece: 100;
61
61
  readonly pendingLeaves: 64;
62
+ /** Leaves whose mark (`group-left`) is kept, and the epochs one names. */
63
+ readonly leftMarks: 64;
62
64
  /**
63
65
  * Syncs of one member answered in `syncWindowMs`: each answer may carry the chain's tail, secrets and the whole
64
66
  * store. A member catching up asks every five seconds at most, and every member syncs every thirty; one asking more
@@ -116,6 +118,8 @@ export declare function rosterHash(roster: Roster): string;
116
118
  /** The id of a community group: from its creator and a nonce, so no other genesis can claim it. */
117
119
  export declare function communityGroupId(creator: string, nonce: string): string;
118
120
  export declare const leaveStatement: (g: string, s: string) => Uint8Array<ArrayBufferLike>;
121
+ /** What the member who committed a leave (`h`) had heard of the leaver then: `e:h16` → its highest number there. */
122
+ export declare const leftStatement: (g: string, h: string, hi: Record<string, number>) => Uint8Array<ArrayBufferLike>;
119
123
  /** The secret of an epoch that adds, re-roles or re-links: from the previous one and the commit. */
120
124
  export declare function derivedSecret(previous: Uint8Array, untaggedHash: string): Uint8Array;
121
125
  /**
@@ -199,6 +203,18 @@ export interface CommunityLeaveFrame {
199
203
  s: string;
200
204
  ls: string;
201
205
  }
206
+ /**
207
+ * The mark of a leave (`h`, the commit's full hash), signed by the member who committed it: how far it had heard the
208
+ * leaver in each epoch. What the leaver wrote past it is not taken (WISP 903 § Leaving and removal).
209
+ */
210
+ export interface CommunityLeftFrame {
211
+ t: "group-left";
212
+ v: 2;
213
+ g: string;
214
+ h: string;
215
+ hi: Record<string, number>;
216
+ sig: string;
217
+ }
202
218
  /** The seed of the link's current entry key, sealed to one member: after a `link` commit, or at a sync. */
203
219
  export interface CommunityEntryFrame {
204
220
  t: "group-entry";
@@ -236,7 +252,7 @@ export interface CommunityWelcomeFrame {
236
252
  rv: SealedSecret;
237
253
  entry: SealedSecret;
238
254
  }
239
- export type CommunityFrame = CommunityMessageFrame | CommunityCommitFrame | CommunitySecretFrame | CommunitySecretsFrame | CommunitySyncFrame | CommunityLeaveFrame | CommunityEntryFrame | GroupMetaFrame;
255
+ export type CommunityFrame = CommunityMessageFrame | CommunityCommitFrame | CommunitySecretFrame | CommunitySecretsFrame | CommunitySyncFrame | CommunityLeaveFrame | CommunityLeftFrame | CommunityEntryFrame | GroupMetaFrame;
240
256
  export type CommunityStatus = "active" | "left" | "removed" | "forked" | "lost";
241
257
  export interface CommunityState {
242
258
  id: string;
@@ -286,6 +302,11 @@ export interface CommunityState {
286
302
  s: string;
287
303
  ls: string;
288
304
  }[];
305
+ /** Leave commit (full hash) → its mark, as its committer signed it (`group-left`), oldest first. Absent in older states. */
306
+ left?: Record<string, {
307
+ hi: Record<string, number>;
308
+ sig: string;
309
+ }>;
289
310
  /** The group's metadata (its picture), as the admin last signed it and I accepted it. */
290
311
  meta?: GroupMeta;
291
312
  }
@@ -468,11 +489,18 @@ export declare class CommunitySession {
468
489
  outAt(key: string): number | undefined;
469
490
  private outIndex;
470
491
  /**
471
- * Someone the chain removed (not one who left) and who is not back in: nothing it signs is heard any more, even for
472
- * an epoch it was in. What one who left wrote while in the group is still taken and handed on, for the epochs it was
473
- * in (WISP 903 § Leaving and removal): its goodbye reaches the members who were away.
492
+ * Whether a frame of someone the chain took out is still heard. A member removed is heard no more, even for an epoch
493
+ * it was in. What one who left wrote while in the group is taken and handed on, its goodbye included, up to what the
494
+ * member who committed the leave had heard of it then (its `group-left` mark), never past it: the leaver still holds
495
+ * those epochs' secrets, and anything it signs later is not heard (WISP 903 § Leaving and removal). No mark here
496
+ * (one not come yet, or a committer's app before it) and nothing of it is heard.
474
497
  */
475
- private wasExpelled;
498
+ private heardAfterOut;
499
+ /** The mark of a leave on my branch, as a frame to hand on (see `heardAfterOut`). */
500
+ private leftFrame;
501
+ private keepLeft;
502
+ /** A leave's mark, from the member who committed it: kept when it is that member's, for a leave I hold. */
503
+ private receiveLeft;
476
504
  /**
477
505
  * What someone the chain took out is told when it comes back (WISP 903 § Leaving and removal): the commits from where
478
506
  * it says it is (`sync`: its tip, or its locator) up to the one that took it out, and nothing after. Later commits
@@ -577,6 +605,8 @@ export declare class CommunitySession {
577
605
  leave(): Promise<CommunityLeaveFrame | null>;
578
606
  /** Commits the leave requests I hold whose members are still in: the engine calls this on hubs. */
579
607
  commitPendingLeaves(now?: number): Promise<number>;
608
+ /** Signs and says how far I had heard a member whose leave I just committed (`group-left`). */
609
+ private markLeft;
580
610
  private out;
581
611
  /**
582
612
  * `mentions`: places of the text that name members, sealed with it (`m`). Never everyone in a community. They
@@ -31,8 +31,12 @@ export declare const GROUP_FILE_LIMITS: {
31
31
  readonly heardAhead: 256;
32
32
  /** Message ids in one `group-have`. */
33
33
  readonly haveIds: 32;
34
- /** A private group's `group-have` goes on an edge at most this often; a community's, from a member, every `communityHaveEveryMs`. */
35
- readonly haveEveryMs: 10000;
34
+ /**
35
+ * `group-have` frames a private group's edge takes in `haveWindowMs`: what is to say is gathered for a second, then
36
+ * goes. A community's, from a member, goes every `communityHaveEveryMs`.
37
+ */
38
+ readonly haveFrames: 10;
39
+ readonly haveWindowMs: 10000;
36
40
  readonly communityHaveEveryMs: 60000;
37
41
  /**
38
42
  * How long a want waits for an offer before the next holder is asked; a transfer that does not move for as long is
@@ -248,7 +248,11 @@ export interface GroupState {
248
248
  seqEpoch: number;
249
249
  /** My own frames, newest last, for members who missed them. */
250
250
  sent: GroupMessageFrame[];
251
- /** Other members' frames, in the order they arrived, for members who missed them. Absent in states from before revision 0.9. */
251
+ /**
252
+ * Other members' frames, in the order they arrived, for members who missed them. Absent in states from before revision
253
+ * 0.9. With an app that keeps each frame with its message (`GroupSession`'s `onRows`), only the ones from before it
254
+ * did, until newer ones take their place.
255
+ */
252
256
  relay?: GroupMessageFrame[];
253
257
  /** Other members' edits, the latest per message, for members who missed them. Absent in states from before edits were handed on. */
254
258
  relayEdits?: GroupEditFrame[];
@@ -303,6 +307,12 @@ export interface GroupSessionHooks {
303
307
  send(to: string, frame: GroupEdgeFrame): boolean | void;
304
308
  /** Store before it resolves: replay state advances only afterwards. */
305
309
  message(message: GroupIncomingMessage): Promise<void> | void;
310
+ /**
311
+ * A frame kept to hand on that came with no message of its own: message `id`, stored before, said again by its author
312
+ * under a later epoch (WISP 902 § Catch-up, "Frames said again"). An app that keeps the frames with its messages puts
313
+ * this one in the place of that message's.
314
+ */
315
+ kept?(id: string, frame: GroupMessageFrame): Promise<void> | void;
306
316
  /** An edit of a member's message, authenticated as its author (WISP 902 § Edits). Apps without edits leave it out. */
307
317
  edit?(edit: GroupIncomingEdit): Promise<void> | void;
308
318
  /** Roster, epoch or status changed. */
@@ -360,7 +370,6 @@ export interface GroupPinFrame extends WirePin {
360
370
  k: string;
361
371
  sig: string;
362
372
  }
363
- /** What a frame weighs in a log, roughly: its boxes plus the fixed fields around them. */
364
373
  /** What a kept frame counts for against `GROUP_LIMITS.relayBytes`. */
365
374
  export declare const frameBytes: (f: GroupMessageFrame) => number;
366
375
  /**
@@ -391,8 +400,15 @@ export declare class GroupSession {
391
400
  private pendingMeta;
392
401
  /** While `handle` runs: the frames it took that a hub passes on (`handle`'s result). */
393
402
  private passOn;
403
+ /** The frames kept to hand on that the app holds with its messages, oldest first; undefined when the state holds them all. */
404
+ private onRows;
394
405
  /** Set while a save of what received messages changed is due (`persistSoon`). */
395
406
  private saveTimer;
407
+ /**
408
+ * The frames of members who left that each member was handed (`frameKey`), so an app that does not take them (from
409
+ * before revision 2026-10-13, and never marks them seen) is not handed them again at every sync. In memory only.
410
+ */
411
+ private leaversHanded;
396
412
  /** Syncs answered per member, a few a minute (`GROUP_LIMITS.syncAnswers`). In memory only. */
397
413
  private syncsAnswered;
398
414
  /** Catch-up answers still going out, a slice at a time (`handOut`). */
@@ -405,7 +421,12 @@ export declare class GroupSession {
405
421
  private provisional;
406
422
  /** When my chain last moved (a commit made or applied), by `hooks.clock`: frames are said again once it has settled. */
407
423
  private chainMovedAt;
408
- constructor(state: GroupState, hooks: GroupSessionHooks);
424
+ /**
425
+ * `onRows`: the frames the app holds with the messages it stored (`GroupIncomingMessage.frame`), oldest first. Given
426
+ * (empty at first), the app is where frames are kept: the saved state carries none of them, and a message received
427
+ * no longer writes them all again. Absent: they are kept in the state, as before.
428
+ */
429
+ constructor(state: GroupState, hooks: GroupSessionHooks, onRows?: GroupMessageFrame[]);
409
430
  private clock;
410
431
  /** A new group: its genesis commit, signed by the creator, who is its admin. */
411
432
  static create(name: string, now?: number): GroupState;
@@ -508,12 +529,18 @@ export declare class GroupSession {
508
529
  /** A fresh secret without a membership change: whoever holds the old one and is not a member learns nothing new. */
509
530
  rotate(now?: number): Promise<void>;
510
531
  private commit;
511
- /** Someone out of the roster is not handed on any more, whatever they sent while in it (WISP 902 § Catch-up). */
532
+ /**
533
+ * Someone removed is not handed on any more, whatever they sent while in the roster; one who left still is, for the
534
+ * epochs before its leave (WISP 902 § Catch-up).
535
+ */
512
536
  private pruneRelay;
513
537
  /** Another member's edit, kept to hand on: the latest per message; the oldest go once the log is full. False: one as new was kept. */
514
538
  private keepEdit;
515
539
  /** A frame of another member, kept to hand on; the oldest go once the log is full. */
516
540
  private keep;
541
+ /** The frames kept to hand on, oldest first: the state's, then the ones the app holds with its messages. */
542
+ private kept;
543
+ private trimRelay;
517
544
  private pruneSecrets;
518
545
  /** Leaves: my secrets go now; the admin removes me from the roster when it hears. */
519
546
  leave(): Promise<void>;
@@ -652,7 +679,8 @@ export declare class GroupSession {
652
679
  private commitUnlessTurnUnconfirmed;
653
680
  /**
654
681
  * A message, from its author's edge or handed on by another member. Handed on, it is taken only while both are in
655
- * the roster (someone removed is neither heard from nor handed on, #300), and its boxes only with the author's `xs`.
682
+ * the roster (someone removed is neither heard from nor handed on, #300), or from a member in it when its author left
683
+ * after it (`handsOn`), and its boxes only with the author's `xs`.
656
684
  */
657
685
  private receiveMessage;
658
686
  /**
@@ -678,6 +706,11 @@ export declare class GroupSession {
678
706
  private ask;
679
707
  private replayWaiting;
680
708
  private receiveCommit;
709
+ /**
710
+ * Whether a frame of `author` under `epoch` is taken from another member, kept and handed on: while its author is in
711
+ * the roster, or when it left (its removal marked `left`, and it is not back in) and the frame is from before that.
712
+ */
713
+ private handsOn;
681
714
  /** Keeps the admin's mark on a commit that took out a member who left (`GroupCommitFrame.left`) when it holds; true when new. */
682
715
  private takeLeftMark;
683
716
  private apply;
@@ -98,6 +98,8 @@ export declare class CarriedTransport implements PkarrTransport {
98
98
  /** My last packet while the edge is down: what a member that just became reachable is handed. */
99
99
  private mine;
100
100
  private lastTimestamp;
101
+ /** The date each packet `stamp` signed carries: the relays' transport takes it rather than check the signature again. */
102
+ private readonly dated;
101
103
  /** My newest packet, wherever it went: what the edge hands the member over itself once it is ready (`linkReady`). */
102
104
  private newest;
103
105
  /** The newest packet of the member's that came through a carrier, and the timestamp of the one a read last returned. */
@@ -67,6 +67,15 @@ export declare const STALLED_LOOK_MS = 15000;
67
67
  export declare const DEPARTED_READ_MS = 30000;
68
68
  /** A chat whose contact was never seen (an invite just sent) keeps looking at the active pace this long. */
69
69
  export declare const AWAITING_PEER_MS: number;
70
+ /**
71
+ * An invite this side made that nobody used, once no longer awaited (`AWAITING_PEER_MS`), is read less often the older
72
+ * it is: a fifth of its age between reads, up to this. Read at the background pace instead, 15 unused invites (their
73
+ * keys and their mailboxes) asked the relays for 60 reads a minute for as long as the app ran: the relays' minute went
74
+ * to invites nobody may ever open, and a join on one was noticed 90 s later (bug hunt 1013-1642, 2026-10-13).
75
+ */
76
+ export declare const UNUSED_INVITE_WAIT_MAX_MS: number;
77
+ /** The wait between reads of an unused invite of age `age` (`UNUSED_INVITE_WAIT_MAX_MS`), never shorter than the pace's `interval`. */
78
+ export declare function unusedInviteWait(age: number, interval: number): number;
70
79
  /**
71
80
  * A group link's peer whose packet advertises and carries no `_tr` on every read for this long publishes none: what it
72
81
  * said before is forgotten (WISP 902 § Transports). Not at the first such packet: an app with no WebRTC (a Linux
@@ -169,6 +178,8 @@ export interface LinkSessionOptions {
169
178
  * sent at once) went out for a minute (2026-10-08).
170
179
  */
171
180
  awaitingSince?: number;
181
+ /** Whether this is an invite this side made that nobody used yet: once no longer awaited, read less often (`unusedInviteWait`). */
182
+ invite?: () => boolean;
172
183
  }
173
184
  /** With `firstPublish: "after-first-poll"`, the first packet goes out by then whatever happened. */
174
185
  export declare const FIRST_PUBLISH_MAX_MS = 2000;
@@ -213,6 +224,8 @@ export declare class LinkSession {
213
224
  private readonly startedAt;
214
225
  /** From when a peer never seen is awaited (`AWAITING_PEER_MS`): never later than this start, whatever the clock said when the chat was made. */
215
226
  private readonly awaitingSince;
227
+ /** This side's invite, nobody used yet (`LinkSessionOptions.invite`). */
228
+ private readonly invite;
216
229
  private readonly intervals;
217
230
  private fastPollUntil;
218
231
  /** An offer to a saved contact is out: from then on its fast window looks less often (`OFFER_FAST_MS`); 0 for none. */
@@ -337,6 +350,8 @@ export declare class LinkSession {
337
350
  * the one that comes back.
338
351
  */
339
352
  private watching;
353
+ /** A contact never seen, whose invite was sent lately (`AWAITING_PEER_MS`): its join is due. */
354
+ private awaitingPeer;
340
355
  /** How urgently this link looks right now. */
341
356
  private pace;
342
357
  private scheduleHeartbeat;