@941design/marmot 0.0.0-stage → 0.2.0-alpha.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 (206) hide show
  1. package/CHANGELOG.md +739 -0
  2. package/LICENSE +21 -0
  3. package/README.md +33 -2
  4. package/dist/account/admin.d.ts +72 -0
  5. package/dist/account/admin.js +209 -0
  6. package/dist/account/device-deps.d.ts +379 -0
  7. package/dist/account/device-deps.js +36 -0
  8. package/dist/account/device-lineage.d.ts +199 -0
  9. package/dist/account/device-lineage.js +390 -0
  10. package/dist/account/device-registry.d.ts +93 -0
  11. package/dist/account/device-registry.js +1290 -0
  12. package/dist/account/device-rotation.d.ts +61 -0
  13. package/dist/account/device-rotation.js +827 -0
  14. package/dist/account/enrolment.d.ts +339 -0
  15. package/dist/account/enrolment.js +1247 -0
  16. package/dist/account/identity-proof.d.ts +79 -0
  17. package/dist/account/identity-proof.js +264 -0
  18. package/dist/account/index.d.ts +17 -0
  19. package/dist/account/index.js +16 -0
  20. package/dist/account/restore-rotation.d.ts +21 -0
  21. package/dist/account/restore-rotation.js +22 -0
  22. package/dist/account/same-account-authorization.d.ts +86 -0
  23. package/dist/account/same-account-authorization.js +180 -0
  24. package/dist/account/teardown.d.ts +190 -0
  25. package/dist/account/teardown.js +878 -0
  26. package/dist/client/admission-cleanup.d.ts +197 -0
  27. package/dist/client/admission-cleanup.js +635 -0
  28. package/dist/client/adoption-proof.d.ts +39 -0
  29. package/dist/client/adoption-proof.js +102 -0
  30. package/dist/client/before-create-group.d.ts +18 -0
  31. package/dist/client/before-create-group.js +65 -0
  32. package/dist/client/before-publish-hooks.d.ts +121 -0
  33. package/dist/client/before-publish-hooks.js +182 -0
  34. package/dist/client/client-config.d.ts +42 -0
  35. package/dist/client/client-config.js +13 -0
  36. package/dist/client/commit-redrive.d.ts +92 -0
  37. package/dist/client/commit-redrive.js +274 -0
  38. package/dist/client/component-update.d.ts +43 -0
  39. package/dist/client/component-update.js +53 -0
  40. package/dist/client/confirm-hooks.d.ts +55 -0
  41. package/dist/client/confirm-hooks.js +74 -0
  42. package/dist/client/create-client.d.ts +1126 -0
  43. package/dist/client/create-client.js +1232 -0
  44. package/dist/client/group-availability.d.ts +182 -0
  45. package/dist/client/group-availability.js +301 -0
  46. package/dist/client/group-disband.d.ts +28 -0
  47. package/dist/client/group-disband.js +64 -0
  48. package/dist/client/group-history.d.ts +461 -0
  49. package/dist/client/group-history.js +1365 -0
  50. package/dist/client/group-profile.d.ts +31 -0
  51. package/dist/client/group-profile.js +62 -0
  52. package/dist/client/group-records.d.ts +522 -0
  53. package/dist/client/group-records.js +1117 -0
  54. package/dist/client/group-removal.d.ts +36 -0
  55. package/dist/client/group-removal.js +127 -0
  56. package/dist/client/group-remove-member.d.ts +49 -0
  57. package/dist/client/group-remove-member.js +163 -0
  58. package/dist/client/group-runtime.d.ts +415 -0
  59. package/dist/client/group-runtime.js +2811 -0
  60. package/dist/client/group-snapshot.d.ts +104 -0
  61. package/dist/client/group-snapshot.js +474 -0
  62. package/dist/client/history-pages.d.ts +107 -0
  63. package/dist/client/history-pages.js +194 -0
  64. package/dist/client/inbox-send.d.ts +19 -0
  65. package/dist/client/inbox-send.js +71 -0
  66. package/dist/client/index.d.ts +24 -0
  67. package/dist/client/index.js +13 -0
  68. package/dist/client/ingest.d.ts +82 -0
  69. package/dist/client/ingest.js +1584 -0
  70. package/dist/client/invitation-outcomes.d.ts +50 -0
  71. package/dist/client/invitation-outcomes.js +135 -0
  72. package/dist/client/lifecycle-events.d.ts +63 -0
  73. package/dist/client/lifecycle-events.js +35 -0
  74. package/dist/client/opaque-candidates.d.ts +82 -0
  75. package/dist/client/opaque-candidates.js +170 -0
  76. package/dist/client/own-change-outbox.d.ts +66 -0
  77. package/dist/client/own-change-outbox.js +158 -0
  78. package/dist/client/pending-leaf.d.ts +116 -0
  79. package/dist/client/pending-leaf.js +378 -0
  80. package/dist/client/permissions.d.ts +9 -0
  81. package/dist/client/permissions.js +12 -0
  82. package/dist/client/pipeline.d.ts +583 -0
  83. package/dist/client/pipeline.js +3666 -0
  84. package/dist/client/reentrancy-guard.d.ts +102 -0
  85. package/dist/client/reentrancy-guard.js +159 -0
  86. package/dist/client/rekey.d.ts +58 -0
  87. package/dist/client/rekey.js +149 -0
  88. package/dist/client/transport-policy.d.ts +181 -0
  89. package/dist/client/transport-policy.js +214 -0
  90. package/dist/history/admission-lineage.d.ts +186 -0
  91. package/dist/history/admission-lineage.js +589 -0
  92. package/dist/history/equivocation.d.ts +55 -0
  93. package/dist/history/equivocation.js +113 -0
  94. package/dist/history/fencing.d.ts +66 -0
  95. package/dist/history/fencing.js +121 -0
  96. package/dist/history/hex.d.ts +3 -0
  97. package/dist/history/hex.js +10 -0
  98. package/dist/history/index.d.ts +74 -0
  99. package/dist/history/index.js +32 -0
  100. package/dist/history/notifications.d.ts +270 -0
  101. package/dist/history/notifications.js +264 -0
  102. package/dist/history/ordering-key.d.ts +24 -0
  103. package/dist/history/ordering-key.js +101 -0
  104. package/dist/history/own-change-fork.d.ts +112 -0
  105. package/dist/history/own-change-fork.js +196 -0
  106. package/dist/history/own-change.d.ts +118 -0
  107. package/dist/history/own-change.js +146 -0
  108. package/dist/history/policy.d.ts +48 -0
  109. package/dist/history/policy.js +52 -0
  110. package/dist/history/retained-window.d.ts +215 -0
  111. package/dist/history/retained-window.js +565 -0
  112. package/dist/inbox/demux.d.ts +90 -0
  113. package/dist/inbox/demux.js +78 -0
  114. package/dist/inbox/handler-registry.d.ts +42 -0
  115. package/dist/inbox/handler-registry.js +37 -0
  116. package/dist/inbox/index.d.ts +11 -0
  117. package/dist/inbox/index.js +10 -0
  118. package/dist/inbox/seen-set.d.ts +82 -0
  119. package/dist/inbox/seen-set.js +202 -0
  120. package/dist/inbox/subscription.d.ts +236 -0
  121. package/dist/inbox/subscription.js +644 -0
  122. package/dist/index.d.ts +10 -0
  123. package/dist/index.js +9 -0
  124. package/dist/invitations/competing-welcome.d.ts +223 -0
  125. package/dist/invitations/competing-welcome.js +128 -0
  126. package/dist/invitations/decline.d.ts +67 -0
  127. package/dist/invitations/decline.js +149 -0
  128. package/dist/invitations/delivery-evidence.d.ts +288 -0
  129. package/dist/invitations/delivery-evidence.js +766 -0
  130. package/dist/invitations/expect-welcome.d.ts +66 -0
  131. package/dist/invitations/expect-welcome.js +138 -0
  132. package/dist/invitations/index.d.ts +18 -0
  133. package/dist/invitations/index.js +18 -0
  134. package/dist/invitations/invitation-outcome.d.ts +110 -0
  135. package/dist/invitations/invitation-outcome.js +210 -0
  136. package/dist/invitations/invite.d.ts +358 -0
  137. package/dist/invitations/invite.js +1102 -0
  138. package/dist/invitations/offers.d.ts +79 -0
  139. package/dist/invitations/offers.js +115 -0
  140. package/dist/invitations/on-proposal.d.ts +47 -0
  141. package/dist/invitations/on-proposal.js +40 -0
  142. package/dist/invitations/pending-proposal-policy.d.ts +52 -0
  143. package/dist/invitations/pending-proposal-policy.js +139 -0
  144. package/dist/invitations/proposal-deadline.d.ts +133 -0
  145. package/dist/invitations/proposal-deadline.js +164 -0
  146. package/dist/invitations/relay-planes.d.ts +43 -0
  147. package/dist/invitations/relay-planes.js +70 -0
  148. package/dist/invitations/welcome-processor.d.ts +272 -0
  149. package/dist/invitations/welcome-processor.js +1241 -0
  150. package/dist/key-packages/device-key.d.ts +131 -0
  151. package/dist/key-packages/device-key.js +272 -0
  152. package/dist/key-packages/device-rotation-records.d.ts +83 -0
  153. package/dist/key-packages/device-rotation-records.js +173 -0
  154. package/dist/key-packages/group-refs.d.ts +40 -0
  155. package/dist/key-packages/group-refs.js +79 -0
  156. package/dist/key-packages/index.d.ts +18 -0
  157. package/dist/key-packages/index.js +18 -0
  158. package/dist/key-packages/key-package-ref.d.ts +16 -0
  159. package/dist/key-packages/key-package-ref.js +21 -0
  160. package/dist/key-packages/observation-stream.d.ts +4 -0
  161. package/dist/key-packages/observation-stream.js +120 -0
  162. package/dist/key-packages/offer-rumor.d.ts +26 -0
  163. package/dist/key-packages/offer-rumor.js +69 -0
  164. package/dist/key-packages/publisher.d.ts +174 -0
  165. package/dist/key-packages/publisher.js +1247 -0
  166. package/dist/key-packages/select-key-package.d.ts +24 -0
  167. package/dist/key-packages/select-key-package.js +90 -0
  168. package/dist/key-packages/slot-manager.d.ts +167 -0
  169. package/dist/key-packages/slot-manager.js +327 -0
  170. package/dist/key-packages/validate-key-package-event.d.ts +3 -0
  171. package/dist/key-packages/validate-key-package-event.js +49 -0
  172. package/dist/media/cache.d.ts +14 -0
  173. package/dist/media/cache.js +10 -0
  174. package/dist/media/index.d.ts +52 -0
  175. package/dist/media/index.js +71 -0
  176. package/dist/mls.d.ts +15 -0
  177. package/dist/mls.js +15 -0
  178. package/dist/shared/account-pubkey.d.ts +4 -0
  179. package/dist/shared/account-pubkey.js +10 -0
  180. package/dist/shared/errors.d.ts +28 -0
  181. package/dist/shared/errors.js +96 -0
  182. package/dist/shared/hex.d.ts +4 -0
  183. package/dist/shared/hex.js +13 -0
  184. package/dist/shared/index.d.ts +14 -0
  185. package/dist/shared/index.js +14 -0
  186. package/dist/shared/kinds.d.ts +8 -0
  187. package/dist/shared/kinds.js +28 -0
  188. package/dist/shared/publish-classification.d.ts +26 -0
  189. package/dist/shared/publish-classification.js +31 -0
  190. package/dist/storage/envelope.d.ts +39 -0
  191. package/dist/storage/envelope.js +201 -0
  192. package/dist/storage/index.d.ts +237 -0
  193. package/dist/storage/index.js +491 -0
  194. package/dist/storage/indexeddb/idb-types.d.ts +68 -0
  195. package/dist/storage/indexeddb/idb-types.js +1 -0
  196. package/dist/storage/indexeddb/index.d.ts +17 -0
  197. package/dist/storage/indexeddb/index.js +141 -0
  198. package/dist/storage/lease.d.ts +54 -0
  199. package/dist/storage/lease.js +168 -0
  200. package/dist/storage/memory/deterministic-signer.d.ts +27 -0
  201. package/dist/storage/memory/deterministic-signer.js +65 -0
  202. package/dist/storage/memory/index.d.ts +32 -0
  203. package/dist/storage/memory/index.js +87 -0
  204. package/dist/storage/memory/lock-manager.d.ts +8 -0
  205. package/dist/storage/memory/lock-manager.js +71 -0
  206. package/package.json +66 -3
@@ -0,0 +1,1126 @@
1
+ /**
2
+ * `createMarmotClient` and the typed client surface (docs/client-api.md).
3
+ *
4
+ * Construction is synchronous and side-effect free towards the consumer's
5
+ * collaborators: it validates options, wraps the account signer with
6
+ * `nostr-events`' `withSignerBudget` (AC-API-5, ADR-009) and narrows the
7
+ * transport to the three `TransportContract` members (AC-API-4). It never
8
+ * calls the signer or the transport.
9
+ *
10
+ * No member is a stub: AC-FIX-6 (S11) sweeps the built package and fails on
11
+ * any `not-implemented` MarmotError.
12
+ */
13
+ import type { MarmotGroupEngineOptions } from '@941design/marmot-engine/engine';
14
+ import type { NostrEvent, Rumor } from '@941design/nostr-events/event';
15
+ import { type Signer } from '@941design/nostr-events/signer';
16
+ import { type BudgetPolicy } from '@941design/nostr-events/signer/budget';
17
+ import type { PermissionDeclaration } from '@941design/nostr-events/signer/permissions';
18
+ import type { TransportContract } from '@941design/nostr-events/transport/contract';
19
+ import type { AppliedNotification, GroupNotification, HistoryBackend, LeafEquivocationNotification, OrderingKey } from '../history/index.js';
20
+ import type { EncryptedMedia, EncryptMediaOptions, MediaCache } from '../media/index.js';
21
+ import { type DeviceForgetOutcome, type DeviceInfo, type DeviceKeyRotationOutcome, type DeviceLineage, type DeviceMaintenanceKind, type EnrolmentApprovalOutcome, type EnrolmentPrompt, type EnrolmentRequestHandle, type EnrolmentRequestOptions } from '../account/index.js';
22
+ import { type InboxDisposition, type InboxRumorHandler } from '../inbox/index.js';
23
+ import { type KeyPackageOffer, type MaintenanceKind, type InvitationOutcome, type CleanupReference, type DeclineCandidate, type DeclineCandidatePage, type PendingInvitation, type ProposalCallback, type WelcomeOutcome } from '../invitations/index.js';
24
+ import { MarmotError } from '../shared/index.js';
25
+ import type { AccountStore, GroupStore, GroupStoreTx } from '../storage/index.js';
26
+ import { type BeforeCreateGroupGates, type CreateGroupGate } from './before-create-group.js';
27
+ import { type BeforePublishHook, type BeforePublishRegistry, type BeforePublishSkipped } from './before-publish-hooks.js';
28
+ import { type GroupRegistry, type GroupRuntime } from './group-runtime.js';
29
+ import type { AvailabilityObservation } from './group-availability.js';
30
+ import type { GroupSnapshot } from './group-snapshot.js';
31
+ import { type InboxRumorDelivery } from './inbox-send.js';
32
+ import { type LifecycleEventPayloads, type LifecycleEvents } from './lifecycle-events.js';
33
+ import { type EngineSeamsOverride } from './client-config.js';
34
+ import { type CleanupDispositionReport } from './admission-cleanup.js';
35
+ /** Consumer-supplied check run on every relay event before it is trusted (ADR-008). */
36
+ export type EventVerifier = (event: NostrEvent) => boolean | Promise<boolean>;
37
+ /**
38
+ * The consumer's ADR-007 stores — `{ account, groupFactory }` of a
39
+ * `WritableStores` (`@941design/marmot/storage`), opened under the lease.
40
+ */
41
+ export interface ClientStores {
42
+ readonly account: AccountStore;
43
+ groupFactory(groupId: string): GroupStore;
44
+ }
45
+ /** Relay policy: `discover` resolves inbox relays via 10050/10002; `fixed` is single-relay mode. */
46
+ export interface RelayOptions {
47
+ readonly defaults: readonly string[];
48
+ readonly mode: 'discover' | 'fixed';
49
+ }
50
+ /** Injectable millisecond clock (grace window, deadlines, rate limits). */
51
+ export interface ClientClock {
52
+ now(): number;
53
+ }
54
+ /**
55
+ * Injectable scheduler for the client's deferred work: confirmation and
56
+ * publish retries, history re-requests and the engine's convergence
57
+ * settle-check. Defaults to `setTimeout` / `clearTimeout`.
58
+ */
59
+ export interface ClientTimers {
60
+ set(callback: () => void, ms: number): unknown;
61
+ clear(handle: unknown): void;
62
+ }
63
+ export interface ClientOptions {
64
+ /** Defaults to `Date.now`. */
65
+ readonly clock?: ClientClock;
66
+ /** Consecutive history timeouts before a relay is excluded from history requests (AC-PIPE-14). Default 3. */
67
+ readonly historySilenceThreshold?: number;
68
+ /** KeyPackage `init_key` retention after consumption (AC-KP-3). Default 24 h. */
69
+ readonly graceWindowMs?: number;
70
+ /** Scheduler for retries and deferred work. Defaults to `setTimeout` / `clearTimeout`. */
71
+ readonly timers?: ClientTimers;
72
+ /** Deadline of each kind-445 history `requestWithDeadline` (AC-PIPE-7). Default 10 s. */
73
+ readonly historyTimeoutMs?: number;
74
+ /** Failed publishes after which a retryable intent goes terminal (`send-rejected` / `intentFailed`). Default 20. */
75
+ readonly maxPublishAttempts?: number;
76
+ /**
77
+ * AC-BAR-2: the one deadline (ms) under which an own commit's `onBeforePublish` barriers are awaited before its first
78
+ * publish. A barrier still pending at the deadline is abandoned (its signal aborts), the commit is published anyway
79
+ * and `beforePublishSkipped { reason: 'barrier-timeout' }` fires. An integer >= 1; default 10 000.
80
+ */
81
+ readonly beforePublishTimeoutMs?: number;
82
+ /** Most kind-1059 wrap ids the persisted inbox seen-set keeps; the oldest are evicted first (AC-INBOX-4). Default 10 000. */
83
+ readonly seenSetCap?: number;
84
+ /**
85
+ * Most distinct enrolment requests one session id may have prompted within
86
+ * a minute; the rest are dropped silently (AC-DEV-5). Default 3.
87
+ */
88
+ readonly enrolmentPromptRateLimit?: number;
89
+ /**
90
+ * Relay event-size budget (bytes of event JSON) of the gift wrap an own enrolment request is sent in:
91
+ * `devices.requestEnrolment` refuses a request whose wrap could exceed it (`invalid-options`,
92
+ * `details.reason: 'request-too-large'`, with `wrapBytes`) before anything is minted. A positive safe
93
+ * integer; default 65 536 (64 KiB, a common relay cap).
94
+ */
95
+ readonly maxGiftWrapBytes?: number;
96
+ /**
97
+ * How long `group.leave()` (and each group of `devices.forget(ownLeafKey)`)
98
+ * waits for a peer's confirmed commit of the local leaf's SelfRemove before
99
+ * purging the group anyway (AC-ADMIN-6). Client-clock milliseconds; default 60 000.
100
+ */
101
+ readonly leaveTimeoutMs?: number;
102
+ /**
103
+ * How long a proposal `onProposal` deferred stays deferred (AC-INVITE-4).
104
+ * Client-clock milliseconds from its first `defer`; default 86 400 000
105
+ * (24 h); `0` = never expires. The deadline is persisted with the deferral
106
+ * (no timer) and checked on every own-commit attempt, on group load, on
107
+ * each history pass of the group and on each inbox pass — never while the
108
+ * group is not caught up (no complete sync since load or since its live
109
+ * subscription last ended). `Infinity` also means never. Once it passed,
110
+ * the proposal is treated as `reject` (never auto-accepted) and
111
+ * `proposalExpired` fires.
112
+ */
113
+ readonly proposalDeferralTimeoutMs?: number;
114
+ /**
115
+ * S20 (AC-ADMIN-6/-10): how long a removal of the local leaf stays revisable after the group's own state first
116
+ * shows it — a same-epoch sibling commit arriving inside it rewinds the removal (the device stays a member; a
117
+ * `leave()` resumes as a member) — before it settles: later input is then `self-evicted`, and a `leave()` /
118
+ * own-leaf `devices.forget` waiting on the removal performs `abandon()`. Client-clock milliseconds, a finite
119
+ * integer >= 0; default 10 000. `0` settles at the removal (the pre-S20 timing) — an opt-out that accepts the
120
+ * zombie leave: a device removed only on the losing branch of a race purges while the group still holds its
121
+ * leaf. No upper bound: values above `leaveTimeoutMs` only lengthen the post-removal wait, never the
122
+ * pre-removal one.
123
+ */
124
+ readonly removalSettleMs?: number;
125
+ /**
126
+ * S5 (AC-RACE-2): how long `advanceQueue` and `invite()`'s proposal policy wait for the elected member's
127
+ * confirmed commit before an admin's own `send()`/`invite()` commits a staged SelfRemove-only batch another
128
+ * member is elected to commit (`decideAutoCommit`/`electionAtRest`, client/pipeline.ts) itself. Client-clock
129
+ * milliseconds, a finite integer >= 0; default 5000 (well under `leaveTimeoutMs`'s default 60000). `0` commits
130
+ * at once (the pre-S5 timing): an opt-out that accepts pre-empting the elected committer.
131
+ */
132
+ readonly selfRemoveElectionWaitMs?: number;
133
+ /**
134
+ * S7 (AC-HYG-2): how long an invite's account record is kept once every one of its Welcome deliveries is
135
+ * `delivered` or `declined` — client-clock milliseconds after its last delivery settled. Until then
136
+ * `retryWelcome` can re-send a delivered Welcome and an invitee's decline is matched to it (`welcomeDeclined`);
137
+ * after it the record is deleted the next time the group is loaded, invited to, retried or declined in. A record
138
+ * with a pending, retryable or failed delivery is never deleted by age. A safe integer >= 0; default 30 days.
139
+ */
140
+ readonly inviteRetentionMs?: number;
141
+ /**
142
+ * inbox-handler-time-budget: how long an inbox consumer callback (a `registerInboxHandler` handler or
143
+ * `onApplicationRumor`) may run before `handlerSlow` reports it — a diagnostic only: the handler is never detached
144
+ * and the inbox queue still waits for it (the "handlers must not await long work" contract stands). Client-clock
145
+ * milliseconds, a safe integer >= 0; default 30 000; `0` never reports.
146
+ */
147
+ readonly inboxHandlerBudgetMs?: number;
148
+ /**
149
+ * S8 (AC-RATCH-1): how many generations the own application sender ratchet skips at the first own application
150
+ * message of a group after it is loaded from storage (encrypted once its first post-load sync opened the send
151
+ * gate). The loaded state may be a restored snapshot that never saw own messages sent after it, held only by a
152
+ * relay the first sync excluded as silent: skipping keeps the next message from re-using one of their
153
+ * generations (same key and nonce; members that read the earlier one refuse it). A safe integer in [32, 100];
154
+ * default 64. The skip is applied with that first message only — never persisted without it — so repeated loads
155
+ * with no send do not accumulate; and until a relay accepted an own application message at or after a recorded
156
+ * skip, a load of that same epoch state does not skip again (group-records.ts `ratchetSkipArmed`), so restarts whose
157
+ * first message is refused everywhere keep the gap within one margin plus the undelivered messages. Own messages
158
+ * the first post-load sync reads back from relays floor the skip (ingesting them advances the own ratchet), and one
159
+ * at or after an undelivered recorded skip marks it delivered and re-arms the skip (BACKLOG
160
+ * ratchet-skip-relay-derived-floor). Skips add up
161
+ * otherwise only for a member that misses messages: one that missed every own
162
+ * message of n load cycles in one epoch reads the next one while n × (margin + messages per cycle) + margin stays
163
+ * within the receivers' forward window (ts-mls `maximumForwardRatchetSteps`, 200); the upper bound (half of it)
164
+ * keeps any single skip, plus fewer than a margin of own messages a member did not receive, inside it. Own
165
+ * messages a restored snapshot can miss must stay fewer than the margin.
166
+ */
167
+ readonly ratchetSkipMargin?: number;
168
+ }
169
+ export interface MarmotClientOptions {
170
+ /** Account-key signer; the client wraps it with `withSignerBudget(signer, budget)`. */
171
+ readonly signer: Signer;
172
+ /** `nostr-events` budget policy; `{ policy: 'none' }` is the explicit opt-out. Required. */
173
+ readonly budget: BudgetPolicy;
174
+ /** The only transport dependency (AC-API-4). */
175
+ readonly transport: TransportContract;
176
+ readonly stores: ClientStores;
177
+ readonly relays: RelayOptions;
178
+ readonly verifier?: EventVerifier;
179
+ /**
180
+ * The application's decision on a staged proposal another member sent,
181
+ * asked before this client builds a commit carrying it (AC-INVITE-4).
182
+ * Omitted: a non-admin member's Add or Remove is rejected, every other
183
+ * proposal accepted. A `defer` lasts at most
184
+ * `options.proposalDeferralTimeoutMs` (then `reject`, `proposalExpired`).
185
+ */
186
+ readonly onProposal?: ProposalCallback;
187
+ /**
188
+ * Receives every inbox rumor `marmot` does not handle itself and no
189
+ * `registerInboxHandler` handler claimed — unmodified (AC-INBOX-2). Same
190
+ * delivery contract as an {@link InboxHandler}: at-least-once, so it MUST
191
+ * tolerate redelivery. Omitted: such rumors are dropped (`unhandled`).
192
+ *
193
+ * Handlers run on the inbox queue and block all inbox dispatch until they
194
+ * settle: do not await `group.send` or other long work — persist what you
195
+ * need and return, or fire-and-forget. Delivery is at-least-once; a throw
196
+ * counts toward the 10-retry cap and each retry re-decrypts the wrap.
197
+ */
198
+ readonly onApplicationRumor?: InboxHandler;
199
+ /**
200
+ * S10 (AC-HIST-3): the rumor history backend — where accepted application messages are retained for
201
+ * `group.history()`, withdrawn on a rewind and purged on teardown. Optional: live delivery
202
+ * (`group.onNotification`) never depends on it.
203
+ */
204
+ readonly history?: HistoryBackend;
205
+ /** S10 (AC-MEDIA-2): the media cache seam `encryptMedia`/`decryptMedia` keep ciphertexts in (no network, ever). */
206
+ readonly mediaCache?: MediaCache;
207
+ readonly options?: ClientOptions;
208
+ }
209
+ export interface MarmotClientEvents {
210
+ /** AC-INBOX-6: fires after the enrolment-approval transaction commits. */
211
+ enrolmentApproved: LifecycleEventPayloads['enrolmentApproved'];
212
+ /** AC-INBOX-6: fires after the forget transaction commits. */
213
+ deviceForgotten: LifecycleEventPayloads['deviceForgotten'];
214
+ /** AC-INBOX-6: fires after the created group's state and account index entry committed. */
215
+ groupCreated: LifecycleEventPayloads['groupCreated'];
216
+ /**
217
+ * A peer removed this device from the group and the removal settled (no longer revisable) — `{ groupId, actor? }`,
218
+ * `actor` the hex account identity of the admin whose removing commit was selected (as `group-disbanded` names it);
219
+ * absent when the committer cannot be resolved. The group and its history stay held, read-only; the application decides whether to `abandon()` it. Not fired for a
220
+ * removal this device requested (`leave()`, an own-leaf `devices.forget`, a teardown in progress or given up). At
221
+ * most once: a crash between the settle and the emit loses it (do not depend on it for correctness). A removal whose
222
+ * window passed while the client was not running is announced when the group is first loaded after the restart, so
223
+ * attach the listener before loading groups. A fenced group still announces its settled removal.
224
+ */
225
+ groupRemoved: {
226
+ readonly groupId: string;
227
+ readonly actor?: string;
228
+ };
229
+ /**
230
+ * Epic marmot-device-key-rotation (S7, AC-ROT-8): `devices.rotateKey()` committed its prepare transaction — `{ rotationId, from,
231
+ * to, groups }`. Fires once per rotation, never for a failed prepare, at most once across a crash (a crash between the commit
232
+ * and the emit loses it: do not depend on it for correctness).
233
+ */
234
+ deviceKeyRotated: LifecycleEventPayloads['deviceKeyRotated'];
235
+ /** Epic marmot-device-key-rotation (S7, AC-ROT-8): every group of the rotation is terminal — `{ rotationId, perGroupOutcome }`; fires once. */
236
+ deviceKeyRotationSettled: LifecycleEventPayloads['deviceKeyRotationSettled'];
237
+ /**
238
+ * S8 (AC-DEV-5, AC-DEV-9): an enrolment request of a new device of this
239
+ * account passed the replay, expiry and rate checks and is recorded — the
240
+ * approval prompt. Answer with `devices.approveEnrolment(requestId)`;
241
+ * `devices.pendingEnrolments()` lists the open ones.
242
+ */
243
+ enrolmentRequested: EnrolmentPrompt;
244
+ /** S8 (AC-KP-7): another account offered a KeyPackage for a group this client holds (recorded; see `invitations.offers()`). */
245
+ keyPackageOffered: KeyPackageOffer;
246
+ authFailed: {
247
+ readonly relayUrl: string;
248
+ readonly error: unknown;
249
+ };
250
+ /**
251
+ * marmot-transport-connected-signal: the transport adapter reported a (re)connect to `relayUrl` through
252
+ * `transportEvents.connected` — the raw relay string as reported (ADR-014). How an extension such as
253
+ * `account-sync` learns of reconnects without its own wiring into the adapter.
254
+ */
255
+ transportConnected: {
256
+ readonly relayUrl: string;
257
+ };
258
+ confirmBlocked: {
259
+ readonly groupId: string;
260
+ readonly intentId: string;
261
+ readonly error: unknown;
262
+ };
263
+ /**
264
+ * AC-HOOK-6, AC-BAR-2: an own commit was published although an `onBeforePublish` hook threw (`hook-error`), a
265
+ * barrier rejected (`barrier-failed`, with the `error`) or the `beforePublishTimeoutMs` deadline passed with a
266
+ * barrier pending (`barrier-timeout`). Best-effort by decision: the commit is never held back by a hook.
267
+ */
268
+ beforePublishSkipped: BeforePublishSkipped;
269
+ /**
270
+ * A relay is excluded from this group's history requests for the session
271
+ * (AC-PIPE-14): `timeout` — it caused `historySilenceThreshold` consecutive
272
+ * history timeouts; `no-progress` — for that many consecutive passes it
273
+ * answered, but with nothing inside the requested window (e.g. it ignores
274
+ * `until`), so the history walk could not advance past it.
275
+ */
276
+ relaySilent: {
277
+ readonly groupId: string;
278
+ readonly relayUrl: string;
279
+ readonly reason: 'timeout' | 'no-progress';
280
+ };
281
+ /**
282
+ * A relay returned a full page of history events all stamped with one
283
+ * second and then proved to hold more: events of that second beyond its
284
+ * cap cannot be paged to (NIP-01 `until` has one-second resolution) and
285
+ * may never be fetched from it. Fires once per relay and second per session.
286
+ */
287
+ historyGap: {
288
+ readonly groupId: string;
289
+ readonly relayUrl: string;
290
+ readonly createdAt: number;
291
+ };
292
+ storeIncompatible: {
293
+ readonly key: string;
294
+ readonly error: MarmotError;
295
+ };
296
+ /**
297
+ * A durable intent went `terminal` with no `send()` caller left to reject: resumed after reload (AC-PIPE-3), or
298
+ * accepted `awaiting-sync` and then fenced (`fenced`) or refused after its release (AC-PIPE-15).
299
+ */
300
+ intentFailed: {
301
+ readonly groupId: string;
302
+ readonly intentId: string;
303
+ readonly error: MarmotError;
304
+ };
305
+ /**
306
+ * A failed group operation could not roll the group's in-memory state back
307
+ * (`store-failed`, `cause` = the rollback failure); the group reloads its
308
+ * durable state before its next operation.
309
+ */
310
+ groupStateFailed: {
311
+ readonly groupId: string;
312
+ readonly error: MarmotError;
313
+ };
314
+ /**
315
+ * A Welcome delivery went `failed` (no inbox relay, every relay refused it,
316
+ * or `maxPublishAttempts` publishes failed); `group.retryWelcome(inviteeRef)`
317
+ * re-delivers it (S5). Reasons from a rewind: `commit-withdrawn` (the invite commit lost a race; the Welcome was not yet published) and
318
+ * `delivered-on-abandoned-branch` (additive, epic marmot-rewound-own-commit-no-signal S4: the Welcome WAS delivered, its invite
319
+ * commit was abandoned and NOTHING re-delivers it automatically -- fired only (a) for an invite re-drive's commit whose root a restore of the
320
+ * original just brought back (the invitee holds the re-drive's branch, which the group left), and (b) for an own invite whose withdrawal writes no
321
+ * re-drive record (unreadable diff, or a marker without changes). Decided once, in the abandoning transition: when a re-drive that was written
322
+ * later loses the change, the application hears `own-change-lost` `{ member-added }` with its reason instead, not this. Never when the library
323
+ * re-drives the invite (the new Welcome can move the invitee), for an enrolment approval it re-issues, or for a forget. `retryWelcome` on such a
324
+ * delivery is refused (`send-rejected`, `details.reason: 'abandoned-branch'`). The invitee may sit on a branch the group left: remove it and invite it again with a
325
+ * fresh KeyPackage; `retryWelcome` does not apply, nothing failed to publish).
326
+ */
327
+ welcomeFailed: {
328
+ readonly groupId: string;
329
+ readonly inviteeRef: string;
330
+ readonly reason: string;
331
+ };
332
+ /**
333
+ * A Welcome delivery that a rewind had failed (`welcomeFailed` with reason `commit-withdrawn`) was put back to
334
+ * `pending` because its invite commit is on the canonical path again; it is delivered in the background.
335
+ */
336
+ welcomeRestored: {
337
+ readonly groupId: string;
338
+ readonly inviteeRef: string;
339
+ };
340
+ /**
341
+ * Reconciling the group's undelivered invite Welcomes with a rewind (or with the stored window on load) failed;
342
+ * the deliveries are left as they were and the next load tries again.
343
+ */
344
+ welcomeReconcileFailed: {
345
+ readonly groupId: string;
346
+ readonly error: unknown;
347
+ };
348
+ /**
349
+ * S7 (AC-HYG-3): the invitee of a Welcome delivery declined it — a DECLINE rumor sealed by the delivery's
350
+ * invitee account, naming that Welcome's id (SHA-256 of the MLS Welcome) and group. Fires once per delivery,
351
+ * after it went `declined` durably (terminal: no further automatic or `retryWelcome` publish); a redelivered or
352
+ * repeated decline does not fire it again, nor does a decline from any other account. The rumor itself still
353
+ * reaches `onApplicationRumor` unchanged. `candidateId` (epic marmot-invitation-outcomes S3) is the delivery's
354
+ * stable candidate identity, the one `declineCandidate` and `invitations.declineCandidates()` carry. A decline
355
+ * whose `keyPackageRef` selects one delivery declines only that one; delivery status `declined` confers no cleanup
356
+ * authority — only the candidate's disposition does.
357
+ */
358
+ welcomeDeclined: {
359
+ readonly groupId: string;
360
+ readonly inviteeRef: string;
361
+ readonly candidateId: string;
362
+ };
363
+ /**
364
+ * Epic marmot-invitation-outcomes S3 (SC-13): the decline evidence of one locally issued delivery changed — a new
365
+ * candidate (`ambiguous` or `actionable`), a late match after the delivery's record left retention, or a
366
+ * refinement (a selector naming it after an ambiguous decline: `actionable`, `qualified`, a higher `rev`, the same
367
+ * `cleanupRef`). Fires after the evidence was written durably, at most once per `(candidateId, rev)`; a crash in
368
+ * between loses it — `invitations.declineCandidates()` recovers every candidate. Subscribe before scanning and
369
+ * deduplicate by `(candidateId, rev)`.
370
+ */
371
+ declineCandidate: DeclineCandidate;
372
+ /**
373
+ * Epic marmot-invitation-outcomes S5 (SC-12): the cleanup disposition of a candidate this session submitted, confirmed or saw
374
+ * withdrawn changed — `pending` once `removeAdmission` recorded it, `removed-revisable` once its own inline Remove confirmed,
375
+ * `removed-settled`, or back to `eligible` / `absent` when a rewind or a lost re-drive undid it. Best effort, after the change is
376
+ * durable: a crash, a restart or a listener added late can miss one — `invitations.cleanupDisposition(ref)` recovers the latest.
377
+ */
378
+ cleanupDisposition: CleanupDispositionReport;
379
+ /**
380
+ * What the inbox did with one inbound kind-1059 wrap (S6): `joined`,
381
+ * `already-member`, `pending` (an unexpected Welcome, see
382
+ * `invitations.pending()`), `no-matching-keypackage`, `rejected` (terminal,
383
+ * with `reason`), `deferred` (retried by the next inbox pass; a throwing
384
+ * handler's `handler-failed` counts toward the processing-failure cap),
385
+ * `delivered` (S7: a `registerInboxHandler` handler or `onApplicationRumor`
386
+ * took it, `to` saying which) or `unhandled` (nothing takes that rumor
387
+ * kind). A wrap already in the seen-set produces none.
388
+ */
389
+ inboxDisposition: InboxDisposition;
390
+ /**
391
+ * inbox-handler-time-budget: an inbox consumer callback (`surface`: a `registerInboxHandler` handler or
392
+ * `onApplicationRumor`) is still running `budgetMs` (`inboxHandlerBudgetMs`) after it was called for the rumor of
393
+ * `wrapId`. Diagnostic only — the handler keeps running and the inbox queue (Welcomes included) keeps waiting for
394
+ * it; fires at most once per call.
395
+ */
396
+ handlerSlow: {
397
+ readonly surface: 'inboxHandler' | 'onApplicationRumor';
398
+ readonly rumorKind: number;
399
+ readonly wrapId: string;
400
+ readonly budgetMs: number;
401
+ };
402
+ /**
403
+ * A proposal `onProposal` deferred passed its deadline
404
+ * (`proposalDeferralTimeoutMs` after `deferredAt`, its first deferral, in
405
+ * client-clock ms) and was treated as `reject`: dropped from the staged set
406
+ * (durably, before this fires), so own commits are no longer refused
407
+ * `proposal-deferred` and queued rumors go out after the next commit
408
+ * (AC-INVITE-4). Once per proposal; a crash between the drop and the emit
409
+ * still emits it (on the next evaluation, at the latest the reload), and a
410
+ * crash right after the emit may emit it once more with the same payload —
411
+ * deduplicate by `(groupId, proposalRef)`.
412
+ */
413
+ proposalExpired: {
414
+ readonly groupId: string;
415
+ readonly proposalRef: string;
416
+ readonly deferredAt: number;
417
+ };
418
+ /** A Welcome was joined (inbox auto-accept under `expectWelcome`, `accept(id)`), after the join committed. */
419
+ groupJoined: {
420
+ readonly groupId: string;
421
+ readonly invitationId: string;
422
+ };
423
+ /**
424
+ * A competing Welcome moved a group this client already held onto its branch (epic `marmot-welcome-race-joiner`):
425
+ * a second valid Welcome for the group named a branch the MIP-03 rule ranks above the held one, so the group was
426
+ * rebased onto it. `from` and `to` are the hex confirmation tags of the abandoned tip and of the Welcome's state;
427
+ * `invitationId` is the competing Welcome's. What the abandoned branch applied is withdrawn (`withdrawn`,
428
+ * `message-withdrawn` notifications) — messages sent on it are NOT re-sent; the application re-sends them. Fires
429
+ * once per switch (a crash between this report and the invitation's confirmation reports it again on the next pass:
430
+ * deduplicate by `invitationId`), also when the switch was decided in an inbox pass with no wrap in hand (the inbox
431
+ * disposition `branch-switched` is reported only when the switch ran inside a Welcome's dispatch); `groupJoined`
432
+ * does not fire again.
433
+ */
434
+ groupBranchSwitched: {
435
+ readonly invitationId: string;
436
+ readonly groupId: string;
437
+ readonly from: string;
438
+ readonly to: string;
439
+ };
440
+ /**
441
+ * An invitation's maintenance — rotate-after-consume of the consumed
442
+ * KeyPackage, the decline rumor's delivery, or completing an interrupted
443
+ * join — failed permanently 10 times (the signer or user refused, a
444
+ * malformed record) and is given up: no further retries or signer prompts.
445
+ */
446
+ maintenanceFailed: {
447
+ readonly invitationId: string;
448
+ readonly kind: MaintenanceKind | DeviceMaintenanceKind;
449
+ readonly reason: string;
450
+ /** `enrolment-approval` only: the groups the device joined before the approval was given up (enrolmentApproved names them too). */
451
+ readonly groups?: readonly string[];
452
+ };
453
+ }
454
+ export type MarmotClientEventName = keyof MarmotClientEvents;
455
+ /** What `group.send()` accepts: an application rumor, a proposal, a commit of pending proposals, or a self-update. */
456
+ export type GroupIntent = {
457
+ readonly type: 'application';
458
+ readonly rumor: Rumor;
459
+ } | {
460
+ readonly type: 'proposal';
461
+ readonly proposal: unknown;
462
+ } | {
463
+ readonly type: 'commit';
464
+ } | {
465
+ readonly type: 'self-update';
466
+ };
467
+ /** Per-event ingest outcome (AC-PIPE-4..7). */
468
+ export type IngestDisposition = {
469
+ readonly kind: 'applied';
470
+ readonly eventId: string;
471
+ } | {
472
+ readonly kind: 'application';
473
+ readonly eventId: string;
474
+ readonly rumor: Rumor;
475
+ readonly orderingKey: OrderingKey;
476
+ } | {
477
+ readonly kind: 'duplicate';
478
+ readonly eventId: string;
479
+ } | {
480
+ readonly kind: 'retryable';
481
+ readonly eventId: string;
482
+ readonly reason: string;
483
+ } | {
484
+ readonly kind: 'rejected';
485
+ readonly eventId: string;
486
+ readonly reason: string;
487
+ };
488
+ export type { OrderingKey } from '../history/index.js';
489
+ export type { GroupSnapshot } from './group-snapshot.js';
490
+ export type { InboxRumorDelivery } from './inbox-send.js';
491
+ /** `MarmotGroup.disbanded`: the selected disband (the `group-disbanded` notification's fields). */
492
+ export interface GroupDisbanded {
493
+ /** Hex account identity of the admin whose disband commit was selected. */
494
+ readonly actor: string;
495
+ /** The MLS epoch the disband commit was made at (its parent's epoch). */
496
+ readonly epoch: bigint;
497
+ /** Hex MLS confirmation tag of that parent state. */
498
+ readonly nodeTag: string;
499
+ /** Hex digest of the selected disband commit. */
500
+ readonly commitDigest: string;
501
+ /** Client-clock milliseconds at which this client recorded the settlement. */
502
+ readonly at: number;
503
+ }
504
+ export interface PendingIntent {
505
+ readonly intentId: string;
506
+ /**
507
+ * `awaiting-sync` (AC-PIPE-15): accepted by `send()` after the group was loaded, before its first post-load sync
508
+ * completed — nothing has been encrypted for it yet. Released (encrypted and published) once that sync completes;
509
+ * failed `fenced` via `intentFailed`, never published, when the sync fences the group (AC-HIST-4).
510
+ */
511
+ readonly state: 'pending-publish' | 'pending-confirm' | 'queued' | 'awaiting-sync';
512
+ /** The `GroupIntent` type the record was created for. */
513
+ readonly kind: GroupIntent['type'];
514
+ }
515
+ export type { AppliedNotification, GroupDisbandedNotification, GroupNotification, HistoryBackend, HistoryEntry, LeafEquivocationNotification, MessageNotification, MessageWithdrawnNotification, WithdrawnNotification, } from '../history/index.js';
516
+ /**
517
+ * Why an `onConfirm` hook runs (AC-MX-1): the confirmed own intent's `GroupIntent` type, or `'create'` /
518
+ * `'join'` for a group this client just created (`groups.create`) or adopted from a Welcome. Its own union —
519
+ * `GroupIntent['type']` (what `send()` accepts) is not widened.
520
+ */
521
+ export type ConfirmKind = GroupIntent['type'] | 'create' | 'join';
522
+ /**
523
+ * What an `onConfirm` hook receives. It runs INSIDE the transaction that persists the group state —
524
+ * a confirmation's, `groups.create`'s (`kind: 'create'`) or a Welcome adoption's (`kind: 'join'`, only when
525
+ * the adoption wrote the group): writes through `tx` commit atomically with that state, and a throw aborts the
526
+ * whole transaction — the confirmation (retried, AC-PIPE-2, AC-PIPE-13), the creation (`groups.create` rejects
527
+ * with the hook's error, nothing is stored) or the adoption (nothing is stored; the join is completed by a later
528
+ * inbox pass). Use `tx`, never the store itself (storage re-entrancy rule). Never run for a foreign commit's
529
+ * ingest, nor for a `groups.restore` adoption: a restore produces no `'create'`/`'join'` — its first hook run is
530
+ * the confirmation of the restore's own self-update (`kind: 'self-update'`).
531
+ */
532
+ export interface ConfirmContext {
533
+ readonly groupId: string;
534
+ /** The confirmed intent's id; the group id for `'create'` / `'join'`. */
535
+ readonly intentId: string;
536
+ readonly kind: ConfirmKind;
537
+ /** Epoch of the persisted state. */
538
+ readonly epoch: bigint;
539
+ readonly tx: GroupStoreTx;
540
+ /** Notifications the confirmed commit produces (empty for application messages, `'create'` and `'join'`). */
541
+ readonly notifications: readonly AppliedNotification[];
542
+ /**
543
+ * AC-MX-1: the state this transaction persists (with its retained rewind window), as an opaque enveloped
544
+ * {@link GroupSnapshot} — what `groups.restore(groupId, snapshot)` needs to resume as this leaf. Store it
545
+ * through `tx` to keep it atomic with the state it describes. Built lazily on the first read and memoized (a
546
+ * hook that never reads it costs no serialization); readable only while the hooks run — a first read after the
547
+ * hook returned throws `transaction-closed`.
548
+ */
549
+ readonly snapshot: GroupSnapshot;
550
+ /**
551
+ * AC-MX-6: set only on the confirmation of the commit `devices.forget` issues to remove another device's leaves
552
+ * from this group — the signature keys (hex) of the leaves it removes. Present while the hooks run, so a hook can
553
+ * act before anything of this confirmation leaves the device: `deviceForgotten` fires only once every group of
554
+ * the forget is settled, after this confirmation's own hooks (and the publishes they scheduled) ran.
555
+ */
556
+ readonly forgetting?: {
557
+ readonly leafKeys: readonly string[];
558
+ };
559
+ }
560
+ export type ConfirmHook = (confirmation: ConfirmContext) => void | Promise<void>;
561
+ export interface LeafInfo {
562
+ readonly leafIndex: number;
563
+ readonly leafKey: string;
564
+ }
565
+ export type { EncryptedMedia, EncryptMediaOptions, MediaCache } from '../media/index.js';
566
+ export type { AvailabilityEndReason, AvailabilityObservation, FenceCause, GroupAvailability } from './group-availability.js';
567
+ export interface MarmotGroup {
568
+ readonly id: string;
569
+ readonly nostrGroupId: string;
570
+ readonly name: string;
571
+ /** The group's description (`marmot.group.profile.v1`); `''` for a group created without one. Changes with a committed `rename`. */
572
+ readonly description: string;
573
+ readonly admins: readonly string[];
574
+ readonly relays: readonly string[];
575
+ readonly epoch: bigint;
576
+ /**
577
+ * The peer disband that ended this group, once the convergence settlement selected it (BACKLOG
578
+ * `marmot-disband-settled-store-divergence`) — `undefined` while the group is live. Durable: a reload keeps it.
579
+ * A disbanded group does not sync, rejects input (`rejected`, reason `group-disbanded`) and refuses `send` and the
580
+ * other own-commit operations as well as `synced()` with `not-a-member` (details `reason: 'disbanded'`); reads,
581
+ * `history()`, `equivocations()` and `abandon()` / `destroy()` still work. The stored state stays the disband's
582
+ * parent (`epoch` does not move). Announced once by a `group-disbanded` notification.
583
+ */
584
+ readonly disbanded: GroupDisbanded | undefined;
585
+ /**
586
+ * Intent -> publish -> confirm (AC-PIPE-1..3). An application rumor sent while proposals are staged
587
+ * is queued and resolves once published after the next confirmed commit (AC-INVITE-3); queued
588
+ * rumors go out in order, and one queued before an `invite()` is released at that commit's new
589
+ * epoch — readable by the new invitee. When the commit the queue makes goes terminal, it emits
590
+ * `intentFailed` and the send that triggered it rejects `send-rejected`; the rumor stays queued.
591
+ *
592
+ * AC-PIPE-15: on a group handle obtained by loading stored state (`groups.get`/`groups.list`), a send issued
593
+ * before the group's first post-load sync completed resolves once the intent is durably recorded
594
+ * `awaiting-sync` — nothing is encrypted yet (the stored state may be a restored, rolled-back snapshot). It
595
+ * is encrypted and published once that sync completes; its terminal failure is reported by `intentFailed`
596
+ * (`fenced` when the sync fences the group, AC-HIST-4).
597
+ */
598
+ send(intent: GroupIntent): Promise<void>;
599
+ /**
600
+ * AC-PIPE-15: resolves once the group has completed its first sync since this client loaded it — every group
601
+ * relay returned EOSE or was excluded as silent (AC-PIPE-14); at once for a group this client instance created
602
+ * or joined, or that already synced. Until then `send()` records `awaiting-sync` intents and `invite`,
603
+ * `setAdmins`, `rename`, `removeMember`, `departAsAdmin`, `leave` and `devices.forget` are refused `commit-pending` (reason
604
+ * `awaiting-sync`). Never settles while no sync can complete (offline). Rejects `fenced` when the group is or
605
+ * becomes fenced (AC-HIST-4), `disposed` / `not-a-member` when the client is disposed / the group abandoned, and
606
+ * `no-lease` when the stores lost their lease before the group's first catch-up (at once once the loss is known,
607
+ * else when a background retry meets it; epic marmot-invitation-outcomes S1).
608
+ */
609
+ synced(): Promise<void>;
610
+ /**
611
+ * Epic marmot-invitation-outcomes (S1, SC-10): observes the group's availability — the fence, the sync state and the
612
+ * membership as independent facts, and whether an own write may be attempted now. The current snapshot is delivered
613
+ * synchronously, before this returns, then every change in the order it happened, each with a strictly increasing
614
+ * `seq`. A fence is an ordinary observation: the subscription stays open (no fence is ever lifted in place, so within
615
+ * a client session no `clear` follows `fenced` — not even after a failed fence-marker write and the reload that
616
+ * follows). Exactly one `ended` closes it, with `final.writable` `false` (a fenced group stays fenced in it): reason
617
+ * `torn-down` (leave, abandon, destroy, or another teardown purge), `restore-undone` (a failed restore taken back),
618
+ * `disposed` (the client), `no-lease` (the account store's lease was released, closed or lost — immediately when the
619
+ * store implements `AccountStore.onLeaseEnded`). After that, a subscription gets the one `ended` at once and nothing
620
+ * more; this method itself never throws for a fenced, torn-down or disposed group. Exempt from the fenced refusal.
621
+ * Change notifications run outside every library frame (a listener may start group operations, which queue); what
622
+ * is delivered before this returns runs in the caller's own frame — subscribed from inside a library callback (an
623
+ * `onConfirm` hook, a store, …), a same-group operation the listener starts there is rejected `reentrant`, as one
624
+ * the callback started itself would be. A throwing listener is ignored. Returns the unsubscribe function (idempotent): no callback follows it. `invalid-options` when `listener`
625
+ * is not a function.
626
+ */
627
+ observeAvailability(listener: (observation: AvailabilityObservation) => void): () => void;
628
+ ingest(events: readonly NostrEvent[]): Promise<readonly IngestDisposition[]>;
629
+ /**
630
+ * The durable outbound intents, read directly — NOT serialised behind the group's operation queue: an intent can
631
+ * vanish from the list a moment before `epoch` reflects its confirmed commit (the confirmation transaction deletes
632
+ * the record, then the confirming operation applies the state). Every group operation runs on that per-group queue,
633
+ * so `await group.ingest([])` afterwards is a barrier: once it resolves the confirmation is fully applied.
634
+ */
635
+ pendingIntents(): Promise<readonly PendingIntent[]>;
636
+ members(): readonly string[];
637
+ memberCount(): number;
638
+ leaves(account: string): readonly LeafInfo[];
639
+ /**
640
+ * One commit adding every KeyPackage, then one Welcome per invitee; resolves with each invitee's
641
+ * Welcome outcome (AC-INVITE-1/2). Rumors queued before it (AC-INVITE-3) are released at the
642
+ * invite commit's new epoch, so the invitees can read them.
643
+ *
644
+ * Fork loss: a withdrawn invite commit is re-driven automatically from the retained KeyPackage events (`welcomeFailed`
645
+ * `commit-withdrawn`, `own-change-withdrawn` `{ member-added }`, then `own-change-reapplied` or `own-change-lost`); the re-driven
646
+ * Welcome has a new `inviteId` and the same `inviteeRef`. A manual re-invite of the same KeyPackage after the re-drive is refused
647
+ * `send-rejected` (the engine rejects a second leaf under that signature key); wait for the terminal.
648
+ */
649
+ invite(keyPackages: readonly NostrEvent[]): Promise<readonly WelcomeOutcome[]>;
650
+ /**
651
+ * Re-wraps and re-publishes `inviteeRef`'s Welcome (its KeyPackageRef) — never a new commit (AC-INVITE-2). A delivery marked
652
+ * `welcomeFailed` `delivered-on-abandoned-branch` is refused `send-rejected` (`details.reason: 'abandoned-branch'`): remove the
653
+ * member and invite it again with a fresh KeyPackage.
654
+ */
655
+ retryWelcome(inviteeRef: string): Promise<WelcomeOutcome>;
656
+ activeAdmins(): readonly string[];
657
+ isActiveAdmin(account: string): boolean;
658
+ isLastActiveAdmin(account: string): boolean;
659
+ /**
660
+ * Sets the admin list in ONE durable commit. Fork loss: re-driven per account (only the flips nobody else changed since the fork
661
+ * point survive, applied to the current tip's list); reported through `own-change-*` (`{ admin }` changes). `departAsAdmin`'s demotion
662
+ * commit is re-driven the same way; if the device's own leave lands first the flip is lost `stranded`.
663
+ */
664
+ setAdmins(accounts: readonly string[]): Promise<void>;
665
+ /**
666
+ * Renames the group: ONE admin commit that replaces the group profile (`marmot.group.profile.v1`: name AND
667
+ * description). `description` omitted keeps the CURRENT description; `description: ''` clears it. An omitted
668
+ * description is resolved when the call is made and stored by value. A concurrent change is never merged: if another
669
+ * admin's profile commit is applied before this commit is built, the rename rejects `send-rejected` (stale epoch) and
670
+ * that profile stands; in a same-epoch race the fork rule keeps one whole profile. An unchanged profile still
671
+ * commits. `onConfirm` hooks see `kind: 'commit'`.
672
+ *
673
+ * Refusals, each with nothing recorded and the epoch unchanged: `invalid-options` for a `name` that is not a
674
+ * non-empty string of at most 256 UTF-8 bytes or a `description` that is not a string of at most 4096 UTF-8 bytes
675
+ * (byte limits, not character counts); `invalid-options` with `details.reason: 'not-admin'` for a caller that is
676
+ * not an admin (a non-admin proposes the rename instead: send `{ type: 'proposal', proposal:
677
+ * groupProfileProposal(...) }` and let an admin send `{ type: 'commit' }`); `commit-pending` while an own commit
678
+ * is pending. A caller that is not a member, or whose pre-sync gate is closed, is refused first, as for every own
679
+ * commit (`not-a-member`, `commit-pending` with `details.reason: 'awaiting-sync'`). An admin demoted between the
680
+ * call and the build is rejected `send-rejected`, like `setAdmins`.
681
+ *
682
+ * Fork loss: re-driven per component; if anyone else changed the profile since the fork point it is lost `concurrent-change`
683
+ * (never merged) and reported through `own-change-*`.
684
+ *
685
+ * While a group-profile (`0x8001`) proposal is staged on the group (another member's, or one of your own), `rename`
686
+ * is rejected `send-rejected` (`details.reason: 'staged-profile-update'`) with nothing recorded and the state
687
+ * unchanged, because a commit that carried the staged proposal and this rename would hold two profile updates;
688
+ * commit the staged proposal first (`send({ type: 'commit' })`).
689
+ */
690
+ rename(name: string, options?: {
691
+ readonly description?: string;
692
+ }): Promise<void>;
693
+ /**
694
+ * Removes `account`: ONE admin commit that removes every leaf the account holds when the commit is built (the stored intent
695
+ * names the account). An admin may remove another admin in the same commit, with no demotion first: the engine's coupling
696
+ * splice drops the removed admin's entry atomically.
697
+ *
698
+ * Refusals, nothing recorded, epoch unchanged: `invalid-options` with `details.reason` `'malformed-account'`, `'self'`
699
+ * (use `departAsAdmin()` or `leave()`) or `'not-admin'`; `commit-pending` while an own commit is pending; `not-a-member` /
700
+ * `commit-pending` (`awaiting-sync`) first, as for every own commit. An account that holds no leaf (never a member, or
701
+ * already removed) resolves as a no-op. An admin demoted between the call and the build is rejected `send-rejected`.
702
+ *
703
+ * Staged proposals: a staged Remove or SelfRemove of the account's leaf is skipped (carried by reference). `send-rejected`,
704
+ * nothing recorded, when a staged Add admits a leaf of the account (`'staged-add-of-removed-account'`), when a staged Update
705
+ * names the account's leaf, or when a staged admin-list change still names a removed admin
706
+ * (`'staged-admin-policy-update'`): commit the staged proposal first (`send({ type: 'commit' })`) and retry. A staged
707
+ * admin-list change is committed together with the removal.
708
+ *
709
+ * Removed side (Q1 option a): each device keeps a tombstoned group (read-only, `members()` without the account, own
710
+ * commits refused `not-a-member`); its own group emits no `leaf-removed` notification (the remaining members' groups do).
711
+ * The app calls `abandon()` / `destroy()`. Success is final once the commit is canonical, or re-driven: if a same-epoch fork loss withdraws it, this device (only it)
712
+ * re-checks the removal against the winning tip and re-drives it as a fresh commit; the application hears `own-change-withdrawn`
713
+ * `{ member-removed }`, then `own-change-reapplied` or `own-change-lost` (`already-applied`, `reversed`, `concurrent-change`, `not-admin`,
714
+ * `stranded`, `attempts-exhausted`). `leaf-removal-withdrawn` is unchanged. A record that outlives a concurrent remove-and-re-add of the same device by another admin removes the account again.
715
+ */
716
+ removeMember(account: string): Promise<void>;
717
+ /**
718
+ * Epic marmot-invitation-outcomes S5 (SC-11): removes exactly the ONE admission a declined delivery made — the leaf position the
719
+ * candidate's proven original Add put in this group — by `ref`, the candidate's cleanup reference. A reference confers no
720
+ * authority: every call re-derives the disposition from durable evidence and lineage.
721
+ *
722
+ * Resolves with a {@link CleanupDispositionReport}: `pending` (with the root `intentId`) when the cleanup was durably accepted —
723
+ * or was already in flight: a repeated, concurrent or lost-reply submit coalesces with it, with no resume, transport call or write
724
+ * — and otherwise the current disposition when it is not `eligible` (`removed-revisable`, `removed-settled`, `absent`,
725
+ * `insufficient-evidence`; nothing is recorded). An accepted cleanup is built, published and confirmed in the background; its
726
+ * commit re-checks the target on the actual parent and is dropped (never removing a replacement) when it no longer holds.
727
+ *
728
+ * Refusals enqueue nothing: `fenced`, `not-a-member` (`disbanded`), `invalid-options` (`details.reason`
729
+ * `malformed-reference`, `foreign-reference` — another account than the signer's or another group —, `unknown-reference`,
730
+ * `self` — the committer's own leaf; another device of the own account is a valid target —, `not-admin`), `confirm-blocked`,
731
+ * `commit-pending` (another own commit pending, or `awaiting-sync`: retryable), `send-rejected` with `details.retryable` for a
732
+ * staged proposal in the way (`staged-add-conflict`, `staged-removal-of-target`, `staged-admin-policy-update` — the last leaf of an
733
+ * admin account gets the account removal's admin coupling). After an uncertain failure, read
734
+ * `invitations.cleanupDisposition(ref)` before resubmitting.
735
+ *
736
+ * Fork loss: a withdrawn cleanup reads `pending` until its library re-drive ends; the application hears `own-change-withdrawn`
737
+ * `{ admission-removed }` (never `member-removed`), then `own-change-reapplied` or `own-change-lost` with the existing reasons. It is
738
+ * never re-driven as an account-wide removal.
739
+ */
740
+ removeAdmission(ref: CleanupReference): Promise<CleanupDispositionReport>;
741
+ departAsAdmin(): Promise<void>;
742
+ leave(): Promise<void>;
743
+ abandon(): Promise<void>;
744
+ destroy(): Promise<void>;
745
+ /**
746
+ * Encrypts `bytes` as `encrypted-media-v1` under the current epoch's key (AC-MEDIA-1): `{ ciphertext, imeta,
747
+ * locator }` — `locator` the ciphertext's SHA-256 (hex), under which the media cache (if configured) keeps it.
748
+ * Nothing is uploaded: the application stores the ciphertext (e.g. Blossom) and sends a rumor carrying `imeta`.
749
+ */
750
+ encryptMedia(bytes: Uint8Array, options?: EncryptMediaOptions): Promise<EncryptedMedia>;
751
+ /**
752
+ * Decrypts media described by `media.imeta`, trying every epoch the group retains. An empty `ciphertext` is
753
+ * looked up in the media cache by `locator` (`invalid-options` / `not-found` when absent).
754
+ */
755
+ decryptMedia(media: EncryptedMedia): Promise<Uint8Array>;
756
+ /** The retained application rumors (the history backend's, in delivery order); none without a backend (AC-HIST-3). */
757
+ history(): AsyncIterable<Rumor>;
758
+ /**
759
+ * Live notifications (AC-HIST-2/3), each after the state it describes was persisted: `applied` / `withdrawn`
760
+ * (a commit's state changes, keyed by its digest; a rewind withdraws them under the same digest), `message`
761
+ * (an accepted application message with its `OrderingKey`) and `message-withdrawn`. Also `own-change-withdrawn` (at most once)
762
+ * and `own-change-reapplied` / `own-change-lost` (at least once, retained until the group's first listener) for own commits a fork
763
+ * loss withdrew. Returns an unsubscribe.
764
+ */
765
+ onNotification(listener: (notification: GroupNotification) => void): () => void;
766
+ /**
767
+ * Every leaf equivocation this member has recorded for the group (ADR-016) — the durable source of truth behind the
768
+ * live `leaf-equivocation` notification, which is a hint delivered at most once per `(nodeTag, leafIndex)` and lost
769
+ * when no listener is attached or the process ends before dispatch. Ordered by `(epoch, nodeTag, leafIndex)`;
770
+ * `[]` when none. A direct read of the group store (not serialised behind the group's operation queue), available
771
+ * on a fenced group; rejects `disposed` / `not-a-member` like every other accessor.
772
+ */
773
+ equivocations(): Promise<readonly LeafEquivocationNotification[]>;
774
+ }
775
+ export interface WelcomeManifest {
776
+ /** Hex MLS group id. */
777
+ readonly groupId: string;
778
+ /** Hex KeyPackageRef of the local KeyPackage the Welcome must consume. */
779
+ readonly keyPackageRef: string;
780
+ /** The account expected to send the Welcome (a member of the group). */
781
+ readonly sponsorAccount: string;
782
+ /** Client-clock milliseconds; a Welcome processed at or after it is not auto-accepted. */
783
+ readonly deadline: number;
784
+ }
785
+ /**
786
+ * A `registerInboxHandler` handler (and the shape of `onApplicationRumor`):
787
+ * receives the rumor as unwrapped and its kind-1059 wrap, both frozen.
788
+ *
789
+ * Handlers run on the inbox queue and block all inbox dispatch (Welcomes
790
+ * included) until they settle: do not await `group.send` or other long work —
791
+ * `send` resolves only once published, which can take as long as the next
792
+ * admin commit or a remote signer's approval. Persist what you need and
793
+ * return, or fire-and-forget.
794
+ *
795
+ * Delivery is at-least-once — the wrap is marked seen only after the handler
796
+ * resolved, so a crash or reload in between, or the wrap id's eviction from
797
+ * the bounded seen-set, redelivers the rumor: handlers MUST tolerate
798
+ * redelivery (AC-INBOX-4). A throw counts toward the 10-retry cap (then the
799
+ * wrap is dropped, `rejected('processing-failed')`) and each retry
800
+ * re-decrypts the wrap. Account-scope client operations called from inside a
801
+ * handler reject `reentrant` (ADR-013).
802
+ */
803
+ export type InboxHandler = InboxRumorHandler;
804
+ export interface MarmotClient {
805
+ /** The account-key signer: the construction `signer` behind `withSignerBudget(signer, budget)`. Every account-key call goes through it. */
806
+ readonly signer: Signer;
807
+ /** Same value as the module export `permissions` (AC-API-7). */
808
+ readonly permissions: PermissionDeclaration;
809
+ readonly groups: {
810
+ create(name: string, options?: {
811
+ readonly relays?: readonly string[];
812
+ readonly admins?: readonly string[];
813
+ }): Promise<MarmotGroup>;
814
+ get(groupId: string): Promise<MarmotGroup | undefined>;
815
+ list(): Promise<readonly MarmotGroup[]>;
816
+ /**
817
+ * AC-MX-2: resumes as the leaf `snapshot` (an `onConfirm` hook's `ConfirmContext.snapshot`) was taken from:
818
+ * adopts it with its rewind window, runs the group's first sync (replaying every commit since from the group
819
+ * relays), commits a self-update and resolves the handle only once that self-update is confirmed — so the
820
+ * relays hold it before any application message from this client. Rejects `envelope-mismatch` (another engine
821
+ * / ts-mls build — a snapshot is restorable only by the build that took it —, or not a well-formed snapshot:
822
+ * a serialized state of another group than its payload names, a rewind window that is no tree below its tip
823
+ * within the rollback horizon), `invalid-options` (a snapshot whose serialized MLS state is of another group
824
+ * than `groupId`), `already-member` (the group is held or being restored) and
825
+ * `reentrant` (from an account-scope surface or a group's `onConfirm` hook) before anything is written; any
826
+ * later failure (`fenced` — also when the group is fenced after its first sync —, `not-a-member` — torn down
827
+ * meanwhile —, `send-rejected`, `disposed`) removes the adopted group again. Until it settles, `groups.get`
828
+ * of it waits (rejecting `reentrant` from inside a consumer surface) and `groups.list` skips it. Never settles
829
+ * while no sync can complete (offline), like `MarmotGroup.synced()`.
830
+ */
831
+ restore(groupId: string, snapshot: GroupSnapshot): Promise<MarmotGroup>;
832
+ };
833
+ readonly keyPackages: {
834
+ create(options?: {
835
+ readonly relays?: readonly string[];
836
+ readonly lastResort?: boolean;
837
+ }): Promise<NostrEvent>;
838
+ list(): Promise<readonly NostrEvent[]>;
839
+ count(): Promise<number>;
840
+ rotate(ref: string): Promise<NostrEvent>;
841
+ forget(ref: string): Promise<void>;
842
+ observe(account: string, listener: (event: NostrEvent) => void): () => void;
843
+ /**
844
+ * S8 (AC-KP-7): mints a fresh KeyPackage and offers it to sponsor `to` for
845
+ * `groupId` — a gift-wrapped offer rumor on `to`'s inbox relays; the group
846
+ * id never appears outside the wrap.
847
+ */
848
+ offer(options: {
849
+ readonly groupId: string;
850
+ readonly to: string;
851
+ }): Promise<{
852
+ readonly offerId: string;
853
+ readonly keyPackageEvent: NostrEvent;
854
+ }>;
855
+ };
856
+ readonly invitations: {
857
+ expectWelcome(manifest: WelcomeManifest): Promise<void>;
858
+ pending(): Promise<readonly PendingInvitation[]>;
859
+ accept(id: string): Promise<MarmotGroup>;
860
+ decline(id: string, options?: {
861
+ readonly declineRumor?: boolean;
862
+ }): Promise<void>;
863
+ /** S8: KeyPackage offers received for groups this client holds (optionally one group's), oldest first; admit one with `group.invite([offer.keyPackageEvent])`. */
864
+ offers(groupId?: string): Promise<readonly KeyPackageOffer[]>;
865
+ /**
866
+ * Epic marmot-invitation-outcomes S2: whether THIS invitation (a Welcome id) caused this device to join its group,
867
+ * read from durable evidence at one instant (ADR-019 D7, D9) — authoritative where `accept(id)` is not (an
868
+ * `accept` may return the held group's handle for a Welcome that was kept out). Runs on the inbox queue (behind the
869
+ * current inbox task) and works before `inbox.start()`. Rejects `reentrant` synchronously from inside an `onConfirm`
870
+ * / `onBeforePublish` / `verifier` / `onProposal` hook, an inbox handler, `onApplicationRumor` or any account-scope
871
+ * consumer surface — read it from an event listener (e.g. `groupJoined`) instead.
872
+ */
873
+ outcome(id: string): Promise<InvitationOutcome>;
874
+ /**
875
+ * Epic marmot-invitation-outcomes S3 (SC-13): one page of the locally issued deliveries their invitee's account
876
+ * declined, recovered offline from this account store alone (no group is opened). Read-only: no publication, no
877
+ * intent, no pruning, no store write. Pages are ordered and bounded (`limit` clamped to `[1, 256]`, default 256);
878
+ * pass the previous page's `next` as `after` until `complete`. Each candidate appears at most once across the
879
+ * pages of one walk; one recorded meanwhile surfaces through the `declineCandidate` event — register it first.
880
+ * Rejects `reentrant` synchronously from inside an account-scope consumer surface (a store, signer or verifier
881
+ * call); allowed from group hooks, inbox handlers and event listeners.
882
+ */
883
+ declineCandidates(options?: {
884
+ readonly after?: string;
885
+ readonly limit?: number;
886
+ }): Promise<DeclineCandidatePage>;
887
+ /**
888
+ * Epic marmot-invitation-outcomes S4 (SC-12): what this store's durable evidence proves about the admission a
889
+ * declined delivery made, by the candidate's cleanup reference — `eligible` (the proven original admission is
890
+ * present), `absent` (`add-off-path`: its Add is not on the selected path; `occupancy-ended`: the admission
891
+ * ended), or `insufficient-evidence` (`unresolved-selector`, `ambiguous-legacy`, `no-anchor`, `lineage-gap`).
892
+ * Read-only and offline: no group runtime, no publication, no intent, no store write; recompute it after branch
893
+ * changes. On a fenced group it still answers, with the last disposition the store proved (`lastKnown: true`).
894
+ * Rejects `invalid-options` (`details.reason`: `malformed-reference`, `foreign-reference` — another account than
895
+ * the signer's —, `unknown-reference`) with no effect. Rejects `reentrant` synchronously from inside an
896
+ * `onConfirm` / `onBeforePublish` / `verifier` / `onProposal` hook, a consumer group-store call or any
897
+ * account-scope consumer surface other than an inbox handler; allowed from inbox handlers and event listeners.
898
+ * Since S5 it also reads `pending` (a cleanup durably accepted, or a library re-drive of a withdrawn one, under the
899
+ * root `intentId`) and `removed-revisable` / `removed-settled` (the cleanup's own confirmed inline Remove, `commitDigest`).
900
+ */
901
+ cleanupDisposition(ref: CleanupReference): Promise<CleanupDispositionReport>;
902
+ };
903
+ readonly inbox: {
904
+ start(): Promise<void>;
905
+ stop(): Promise<void>;
906
+ };
907
+ /** S8: the account's devices (one leaf signature key per client instance) and same-account enrolment (ADR-003). */
908
+ readonly devices: {
909
+ list(): Promise<readonly DeviceInfo[]>;
910
+ requestEnrolment(options: EnrolmentRequestOptions): Promise<EnrolmentRequestHandle>;
911
+ pendingEnrolments(): Promise<readonly EnrolmentPrompt[]>;
912
+ /**
913
+ * Approves a prompted enrolment request (ADR-003). Call it from application (UI) code: from inside an
914
+ * inbox handler or `onApplicationRumor` it inherits their account-scope frame and its `group.invite`
915
+ * rejects `reentrant` (ADR-013).
916
+ */
917
+ approveEnrolment(requestId: string): Promise<EnrolmentApprovalOutcome>;
918
+ label(leafKey: string, label: string): Promise<void>;
919
+ forget(leafKey: string): Promise<DeviceForgetOutcome>;
920
+ /**
921
+ * Epic marmot-device-key-rotation (S7): re-keys this device. A fresh device signing key (its account identity proof signed
922
+ * once) becomes the device key in one transaction; every held group's own leaf is then re-keyed to it (a self-update commit
923
+ * per group), the KeyPackages signed with the old key are replaced and deleted, and `deviceKeyRotationSettled` fires when
924
+ * every group is terminal. Resolves after the prepare committed and one pass drove every group (`settled` tells whether it
925
+ * is finished; the rest continues in the background and after a restart). A rotation already open is returned. Rejects
926
+ * `invalid-options` with `details.reason`: `no-device-key` (nothing minted, no group), `device-forgetting` (this device's
927
+ * own forget is open), `rotation-unavailable`.
928
+ */
929
+ rotateKey(): Promise<DeviceKeyRotationOutcome>;
930
+ /** The open rotation, else the last one (`status`: `rotating` / `rotated` / `gave-up`); `undefined` when the device never rotated. */
931
+ rotation(): Promise<DeviceKeyRotationOutcome | undefined>;
932
+ };
933
+ readonly extensions: {
934
+ /**
935
+ * Routes every inbox rumor of `kind` to `handler` instead of
936
+ * `onApplicationRumor` (AC-INBOX-5); `handler-exists` / `reserved-kind`.
937
+ * Handlers run on the inbox queue and block all inbox dispatch until they
938
+ * settle: do not await `group.send` or other long work — persist what you
939
+ * need and return, or fire-and-forget. Delivery is at-least-once; a throw
940
+ * counts toward the 10-retry cap and each retry re-decrypts the wrap.
941
+ */
942
+ registerInboxHandler(kind: number, handler: InboxHandler): () => void;
943
+ onConfirm(hook: ConfirmHook): () => void;
944
+ /**
945
+ * AC-HOOK-1: registers a hook that runs for every own `commit` / `self-update` between its staging and its first
946
+ * publish, in its own transaction, handed the pending-tagged snapshot of the state the commit produces; the
947
+ * `PublishBarrier` it may return is awaited (best-effort, `beforePublishTimeoutMs`) before the publish. Returns
948
+ * the unregister function; throws `disposed` on a disposed client. A hook that throws, a barrier that rejects or
949
+ * times out never holds the commit back (`beforePublishSkipped`). From inside the hook or the barrier, a mutating
950
+ * operation on the group, `groups.restore`, `devices.*` and `sendInboxRumor` reject `reentrant`.
951
+ */
952
+ onBeforePublish(hook: BeforePublishHook): () => void;
953
+ /**
954
+ * `groups.create()` waits until `gate()` resolves and aborts with its
955
+ * rejection; a gate resolving `{ once: true }` is not asked again by this
956
+ * client instance (AC-INBOX-7). Returns the unregister function.
957
+ */
958
+ beforeCreateGroup(gate: CreateGroupGate): () => void;
959
+ /**
960
+ * AC-MX-3: gift-wraps `rumor` (the account's own, with its NIP-01 id) to `to` through the budgeted signer and
961
+ * publishes it once on `to`'s inbox relays (marmot's inbox resolution). Persists nothing, retries nothing:
962
+ * `{ status: 'delivered' | 'retryable' | 'failed', reason?, relays? }`. Rejects `reserved-kind` for a
963
+ * `RUMOR_KINDS` value (before any signer or transport call), `invalid-options` for a malformed input and
964
+ * `reentrant` from an account-scope surface or a group's `onConfirm` hook.
965
+ */
966
+ sendInboxRumor(input: {
967
+ readonly to: string;
968
+ readonly rumor: Rumor;
969
+ }): Promise<InboxRumorDelivery>;
970
+ };
971
+ /**
972
+ * Sinks for transport-adapter callbacks the narrowed `TransportContract`
973
+ * cannot carry: wire `authFailed` into the adapter's `onAuthFailed` option
974
+ * and `connected` into its (re)connect callback. Re-emitted as client
975
+ * events (`authFailed`, `transportConnected`) with the raw relay string
976
+ * (ADR-014); no-ops once the client is disposed.
977
+ */
978
+ readonly transportEvents: {
979
+ authFailed(relayUrl: string, error: unknown): void;
980
+ connected(relayUrl: string): void;
981
+ };
982
+ on<E extends MarmotClientEventName>(event: E, listener: (payload: MarmotClientEvents[E]) => void): () => void;
983
+ /** Releases listeners; every later call on this client throws `disposed`. Idempotent. */
984
+ dispose(): void;
985
+ }
986
+ /**
987
+ * Internal (tests only): the defects the integration properties' negative controls reintroduce into the commit re-drive (epic
988
+ * marmot-rewound-own-commit-no-signal, S6). Each one is a single guarded line in the production path; none is reachable from the public API.
989
+ */
990
+ export interface RedriveFaultsForTest {
991
+ /** AC-PROP-2 (b): the re-drive commit is built WITHOUT the surviving changes' payload, while `own-change-reapplied` is still dispatched for them. */
992
+ readonly dropPayload?: boolean;
993
+ /** AC-PROP-4: the lost verdicts of a re-drive build are dispatched BEFORE the mint transaction commits (and again once it has). */
994
+ readonly dispatchLostBeforeMint?: boolean;
995
+ }
996
+ /** Resolved construction state later client-module stories build on. */
997
+ export interface ClientContext {
998
+ readonly signer: Signer;
999
+ readonly transport: TransportContract;
1000
+ readonly stores: ClientStores;
1001
+ readonly relays: RelayOptions;
1002
+ readonly verifier: EventVerifier | undefined;
1003
+ readonly onProposal: ProposalCallback | undefined;
1004
+ readonly clock: ClientClock;
1005
+ readonly historySilenceThreshold: number;
1006
+ readonly graceWindowMs: number;
1007
+ readonly timers: ClientTimers;
1008
+ readonly historyTimeoutMs: number;
1009
+ readonly maxPublishAttempts: number;
1010
+ /** AC-HOOK-1, AC-BAR-2: the `extensions.onBeforePublish` hooks and the barrier deadline. */
1011
+ readonly beforePublish: BeforePublishRegistry;
1012
+ readonly seenSetCap: number;
1013
+ readonly enrolmentPromptRateLimit: number;
1014
+ readonly maxGiftWrapBytes: number;
1015
+ readonly leaveTimeoutMs: number;
1016
+ /** S15 (AC-INVITE-4): deferral deadline of an `onProposal`-deferred proposal (ms; 0 = never). */
1017
+ readonly proposalDeferralTimeoutMs: number;
1018
+ /** S10: the optional history backend and media cache seams. */
1019
+ readonly history: HistoryBackend | undefined;
1020
+ readonly mediaCache: MediaCache | undefined;
1021
+ /** Internal, tests only: rewrites the engine seams (see {@link createMarmotClientWith}). */
1022
+ readonly engineSeamsOverride: EngineSeamsOverride | undefined;
1023
+ /** Internal, tests only: see {@link InternalClientOptions.engineOptions}. */
1024
+ readonly engineOptionsForTest: InternalClientOptions['engineOptions'];
1025
+ /** Internal: see {@link InternalClientOptions.finishPurgeBeforeJoin}. */
1026
+ readonly finishPurgeBeforeJoin: boolean;
1027
+ /** How long one history backend call may take before it counts as a failed attempt (ms). */
1028
+ readonly historyBackendTimeoutMs: number;
1029
+ /** S20: how long a removal of the local leaf stays revisable (client-clock ms; see client/group-removal.ts). */
1030
+ readonly removalSettleMs: number;
1031
+ /** S5 (AC-RACE-2): the elected-SelfRemove-committer bounded wait (client-clock ms; see client/pipeline.ts). */
1032
+ readonly selfRemoveElectionWaitMs: number;
1033
+ /** S7 (AC-HYG-2): how long a settled invite record is kept (client-clock ms; see invitations/invite.ts). */
1034
+ readonly inviteRetentionMs: number;
1035
+ /** inbox-handler-time-budget: when a running inbox consumer callback is reported `handlerSlow` (client-clock ms; 0 = never). */
1036
+ readonly inboxHandlerBudgetMs: number;
1037
+ /** S8 (AC-RATCH-1): own application ratchet skip at the first own message after a load (see client/pipeline.ts). */
1038
+ readonly ratchetSkipMargin: number;
1039
+ /** Internal (tests only): see {@link InternalClientOptions.disableSelfUpdateReenqueueForTest}. */
1040
+ readonly disableSelfUpdateReenqueueForTest: boolean;
1041
+ /** Internal (tests only): see {@link InternalClientOptions.disableRestoreRotationForTest}. */
1042
+ readonly disableRestoreRotationForTest: boolean;
1043
+ /** Internal (tests only): see {@link InternalClientOptions.disableRatchetSkipForTest}. */
1044
+ readonly disableRatchetSkipForTest: boolean;
1045
+ /** Internal (tests only): see {@link InternalClientOptions.redriveFaultsForTest}. */
1046
+ readonly redriveFaultsForTest: RedriveFaultsForTest | undefined;
1047
+ /** Internal (tests only): see {@link InternalClientOptions.exposeRuntimesForTest}. */
1048
+ readonly exposeRuntimesForTest: InternalClientOptions['exposeRuntimesForTest'];
1049
+ emit<E extends MarmotClientEventName>(event: E, payload: MarmotClientEvents[E]): void;
1050
+ /** AC-INBOX-6: the only emit path of every `LifecycleEventPayloads` member — after the commit. */
1051
+ readonly lifecycle: LifecycleEvents;
1052
+ /** AC-INBOX-7: the `beforeCreateGroup` gates `groups.create()` passes first. */
1053
+ readonly beforeCreateGroup: BeforeCreateGroupGates;
1054
+ /**
1055
+ * Epic marmot-device-key-rotation (S6, AC-NOTIF-6): where a group operation reads the device lineage from — the
1056
+ * account's recorded links, as the synchronous {@link DeviceLineage} snapshot `devices.lineage()` hands out (`isRetired`, `keysOf`). Late-bound
1057
+ * (the device service is built after the group registry that holds `ctx`): `read` is `undefined` until then, and
1058
+ * a failing or absent read only means no `retired-key-readded` is emitted.
1059
+ */
1060
+ readonly deviceLineage: DeviceLineageSource;
1061
+ isDisposed(): boolean;
1062
+ }
1063
+ /** See {@link ClientContext.deviceLineage}. */
1064
+ export interface DeviceLineageSource {
1065
+ read: (() => Promise<DeviceLineage>) | undefined;
1066
+ }
1067
+ /** Internal accessor for tests; not re-exported. */
1068
+ export declare function getGroupRegistry(client: MarmotClient): GroupRegistry;
1069
+ /** Internal accessor for other client-module files and tests; not re-exported. */
1070
+ export declare function getClientContext(client: MarmotClient): ClientContext;
1071
+ export declare const BUDGET_NUMERIC_FIELDS: readonly ["concurrency", "minSpacingMs", "timeoutMs", "leaseMs"];
1072
+ export declare function createMarmotClient(options: MarmotClientOptions): MarmotClient;
1073
+ /** What {@link createMarmotClientWith} takes beyond the public options — never reachable from the package root. */
1074
+ export interface InternalClientOptions {
1075
+ /**
1076
+ * Rewrites the seams every engine of this client is built with — how a
1077
+ * test builds a client on the engine defaults to prove that a seam is
1078
+ * load-bearing (AC-ADMIN-8, AC-ADMIN-9).
1079
+ */
1080
+ readonly engineSeams?: EngineSeamsOverride;
1081
+ /**
1082
+ * Extra options every engine of this client is built with, spread over marmot's own (never over `removal` or
1083
+ * `opaque`, the persisted records) — how a test chooses an engine option marmot does not expose (the OQ-1 hidden-credit
1084
+ * policy, or the opaque seam switched off). The opt-in itself is the one literal in `group-runtime.ts`, never an option.
1085
+ */
1086
+ readonly engineOptions?: Partial<MarmotGroupEngineOptions<NostrEvent>>;
1087
+ /**
1088
+ * `false` skips finishing an interrupted purge before a Welcome's group is adopted — ONLY for the negative
1089
+ * control that shows why it is there (a resumed purge would delete the re-joined group). Default `true`.
1090
+ */
1091
+ readonly finishPurgeBeforeJoin?: boolean;
1092
+ /** Internal (tests only): the history backend call timeout; default {@link HISTORY_BACKEND_TIMEOUT_MS}. */
1093
+ readonly historyBackendTimeoutMs?: number;
1094
+ /**
1095
+ * Internal (tests only), AC-RACE-3's negative control: `true` disables every drive of a re-enqueued
1096
+ * self-update (`driveReenqueuedSelfUpdate`, reached from the scheduled drive and from `resumePending`) — the withdrawn self-update's re-enqueued record is still written atomically
1097
+ * (group-history.ts `recordTransition`; that durability cannot be disabled from outside), but nothing
1098
+ * ever drives it, reproducing the pre-AC-RACE-1 symptom (the rotation never lands on the winning branch,
1099
+ * and no `intentFailed` is ever reported either — it is simply stuck, the "silently lost" bug this story
1100
+ * fixes). Default `false`.
1101
+ */
1102
+ readonly disableSelfUpdateReenqueueForTest?: boolean;
1103
+ /**
1104
+ * Tests only: a successful `groups.restore` owes no device-key rotation (owner decision 13), for suites that count the
1105
+ * signer calls and relay events of a restore and are not about the rotation.
1106
+ */
1107
+ readonly disableRestoreRotationForTest?: boolean;
1108
+ /**
1109
+ * Internal (tests only), AC-RATCH-1/3's negative control: `true` never asks the engine for the post-load ratchet
1110
+ * skip, so the first own application message after a load uses the restored state's next generation (the
1111
+ * behaviour before AC-RATCH-1). Default `false`.
1112
+ */
1113
+ readonly disableRatchetSkipForTest?: boolean;
1114
+ /**
1115
+ * Internal (tests only), the negative controls of epic marmot-rewound-own-commit-no-signal's integration properties
1116
+ * (AC-PROP-2 (b), AC-PROP-4): each flag reintroduces ONE defect the corresponding property exists to catch. Absent: no effect.
1117
+ */
1118
+ readonly redriveFaultsForTest?: RedriveFaultsForTest;
1119
+ /**
1120
+ * Internal (tests only), a mutation-gate test seam: called once at client construction with a read-only lookup
1121
+ * of the live per-group runtimes, so a test can drive pipeline internals on a real runtime. Absent: no effect.
1122
+ */
1123
+ readonly exposeRuntimesForTest?: (get: (groupId: string) => GroupRuntime | undefined) => void;
1124
+ }
1125
+ /** Internal (tests only): `createMarmotClient` with {@link InternalClientOptions}. */
1126
+ export declare function createMarmotClientWith(options: MarmotClientOptions, internal: InternalClientOptions): MarmotClient;