@ghostlytools/sdk 1.9.0 → 1.10.1

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 (37) hide show
  1. package/dist/core.js +2 -2
  2. package/dist/{fakes-Bx53XiDM.js → fakes-83bCOBaf.js} +2 -2
  3. package/dist/{fakes-Bx53XiDM.js.map → fakes-83bCOBaf.js.map} +1 -1
  4. package/dist/fakes.js +1 -1
  5. package/dist/index.js +2 -2
  6. package/dist/{keet-identity-key-D8ioYMkd.js → keet-identity-key-DyvuvnRO.js} +2 -2
  7. package/dist/{keet-identity-key-D8ioYMkd.js.map → keet-identity-key-DyvuvnRO.js.map} +1 -1
  8. package/dist/{src-Ch4NWeBg.js → src-CEgQHzFr.js} +3094 -1885
  9. package/dist/src-CEgQHzFr.js.map +1 -0
  10. package/dist/testing.js +3 -3
  11. package/dist/types/core/src/appStatements.d.ts +7 -0
  12. package/dist/types/core/src/callSignal.d.ts +10 -0
  13. package/dist/types/core/src/communityRendezvous.d.ts +5 -1
  14. package/dist/types/core/src/contactRecords.d.ts +31 -0
  15. package/dist/types/core/src/engineErrors.d.ts +1 -0
  16. package/dist/types/core/src/ghostlink.d.ts +40 -2
  17. package/dist/types/core/src/groupCommunity.d.ts +117 -11
  18. package/dist/types/core/src/groupFiles.d.ts +15 -0
  19. package/dist/types/core/src/groupMeta.d.ts +3 -2
  20. package/dist/types/core/src/groupSession.d.ts +142 -14
  21. package/dist/types/core/src/http.d.ts +13 -0
  22. package/dist/types/core/src/identityProofs.d.ts +7 -3
  23. package/dist/types/core/src/link.d.ts +16 -2
  24. package/dist/types/core/src/pairedAppRanges.d.ts +17 -9
  25. package/dist/types/core/src/pairedEdits.d.ts +4 -1
  26. package/dist/types/core/src/pairedTransports.d.ts +8 -0
  27. package/dist/types/core/src/pairedWake.d.ts +2 -1
  28. package/dist/types/core/src/storeForward.d.ts +2 -1
  29. package/dist/types/core/src/text.d.ts +9 -0
  30. package/dist/types/core/src/turnRecord.d.ts +2 -2
  31. package/dist/types/core/src/videoMetadata.d.ts +17 -0
  32. package/dist/types/core/src/webPush.d.ts +15 -6
  33. package/dist/{verify-Bi_Y5oat.js → verify-BWOWTWmV.js} +3 -3
  34. package/dist/verify-BWOWTWmV.js.map +1 -0
  35. package/package.json +1 -1
  36. package/dist/src-Ch4NWeBg.js.map +0 -1
  37. package/dist/verify-Bi_Y5oat.js.map +0 -1
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
1
- import { Yu as IDENTITY_MAX_EVIDENCE, ad as IdentityExchange, dw as createIdentity, ia as isBitcoinAddress, ka as decodeBolt11, pd as newIdentityBinding, sd as emptyIdentityLedger, ud as identityStatement } from "./src-Ch4NWeBg.js";
1
+ import { Au as IdentityExchange, Cw as createIdentity, Fu as identityStatement, Mu as emptyIdentityLedger, Ru as newIdentityBinding, bu as IDENTITY_MAX_EVIDENCE, ia as isBitcoinAddress, ka as decodeBolt11 } from "./src-CEgQHzFr.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-Bi_Y5oat.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-Bx53XiDM.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-BWOWTWmV.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-83bCOBaf.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;
@@ -100,6 +100,13 @@ export interface SignedAppRevocation {
100
100
  signature: AppSignature;
101
101
  }
102
102
  export type AppRevocationRefusal = "bad-revocation" | AppSignatureRefusal;
103
+ /**
104
+ * One line of an app's text, from `min` to `max` code points: a title, a tagline, a store's name, a removal's or a
105
+ * revocation's reason. It is shown alone (a heading, a window title), so it holds no control character and none of
106
+ * what `stripHidden` takes from a nickname (invisible and direction-changing characters, line and paragraph
107
+ * separators), and when it is not empty it shows something (`hasVisible`). The joiners an emoji or a script needs stay.
108
+ */
109
+ export declare const isAppLine: (v: unknown, max: number, min?: number) => v is string;
103
110
  /** Checks a revocation statement's shape; the reason it is refused, or null. */
104
111
  export declare function checkAppRevokeStatement(value: unknown): string | null;
105
112
  /** Signs a revocation with the publisher's key. */
@@ -170,6 +170,16 @@ export declare function extractParamsFromSdp(sdp: string, { maxCandidates, loopb
170
170
  }): Partial<CallSignal>;
171
171
  /** Offers, answers and hang-ups older (or further in the future) than this are ignored. */
172
172
  export declare const CALL_SIGNAL_MAX_AGE_MS = 120000;
173
+ /**
174
+ * A call that comes this soon after the contact's last missed one does not ring, when that one barely rang
175
+ * (`BURST_RING_MS`): a bot looping call and hang-up does that (1,375 calls a minute), no person does. It is kept as a
176
+ * missed call, and the wait starts over with it, so a burst rings once and a call placed after a pause rings again.
177
+ * A person's call that rang a while, then was cancelled or rang out, holds nothing back: calling again at once (voice to
178
+ * video, a slip of the finger) rings. The apps (`useWebRTC`) and the headless CLI's call manager both keep it.
179
+ */
180
+ export declare const QUICK_REDIAL_MS = 2000;
181
+ /** A missed call that rang shorter than this was not a person's (`QUICK_REDIAL_MS`). */
182
+ export declare const BURST_RING_MS = 1000;
173
183
  /**
174
184
  * A signal dated further ahead of this clock than this is not taken, however it was heard. A receiver acts on a signal
175
185
  * only when its `ts` is later than the last one it acted on: taken, a signal dated a day ahead would be that last one,
@@ -103,8 +103,12 @@ export declare function readLobby(keys: {
103
103
  /**
104
104
  * The beacon to publish: my entry (or none, `mine` null, when I step down) with the other fresh
105
105
  * hubs, newest first, at most `maxHubs`. A hub not in the roster any more is dropped.
106
+ *
107
+ * Anyone holding the rendezvous secret writes this record, so what is in it does not decide what stays: my entry always
108
+ * does, then the keys I know as members (`known`) before keys I do not, and an entry dated ahead of now ranks as one of
109
+ * now. Entries stay as their hubs dated them.
106
110
  */
107
- export declare function mergeBeacon(existing: Hub[], me: string, mine: Hub | null, now?: number, isMember?: (key: string) => boolean): Hub[];
111
+ export declare function mergeBeacon(existing: Hub[], me: string, mine: Hub | null, now?: number, isMember?: (key: string) => boolean, known?: (key: string) => boolean): Hub[];
108
112
  /** The lobby to publish: my request refreshed, others' still fresh, newest last. */
109
113
  export declare function mergeLobby(existing: LobbyEntry[], mine: LobbyEntry, now?: number): LobbyEntry[];
110
114
  /** Fresh hubs of a beacon, as a member sees them. */
@@ -85,3 +85,34 @@ export declare function requestRecords(askerSeedB64: string, linkKeyZ32: string,
85
85
  * open, does not hold, or has expired by `now`. That the packet is signed by the asker key is the resolver's check.
86
86
  */
87
87
  export declare function openRequest(linkSeedB64: string, askerZ32: string, records: GhostRecord[], now: number): ContactRequest | null;
88
+ /**
89
+ * The asker's proof (WISP 8xx § Accept): in the chat a request started, the requester's app says on the live session
90
+ * that it holds the asker key the request came under. The invite a request carries is a bearer code, so whoever made
91
+ * the chat the owner joined may be someone other than the asker; until this proof comes, the request's text shows as
92
+ * not confirmed. Signed by *K* over the link key, *K*, and both sides' participation keys in that chat: the joiner's is
93
+ * new with the join, so a proof is made in the chat and for it, never before.
94
+ */
95
+ export declare const CONTACT_ASKER_FRAME = "contact-asker";
96
+ export interface ContactAskerFrame {
97
+ t: typeof CONTACT_ASKER_FRAME;
98
+ /** The link key and the asker key, z-base-32. */
99
+ l: string;
100
+ k: string;
101
+ /** Ed25519 by *K*, base64url. */
102
+ s: string;
103
+ }
104
+ /** Whose chat is whose: the inviter is the asker (it made the invite), the joiner the owner. */
105
+ export interface ContactAskerChat {
106
+ inviter: string;
107
+ joiner: string;
108
+ }
109
+ /** The requester's proof for the chat its request started. */
110
+ export declare function contactAskerFrame(askerSeedB64: string, linkKeyZ32: string, chat: ContactAskerChat): ContactAskerFrame;
111
+ /**
112
+ * Whether a proof heard in a chat is the one the owner waits for there: the link and asker keys of the request it
113
+ * accepted, signed by that asker key for this chat's two participation keys. Anything else proves nothing.
114
+ */
115
+ export declare function contactAskerHolds(frame: unknown, expected: {
116
+ link: string;
117
+ key: string;
118
+ }, chat: ContactAskerChat): boolean;
@@ -71,6 +71,7 @@ export declare const ENGINE_ERRORS: {
71
71
  readonly fedimintAlreadyJoined: "You already joined this federation";
72
72
  readonly fedimintConnecting: "Wait for the federation to connect";
73
73
  readonly fedimintNotEnough: "Not enough in this federation";
74
+ readonly fedimintRedeemUnheard: "Could not hear from the federation about these notes: if they don't show in your balance soon, paste them again";
74
75
  readonly fedimintRealOnTestnet: "This federation holds real bitcoin: it belongs in a Mainnet Fedimint wallet";
75
76
  readonly fedimintTestOnMainnet: "This federation is on {chain}, a test network: it belongs in a Testnet Fedimint wallet";
76
77
  readonly walletAway: "{wallet} can't be used here. Use it on {device}.";
@@ -3,7 +3,7 @@ import { type DeliveryMode, type DhtDeliveryState, type DhtDeliveryView, type Dh
3
3
  import type { DhtFileAnnouncement, DhtFileOffer } from "./dhtFiles.js";
4
4
  import { type ProofAdapter, type ProofScope } from "./peerProofs.js";
5
5
  import { type IdentityScope } from "./identityProofs.js";
6
- import { type NativeEndpoint, type PairedTransport, type TransportDescriptors } from "./pairedTransports.js";
6
+ import { type NativeEndpoint, type NativeTransport, type PairedTransport, type TransportDescriptors } from "./pairedTransports.js";
7
7
  import { type LinkPreview } from "./linkPreview.js";
8
8
  import { type WireReply } from "./replies.js";
9
9
  import { type StatusCard } from "./statusCards.js";
@@ -22,6 +22,7 @@ import { type SessionCapability } from "./pairedCapabilities.js";
22
22
  import { type AppFrameEvent, type AppSendError } from "./pairedApps.js";
23
23
  import { type AppRangeTask } from "./pairedAppRanges.js";
24
24
  import { type WakeTarget } from "./pairedWake.js";
25
+ import { type ContactAskerFrame } from "./contactRecords.js";
25
26
  import { type WireReaction } from "./reactions.js";
26
27
  import { type WirePin } from "./pins.js";
27
28
  import { type TypingActivity } from "./pairedTyping.js";
@@ -367,6 +368,14 @@ export interface GhostLinkEvents {
367
368
  onPeerWake?(target: WakeTarget | null): void;
368
369
  /** Both sides offer `wake/1` on the open session (true), or no longer (false): the moment to share this side's. */
369
370
  onWakeSupport?(supported: boolean): void;
371
+ /**
372
+ * The contact said it holds the asker key of the contact request that started this chat (WISP 8xx § Accept), not
373
+ * checked yet: only the caller knows which key it waits for. With this chat's two participation keys.
374
+ */
375
+ onContactAsker?(frame: unknown, keys: {
376
+ mine: string;
377
+ peer: string;
378
+ }): void;
370
379
  /**
371
380
  * The contact's app opened, closed or sent data in one of this chat's mini-apps (`apps/1`, WISP 1200 § In a chat),
372
381
  * already checked against the receiver's limits; or, as a `close` with `offline`, the session ended while it had one
@@ -580,6 +589,8 @@ export interface GhostLinkOptions {
580
589
  avatar?: string;
581
590
  lastSeenTimestamp?: number;
582
591
  pollIntervals?: PollIntervals;
592
+ /** A contact that left a live session is read no slower than the idle pace this long (a CLI daemon's, `DAEMON_WATCH_PEER_IDLE_MS`). */
593
+ watchPeerIdleMs?: number;
583
594
  /**
584
595
  * The transport this chat was live on when the app last ran (it quit, or crashed, with the session up). The contact is
585
596
  * probably still there, holding a session that is dead now: that transport is dialled first, and a native one is
@@ -742,6 +753,8 @@ export declare class GhostLink {
742
753
  /** Edit frames the contact may send per window; the rest go unconfirmed and come again. */
743
754
  private readonly editsReceived;
744
755
  private readonly wakeReceived;
756
+ /** Said once a session by the requester's app: a few a minute at most. */
757
+ private readonly askerReceived;
745
758
  /**
746
759
  * The contact's name and picture, its word on held items, its ways of paying and its transport descriptors, each saved
747
760
  * on this side when it changes: said once a session and when changed, so a handful a minute each. Past that only the
@@ -1002,6 +1015,12 @@ export declare class GhostLink {
1002
1015
  stop(announce?: boolean): Promise<void>;
1003
1016
  /** Opens the data link if needed and resolves once it is usable. */
1004
1017
  connect(timeoutMs?: number): Promise<void>;
1018
+ /**
1019
+ * `connect` for what only needs the link (a request, a file, a payment step): on a live session it does nothing, where
1020
+ * `connect` is a retry that says this side's transport policy again, and the contact reads 10 a minute
1021
+ * (POLICY_RECEIVE_LIMIT). A shared app's every file, each file sent and each payment step used to spend one.
1022
+ */
1023
+ private open;
1005
1024
  /** Closes what a switch replaced once the contact has had time to move too. */
1006
1025
  private retire;
1007
1026
  /**
@@ -1130,6 +1149,12 @@ export declare class GhostLink {
1130
1149
  * simply be away. Two dials crossing are settled by key order (see `registerEndpoint`).
1131
1150
  */
1132
1151
  private knock;
1152
+ /**
1153
+ * This side's listener on `transport` is up again after it was let go while the contact was away (the engine's
1154
+ * `releaseGoneListeners`), and the contact is back: it is dialled once now, whichever side's turn it is, as after a
1155
+ * restart. The contact's own dials found no listener here meanwhile, and wait out their backoff (half a minute).
1156
+ */
1157
+ knockOnReturn(transport: NativeTransport): void;
1133
1158
  /** The knock under way (`knock`): its transport, its attempt, and whether it was knocked again (`knockAgain`). */
1134
1159
  private knocking;
1135
1160
  /**
@@ -1495,6 +1520,19 @@ export declare class GhostLink {
1495
1520
  * `wake/1`. False when it could not go now: the caller shares it again on the next session.
1496
1521
  */
1497
1522
  sendWake(target: WakeTarget | null): boolean;
1523
+ /**
1524
+ * This side's participation key and the pinned contact's, on a paired session that is open and ready: what the asker's
1525
+ * proof of a contact request is made for (WISP 8xx § Accept). Undefined otherwise.
1526
+ */
1527
+ get participationKeys(): {
1528
+ mine: string;
1529
+ peer: string;
1530
+ } | undefined;
1531
+ /**
1532
+ * Says on the live session that this side asked through the contact's link (WISP 8xx § Accept). No capability: an app
1533
+ * that does not know the frame drops it. False when it could not go now: the caller says it again on the next session.
1534
+ */
1535
+ sendContactAsker(frame: ContactAskerFrame): boolean;
1498
1536
  /** Both sides offer `pin/1` on the open session: a pin can be said and confirmed. */
1499
1537
  get supportsPins(): boolean;
1500
1538
  /**
@@ -1583,7 +1621,7 @@ export declare class GhostLink {
1583
1621
  sendAppRange(task: AppRangeTask, bytes: Uint8Array, size: number): Promise<void>;
1584
1622
  /** `task`'s file cannot be read: `changed` or `gone` goes in place of its bytes (nothing once it is no longer live, but its place frees). */
1585
1623
  failAppRange(task: AppRangeTask, error: "changed" | "gone"): void;
1586
- /** Whether `task` still waits for an answer on this session (`AppRanges.holds`): one that does not needs none. */
1624
+ /** Whether `task` still holds a place until it is answered (`AppRanges.holds`): one that does not needs no answer. */
1587
1625
  holdsAppRange(task: AppRangeTask): boolean;
1588
1626
  /** An `ar-*` frame from the contact, on a session that agreed `app-ranges/1`. */
1589
1627
  private receiveAppRange;
@@ -64,6 +64,8 @@ export declare const COMMUNITY_LIMITS: {
64
64
  readonly replay: 256;
65
65
  /** Commits in one welcome or chain piece. */
66
66
  readonly chainPiece: 100;
67
+ /** Admissions members other than the admin may commit in a row while the admin is away (`memberAdmissions`). */
68
+ readonly memberAdmissions: 32;
67
69
  readonly pendingLeaves: 64;
68
70
  /** Leaves whose mark (`group-left`) is kept, and the epochs one names. */
69
71
  readonly leftMarks: 64;
@@ -91,6 +93,11 @@ export declare const COMMUNITY_LIMITS: {
91
93
  readonly catchUpSlice: 16;
92
94
  /** Between two slices, when the member's app cannot say it handled one (`handled` resolves `false`). */
93
95
  readonly catchUpPauseMs: 500;
96
+ /**
97
+ * A message a member handed on with its live mark (`lv`, WISP 903 § Relaying) is live here only when the time it says
98
+ * is at most this long before my clock: the mark is that member's word, and past this it would make a catch-up ring.
99
+ */
100
+ readonly liveMarkMs: number;
94
101
  };
95
102
  /** What every member should know about who can read what, and what the link does, in the words the apps show. */
96
103
  export declare const GROUP_READ_NOTE_COMMUNITY: string;
@@ -322,10 +329,15 @@ export interface CommunityState {
322
329
  /** My next sequence number under the commit `seqH` (full hash). */
323
330
  seq: number;
324
331
  seqH: string;
325
- /** Sender → `e:h16` → highest seen and the window below it. */
332
+ /**
333
+ * Sender → `e:h16` → highest seen and the window below it. `gap`: the lowest number missing below it, how many syncs
334
+ * asked for it and when the last did (`haveOf`); `floor`: what is missing at or below it is given up.
335
+ */
326
336
  seen: Record<string, Record<string, {
327
337
  high: number;
328
338
  window: number[];
339
+ gap?: [number, number, number];
340
+ floor?: number;
329
341
  }>>;
330
342
  nicks: Record<string, string>;
331
343
  /** Recent frames from everyone (mine included), oldest first. */
@@ -346,6 +358,12 @@ export interface CommunityState {
346
358
  * Absent in older states.
347
359
  */
348
360
  alone?: string[];
361
+ /**
362
+ * My texts saved here (counter, frame in `store`) whose message row may not be stored or whose frame may not have gone
363
+ * yet, as `e:h16:n`, oldest first: an app killed in between stores and says them when it opens again (`resume`), so the
364
+ * number is never given to another text. Absent in older states.
365
+ */
366
+ unsaid?: string[];
349
367
  /** Leave requests waiting for a member to commit them. */
350
368
  pendingLeaves: {
351
369
  s: string;
@@ -362,7 +380,14 @@ export interface CommunityState {
362
380
  /** A few statements I held before `meta`, oldest first, for a member back from away (`keepPastGroupMeta`). Absent in older states. */
363
381
  metaPast?: GroupMeta[];
364
382
  }
365
- /** `frame`: the frame the message came in, as it is kept to hand on to a member who missed it. An app may keep it with the message it stores. */
383
+ /**
384
+ * `frame`: the frame the message came in, as it is kept to hand on to a member who missed it (without a live mark). An
385
+ * app may keep it with the message it stores.
386
+ * `live`: it came as it was written (revision 2026-11-03): straight from its author over the author's own edge, not in
387
+ * the author's answer to my sync and not one that waited for a commit or a secret; or handed on at once by the member
388
+ * at the other end of the edge, whose live mark names itself (`lv`), the time it says at most `liveMarkMs` before my
389
+ * clock. How long it took then says how far the author's clock is from mine.
390
+ */
366
391
  export interface CommunityIncomingMessage {
367
392
  id: string;
368
393
  sender: string;
@@ -376,6 +401,7 @@ export interface CommunityIncomingMessage {
376
401
  card?: StatusCard;
377
402
  file?: GroupFileMeta;
378
403
  frame?: CommunityMessageFrame;
404
+ live?: true;
379
405
  }
380
406
  /**
381
407
  * What an application sends through the group rather than as text: `frame` for everyone in the epoch (the group
@@ -415,6 +441,11 @@ export interface CommunitySessionHooks {
415
441
  * Undefined for anything else. Asked once the frame is read, before the `app` hook.
416
442
  */
417
443
  lasting?(message: CommunityIncomingApp): string | undefined;
444
+ /**
445
+ * Whether an application frame (mine or a member's) is only a hint (a `group-have`, WISP 503): relayed live like any
446
+ * frame, but never kept, so it takes no place among those a member back from away gets.
447
+ */
448
+ fleeting?(frame: Record<string, unknown>): boolean;
418
449
  /** An application frame for the group (see `sendApp`). */
419
450
  app?(message: CommunityIncomingApp): Promise<void> | void;
420
451
  /** A payload another member sealed to me (see `sendPair`). Payloads to others are carried, never opened. */
@@ -495,6 +526,10 @@ export declare class CommunitySession {
495
526
  private waiting;
496
527
  private waitingBytes;
497
528
  private asked;
529
+ /** Per member: until when what comes over its edge may be its answer to my sync (`ANSWER_WINDOW_MS`). In memory only. */
530
+ private readonly answering;
531
+ /** The message frames given to `handle` that came live here (`CommunityIncomingMessage.live`): `passOn` marks them. */
532
+ private readonly cameLive;
498
533
  /** Syncs answered per member, a few a minute (`COMMUNITY_LIMITS.syncAnswers`). In memory only. */
499
534
  private syncsAnswered;
500
535
  /** Messages taken per author, a few a second (`MessagePace`). In memory only. */
@@ -513,6 +548,8 @@ export declare class CommunitySession {
513
548
  private pendingMeta;
514
549
  /** The store's frames the app holds with their messages (`storeKey` → message id): in memory here, not in what is saved. */
515
550
  private readonly onRows;
551
+ /** The oldest epoch whose seen marks are kept, as of the last `pruneSeen`. In memory only. */
552
+ private seenFrom;
516
553
  /** `rows`: the frames the app holds with the messages it stored (`CommunityIncomingMessage.frame`). They join the store. */
517
554
  constructor(state: CommunityState, hooks: CommunitySessionHooks, rows?: readonly {
518
555
  id: string;
@@ -655,15 +692,27 @@ export declare class CommunitySession {
655
692
  private branch;
656
693
  /** How many admin changes the main branch holds up to each index. */
657
694
  private adminCounts;
658
- /** What each of two branches holds after their common parent: whether it has an admin change, and its first commit. */
695
+ /** What each of two branches holds after their common parent: whether it has an admin change, its first commit, and its hand-overs. */
659
696
  private parting;
660
697
  /**
661
- * Is branch `a` better than branch `b`? After their common parent: the one that keeps an admin
662
- * change first, however short and however far back it parts; then the longer; then, parting within
663
- * the window, the lower hash of the first commit. Both holding admin changes means the admin signed
664
- * two histories: `b` stays (a fresh one halts the group, see `receiveCommit`).
698
+ * Whether a hand-over (`h`, a `role`) went to a member whose leave of that admission I know on a branch that does not
699
+ * hold the hand-over: signed on a view from before the leave, it would leave the role with someone gone for good (a
700
+ * leave never names the admin). Not when that member signed a commit after the hand-over: it took the role while still
701
+ * in, so its leave came later, and a branch from before the hand-over must not undo what it and later admins did.
702
+ */
703
+ private handedToLeaver;
704
+ /** Whether `key` signed a commit I know that comes after `h` (on the main branch past it, or on a side branch through it). */
705
+ private signedAfter;
706
+ /**
707
+ * Is branch `a` better than branch `b`? After their common parent: first, the one that does not hand the
708
+ * role to a member who left (`handedToLeaver`); then the one that keeps an admin change, however short
709
+ * and however far back it parts; then one I can read over one whose tip lists me and whose secret I lack;
710
+ * then the longer; then, parting within the window, the lower hash of the first commit. Both holding admin changes means the admin signed two histories: `b` stays (a fresh one
711
+ * halts the group, see `receiveCommit`).
665
712
  */
666
713
  private better;
714
+ /** A commit whose roster lists me and whose secret I do not hold (yet). */
715
+ private awaitsSecret;
667
716
  /**
668
717
  * Takes in a commit (from a frame or from me): placed in the tree if it verifies against its
669
718
  * parent, a fork if the admin signed another commit after the same parent, and then the best
@@ -693,6 +742,13 @@ export declare class CommunitySession {
693
742
  private followEntry;
694
743
  /** Side commits stay up to a bound, the most recent ones (a longer branch being assembled included). */
695
744
  private pruneSide;
745
+ /**
746
+ * Seen marks of epochs older than the window go, every sender's, once the branch I follow moves past them: as
747
+ * `markSeen` drops the sender's it marks. Before, only that sender's went, so a member who left or went quiet kept
748
+ * an entry for every epoch it wrote in, and its window of numbers, for the life of the group (agents#2904). Those
749
+ * within the window stay, a leaver's too: what it wrote before its leave is still taken up to its mark there.
750
+ */
751
+ private pruneSeen;
696
752
  private pruneSecrets;
697
753
  /** A derived epoch's secret, from its parent's, when that is held. */
698
754
  private takeDerived;
@@ -725,7 +781,20 @@ export declare class CommunitySession {
725
781
  rewelcome(memberKey: string): Promise<(CommunityChainFrame | CommunityWelcomeFrame)[]>;
726
782
  /** The chain, the secrets from the admitting commit on, the rendezvous secret and the entry seed, for one newcomer. */
727
783
  private welcomeFor;
784
+ /**
785
+ * Takes a member out, and with it everyone it let in who is still in, and whom those let in in turn
786
+ * (`admittedThrough`): keys a member let in cost it nothing, and one by one they were the admin's to clear. A
787
+ * `remove` commit each, as before (an app from before follows them), one at a time, so what arrives meanwhile is
788
+ * heard, and an admission signed meanwhile by one of them is taken out too (`memberAdmissions` bounds them, as a
789
+ * removal is not the admin letting anyone in). A member already out still has those it let in cleared.
790
+ */
728
791
  remove(memberKey: string, now?: number): Promise<void>;
792
+ /**
793
+ * The members still in whose admission, on the main branch, `root` signed, or one of them did, and so on: in the
794
+ * order they were let in. An admission signed by whoever was the admin then is the admin's, not counted: removing
795
+ * a former admin does not take out everyone it let in. Never the admin nor me.
796
+ */
797
+ private admittedThrough;
729
798
  transferAdmin(memberKey: string, now?: number): Promise<void>;
730
799
  rotate(now?: number): Promise<void>;
731
800
  /** A new entry key (the old link reaches nobody), or none (`off`): a `link` commit every member follows. */
@@ -737,7 +806,11 @@ export declare class CommunitySession {
737
806
  leave(): Promise<CommunityLeaveFrame | null>;
738
807
  /** Commits the leave requests I hold whose members are still in: the engine calls this on hubs. */
739
808
  commitPendingLeaves(now?: number): Promise<number>;
740
- /** Signs and says how far I had heard a member whose leave I just committed (`group-left`). */
809
+ /**
810
+ * Signs and says how far I had heard a member whose leave I just committed (`group-left`): per epoch, up to the first
811
+ * number of my window of it I never heard, so a copy of the leaver's state cannot sign one later into the gap. A gap
812
+ * at the window's bottom (a jump past it, or a counter raised by a restore) leaves the epoch out: nothing of it then.
813
+ */
741
814
  private markLeft;
742
815
  private out;
743
816
  /**
@@ -756,7 +829,7 @@ export declare class CommunitySession {
756
829
  /**
757
830
  * An application frame to everyone in the group (a note about a payment, a request anyone may pay): sealed to
758
831
  * the epoch like text, signed, kept and caught up like text, and handed to the other members' `app` hook
759
- * instead of their history.
832
+ * instead of their history. A fleeting one (`CommunitySessionHooks.fleeting`) is only said to those up now.
760
833
  */
761
834
  sendApp(frame: Record<string, unknown>, nick?: string, now?: number): Promise<{
762
835
  id: string;
@@ -802,9 +875,21 @@ export declare class CommunitySession {
802
875
  /**
803
876
  * Saves, then says my frame on every edge. One no edge took (none is up: I just joined, or my app just opened) is
804
877
  * remembered until a member it was written for is handed it: I may be behind on the chain without knowing, and the
805
- * first member I reach may be one let in since, who cannot read it but can carry it (`receiveSync`).
878
+ * first member I reach may be one let in since, who cannot read it but can carry it (`receiveSync`). `saved`: the
879
+ * caller marked it unheard and saved it (`sendText`).
806
880
  */
807
881
  private say;
882
+ /** My frame in `unheard`, before it is said: the frames of mine the store no longer holds leave it. */
883
+ private markUnheard;
884
+ /**
885
+ * Stores and says what an app killed mid-send left `unsaid`: its counter and frame were saved, its row or its sending
886
+ * may not have happened. A row stored already is not stored twice (the app's store takes one row per id), a frame
887
+ * that went already is taken by the members as one they hold. The engine calls this on each tick; a send does first.
888
+ */
889
+ resume(): Promise<void>;
890
+ private sayUnsaid;
891
+ /** The row of one of my own texts, as `sendText` stored it, opened from its frame; none for anything else, or one deleted for everyone. */
892
+ private ownRow;
808
893
  /**
809
894
  * Message `id` was deleted for everyone (WISP 400 § Delete for everyone), by its author or here: its frame goes from
810
895
  * the store, so no catch-up hands it to a member who was away (they get the removal, which stays). A frame said again
@@ -854,7 +939,16 @@ export declare class CommunitySession {
854
939
  * was new and valid, so a hub knows to relay it on.
855
940
  */
856
941
  handle(from: string, raw: unknown): Promise<boolean>;
942
+ /** After a secret came that confirms: a branch that waited for it may be the one to follow now (see `better`). */
943
+ private tookSecrets;
857
944
  private receiveLeave;
945
+ /**
946
+ * What a hub hands on of a frame it took (`handle` said it was new): as it came, without the live mark of whoever
947
+ * handed it to me, and with mine when it came live here (WISP 903 § Relaying, revision 2026-11-03). Hand it on at
948
+ * once: the mark says it is passed on as it came.
949
+ */
950
+ passOn(frame: object): object;
951
+ /** `waited`: it waited for a commit or a secret (`replayWaiting`), so it is not live. */
858
952
  private receiveMessage;
859
953
  /**
860
954
  * A frame signed with my own key that I did not send here: another copy of this profile sent it (a restored backup, a
@@ -863,6 +957,14 @@ export declare class CommunitySession {
863
957
  */
864
958
  private ownFrame;
865
959
  private isDuplicate;
960
+ /**
961
+ * What a sync says I have of a sender under a commit: below the lowest number missing, not the highest seen. A live
962
+ * frame raises the highest above that sender's frames still coming in a catch-up answer, and when the rest of the
963
+ * answer never came (my app closed or my edge dropped, or the hub's app closed), every later sync said I had them:
964
+ * they were lost for good (2026-10-18). A gap asked for by `GAP_ASKS` syncs at least `GAP_ASK_MS` apart that none
965
+ * filled (the stores rolled past it, a leaver's frames) is given up: each answer hands what is stored above it again.
966
+ */
967
+ private haveOf;
866
968
  private markSeen;
867
969
  private park;
868
970
  /** Something is missing here: the current epoch's secret, or the epoch of frames waiting. */
@@ -887,7 +989,11 @@ export declare class CommunitySession {
887
989
  setPicture(picture: string | null, now?: number): Promise<void>;
888
990
  /** Renames the group: only the admin, signed under the current commit, beside the picture. */
889
991
  rename(name: string, now?: number): Promise<void>;
890
- /** Signs a body under my current commit, keeps it and sends it to everyone (hubs relay it). Inside `serialize`. */
992
+ /**
993
+ * Signs a body under my current commit, keeps it and sends it to everyone (hubs relay it). Inside `serialize`. Like a
994
+ * commit, only with admin work on and a good turn read (WISP 06 § Forced takeover): refused otherwise, or, `quiet`,
995
+ * not made. Its revision is never under the floor (WISP 06 § Raised counters).
996
+ */
891
997
  private publishMeta;
892
998
  /** A statement sealed under my current epoch, when I hold its secret. */
893
999
  private metaFrame;
@@ -21,6 +21,13 @@ export declare const GROUP_FILE_LIMITS: {
21
21
  readonly serveMoveBytes: number;
22
22
  /** How long a served transfer keeps its place while all are taken and another member asks: past it, the place is theirs. */
23
23
  readonly servePlaceMs: number;
24
+ /**
25
+ * A served transfer's pace is what it confirmed in the last `servePaceMs` (at most twice that), counted from its offer.
26
+ * While all places are taken and a member holding none asks or waits, the slowest served that long gives it its place,
27
+ * if at its pace more is left to go than it has been served and than `servePaceMs`: members on fast links do not wait
28
+ * for slow ones that asked first. Each member's transfer of a file loses its place so once per holder.
29
+ */
30
+ readonly servePaceMs: 10000;
24
31
  /** File announcements a member sends to one group in a minute. */
25
32
  readonly announcePerMinute: 8;
26
33
  /** File announcements of one member of a group fetched by themselves in `announceWindowMs`; past it, kept for a Download. */
@@ -47,6 +54,14 @@ export declare const GROUP_FILE_LIMITS: {
47
54
  */
48
55
  readonly haveFramesTaken: 20;
49
56
  readonly communityHaveEveryMs: 60000;
57
+ /**
58
+ * `group-want` frames an edge sends in `wantWindowMs`, and takes from its member, the rest dropped before anything is
59
+ * looked up: twice what it may send, as for `group-have`. A member back from away in a group of 16 asked one member
60
+ * for at most 47 in 10 seconds, its files coming as fast as the network lets them.
61
+ */
62
+ readonly wantFrames: 50;
63
+ readonly wantFramesTaken: 100;
64
+ readonly wantWindowMs: 10000;
50
65
  /**
51
66
  * How long a want waits for an offer before the next holder is asked; a transfer that does not move for as long is
52
67
  * left for the next holder too.
@@ -124,12 +124,13 @@ export declare function groupMetaNewer(a: {
124
124
  /**
125
125
  * The revision of the next statement signed under `epoch`: one past the held statement's under the same epoch, else 1.
126
126
  * Counting on from a statement of an earlier epoch would let a former admin who signed the highest safe revision leave
127
- * every later admin with a revision no member accepts.
127
+ * every later admin with a revision no member accepts. Never under `floor` (WISP 06 § Raised counters): a copy started
128
+ * from older state signs above every revision the device it replaced may have signed under the same commit.
128
129
  */
129
130
  export declare function nextGroupMetaRevision(before: {
130
131
  e: number;
131
132
  r: number;
132
- } | undefined, epoch: number): number;
133
+ } | undefined, epoch: number, floor?: number): number;
133
134
  /**
134
135
  * Statements a member keeps from before the one it holds, oldest first, so it can hand a member back from away each
135
136
  * change it missed where it was made, not only the latest (two renames read as one, 2026-10-14). A few, and their