@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,461 @@
1
+ /**
2
+ * S10 — the client side of `history-media`: the group handle's
3
+ * `onNotification`, `history()`, `encryptMedia`/`decryptMedia`, the delivery
4
+ * of a persisted transition's notifications (listeners, then the history
5
+ * backend), and fencing (AC-HIST-4).
6
+ *
7
+ * Everything here runs AFTER the state it describes was persisted (persist
8
+ * before side effects). Listeners are dispatched outside every re-entrancy
9
+ * frame — nothing awaits them, so one may start another operation, which
10
+ * queues. The history backend and the media cache are consumer surfaces,
11
+ * called through the guard; its updates go through a durable outbox (retried,
12
+ * in order), never blocking the live delivery or the group's state.
13
+ */
14
+ import type { Rumor } from '@941design/nostr-events/event';
15
+ import type { LeafEquivocation } from '@941design/marmot-engine/core';
16
+ import { type EquivocationRecord, type GroupNotification, type MessageNotification, type OrderingKey, type MessageWithdrawnNotification, type RetainedWindow } from '../history/index.js';
17
+ import { type EncryptedMedia, type EncryptMediaOptions } from '../media/index.js';
18
+ import { MarmotError } from '../shared/index.js';
19
+ import { type ClientState } from '@941design/marmot-engine/mls';
20
+ import type { GroupStoreTx, KeyValueView } from '../storage/index.js';
21
+ import { type MarkerChange, type OwnCommitMarker, type PendingIntentRecord } from './group-records.js';
22
+ import type { ClientContext } from './create-client.js';
23
+ import type { ReentrancyGuard } from './reentrancy-guard.js';
24
+ import type { GroupRuntime } from './group-runtime.js';
25
+ export declare function subscribeNotifications(rt: GroupRuntime, listener: (notification: GroupNotification) => void): () => void;
26
+ /** Announces notifications whose state is already persisted (a settled disband, client/group-disband.ts). */
27
+ export declare function announceNotifications(rt: GroupRuntime, notifications: readonly GroupNotification[]): void;
28
+ /** Delivers `notifications` to the group's `onNotification` listeners, each listener detached from the caller's frame. Call only after the transaction that decided them has committed. */
29
+ export declare function dispatch(rt: GroupRuntime, notifications: readonly GroupNotification[]): void;
30
+ /**
31
+ * S11 (AC-COMP-10, spec DD7 Delivery): hands every terminal in the outbox (`own-change-reapplied`, `own-change-lost`) to the
32
+ * group's listeners in the order it was decided, then removes what was handed over in a follow-up transaction. Called
33
+ * after a transaction that wrote terminals committed, when the first listener subscribes (the load path: a reloaded handle has
34
+ * no listener until the app attaches one) and ahead of every transition's own notifications (`deliverTransition`), so a
35
+ * retained terminal always precedes whatever this session adds. `resumePending` does not announce: on a first load it would
36
+ * find no listener, and every later case is covered by these.
37
+ *
38
+ * At-least-once, with the payload identical on every delivery: a crash or dispose before this runs leaves the entries for
39
+ * the next load; one after the dispatch and before the removal repeats them once. A disposed runtime delivers nothing and
40
+ * keeps the entries. With no listener nothing is delivered or removed (an entry is removed only once a listener was handed
41
+ * it, so a handle that subscribes after the load still receives it); the outbox's cap bounds that retention. Never throws. Run inside a group
42
+ * op (the queue serialises it with every other writer), except the `deliverTransition` path, which drops by key.
43
+ */
44
+ export declare function announceTerminals(rt: GroupRuntime, except?: ReadonlySet<string>): Promise<void>;
45
+ /** The ledger disposition of a message once withdrawn: still terminal (a redelivery is a duplicate), never withdrawn twice. */
46
+ export declare const WITHDRAWN_DISPOSITION = "withdrawn";
47
+ /** One withdrawn own commit that declared a change: what {@link recordTransition} turns into a re-drive record (S1). */
48
+ export interface WithdrawnOwnCommit {
49
+ /** The commit's kind-445 event id: its ledger entry's and marker's key. */
50
+ readonly eventId: string;
51
+ /** The root intent id (`reportedIntentIdOf`). */
52
+ readonly rootIntentId: string;
53
+ /** The abandoned node. */
54
+ readonly node: string;
55
+ /** The ledger entry's `at` and the node's epoch: the withdrawal-order key shared with `withdrawnSelfUpdates` (DD1). */
56
+ readonly at?: number;
57
+ readonly epoch?: number;
58
+ /** Hex digest of the withdrawn commit. */
59
+ readonly commitDigest: string;
60
+ /** Non-empty: the declared changes with their fork-point values, in the diff's order; no verdicts. */
61
+ readonly changes: readonly MarkerChange[];
62
+ readonly forkEpoch: number;
63
+ /** The carried `maxPublishAttempts` budget (the marker's). */
64
+ readonly attempts: number;
65
+ /** The marker to persist, set exactly on the commit's FIRST withdrawal (DD14: `changes` are written once). */
66
+ readonly markerUpdate?: OwnCommitMarker;
67
+ }
68
+ /**
69
+ * A persisted transition's announcements, computed before the transaction
70
+ * that persists it: the ledger entries of withdrawn messages are rewritten
71
+ * in that transaction ({@link markWithdrawn}), and everything is delivered
72
+ * once it committed ({@link deliverTransition}).
73
+ */
74
+ export interface TransitionPlan {
75
+ /** The window persisted with the transition: `rt.window` once delivered. */
76
+ readonly window: RetainedWindow;
77
+ /** State withdrawals, message withdrawals, applied changes, then the kept messages — the dispatch order. */
78
+ readonly notifications: readonly GroupNotification[];
79
+ /** Messages of this transition still on the canonical branch: appended to the history backend. */
80
+ readonly kept: readonly MessageNotification[];
81
+ /** Messages delivered earlier whose branch this transition abandoned. */
82
+ readonly withdrawn: readonly MessageWithdrawnNotification[];
83
+ /** The transition left states the group had been on (a fork rewind): outcomes read from them may not hold. */
84
+ readonly rewound: boolean;
85
+ /**
86
+ * S20 round 1: leaf keys (hex signature keys) the rewind WITHDREW — held by a state it abandoned and by no state
87
+ * of the new canonical path (an Add that existed only on the abandoned branch). Decided here, at the rewind, while
88
+ * the abandoned states are still in the window: a later recheck cannot re-derive it once the horizon pruned them.
89
+ */
90
+ readonly withdrawnLeaves?: readonly string[];
91
+ /**
92
+ * S20 round 2: every leaf key on a state this transition put on the canonical path, and on its new tip (computed
93
+ * on demand — only when a settlement-recheck marker exists): a withdrawn leaf seen there again (re-added after the
94
+ * rewind that recorded it) is no longer withdrawn evidence. States that were canonical before this transition are
95
+ * not counted: they are older than the evidence (each earlier transition already pruned against its own), and a
96
+ * state older than the withdrawn Add holding the same leaf — a device removed, then re-enrolled with the same leaf
97
+ * key — is not a re-add.
98
+ */
99
+ readonly canonicalLeaves?: () => ReadonlySet<string>;
100
+ /**
101
+ * S5 (AC-RACE-1): own self-update commits a rewind withdrew — terminal-ledger entries whose
102
+ * `selfUpdateIntentId` was set at confirm time, matched the same way `withdrawn` is but kept OUT of it:
103
+ * a self-update commit never had a `message` notification of its own, so it must never surface as
104
+ * `message-withdrawn` (no such notification, no history-backend `withdraw` op) — only its ledger entry
105
+ * is marked withdrawn ({@link markWithdrawn}), and {@link recordTransition} re-enqueues it atomically, in
106
+ * the SAME transaction, so the withdrawal is never durable without its re-enqueue also being durable.
107
+ * `originalIntentId` is the ROOT id of the chain (never a prior re-enqueue's own fresh id — see
108
+ * `reportedIntentIdOf`, pipeline.ts), and `attempts` carries that chain's own publish-attempt budget
109
+ * forward rather than resetting it.
110
+ */
111
+ readonly withdrawnSelfUpdates?: readonly {
112
+ readonly eventId: string;
113
+ readonly originalIntentId: string;
114
+ readonly attempts: number;
115
+ readonly rekey?: string;
116
+ }[];
117
+ /**
118
+ * The withdrawal-order key (`at`, abandoned epoch) of each entry of {@link withdrawnSelfUpdates}, by event id: with the same key on
119
+ * {@link WithdrawnOwnCommit}, {@link recordTransition} assigns `seq` in ONE pass over both families (DD1). Absent: 0, 0.
120
+ */
121
+ readonly selfUpdateOrder?: Readonly<Record<string, {
122
+ readonly at: number;
123
+ readonly epoch: number;
124
+ }>>;
125
+ /**
126
+ * Epic marmot-rewound-own-commit-no-signal (S1; spec DD2, DD11-DD14): the own commits this transition withdrew that
127
+ * declared a change, one entry per root intent id (the deepest marked node of the root when a root has several),
128
+ * in the withdrawal order of {@link withdrawnSelfUpdates} (`at`, epoch, event id). {@link recordTransition} writes
129
+ * each one's re-drive record in the SAME transaction the withdrawal is marked in; the `own-change-withdrawn`
130
+ * notifications are in {@link notifications}. Absent when none. A root with a restored marked node (see
131
+ * {@link restoredOwnCommits}) gets no entry.
132
+ */
133
+ readonly withdrawnOwnCommits?: readonly WithdrawnOwnCommit[];
134
+ /**
135
+ * Event ids of EVERY own-commit ledger entry (`ownCommitRoot`) whose node this transition abandoned, turned
136
+ * `withdrawn` by {@link markWithdrawn}: the marked ones above, a commit whose intersected diff is empty or that is
137
+ * unreadable ({@link unreadableOwnCommits}), a duplicate node of one root, and a DD17 link-only entry (no marker),
138
+ * which is withdrawn silently — ledger only, no record, no notification.
139
+ */
140
+ readonly withdrawnOwnCommitEntries?: readonly string[];
141
+ /**
142
+ * Marked own commits whose withdrawal could not be broken down into changes (the commit's states or the fork point
143
+ * are not in the window, or a leaf credential / admin policy of the pair does not decode — `ownCommitChanges`
144
+ * returned `undefined`). The documented outcome: no re-drive record, no `own-change-*` notification (the changes
145
+ * cannot be named), the ledger entry withdrawn like any other; the coarse `withdrawn` notifications still fire.
146
+ * Never read as "no change".
147
+ */
148
+ readonly unreadableOwnCommits?: readonly {
149
+ readonly eventId: string;
150
+ readonly rootIntentId: string;
151
+ readonly node: string;
152
+ readonly reason: string;
153
+ }[];
154
+ /**
155
+ * Marked own commits this transition put back on the canonical path while their ledger disposition was `withdrawn`
156
+ * (DD14, decided on the marker): {@link recordTransition} returns the entries to `own` and deletes the not-yet-started
157
+ * re-drive record of the root; `own-change-reapplied` (naming the node's commit digest) is in {@link notifications}.
158
+ * One entry per root (the deepest node); `eventIds` lists every restored entry of the root.
159
+ */
160
+ readonly restoredOwnCommits?: readonly {
161
+ readonly rootIntentId: string;
162
+ readonly eventIds: readonly string[];
163
+ }[];
164
+ /**
165
+ * The tags of the nodes this transition abandoned (left the canonical path). {@link deliverTransition} uses them to
166
+ * withdraw the invite commits (and so their undelivered Welcomes) that sat on them. Absent when none was abandoned.
167
+ */
168
+ readonly abandonedTags?: readonly string[];
169
+ /**
170
+ * S5 (AC-RACE-1): every node tag on the transition's new canonical path — `after`'s and `diffAgainst`'s (one
171
+ * catch-up batch can bring a withdrawn own self-update's node back onto the canonical path AND prune it below the
172
+ * horizon in the same transition; `diffAgainst` still holds it). {@link recordTransition} cancels a pending
173
+ * re-enqueue whose original rotation is on it ({@link cancelRestoredReenqueues}). Always holds the canonical path of `after` and `diffAgainst`
174
+ * (their tips included), moved or not; {@link cancelRestoredReenqueues} treats an empty set as "nothing to restore".
175
+ */
176
+ readonly canonicalTags: ReadonlySet<string>;
177
+ /**
178
+ * Epic marmot-invitation-outcomes S4 (SC-4 I11): what {@link recordTransition} advances admission lineage over — the
179
+ * window the transition started from, the one it diffed against, and `window`'s tip state. Absent on a plan that
180
+ * does not move the window (a lost message): no checkpoint moves then.
181
+ */
182
+ readonly lineage?: {
183
+ readonly before: RetainedWindow;
184
+ readonly diff: RetainedWindow;
185
+ readonly tip: ClientState;
186
+ };
187
+ }
188
+ /**
189
+ * The announcements of moving the group from `before` (tip `beforeTip`) to
190
+ * `after` (tip `afterTip`) with `messages` accepted on the way.
191
+ *
192
+ * A message delivered earlier is withdrawn when the state it was delivered
193
+ * under (its ledgered `node`, the ordering key's `acceptedDigest`) left the
194
+ * canonical path — whether this member received it (`application`) or sent
195
+ * it (`own`) — or when the engine retracted it itself (`invalidated`, its
196
+ * in-memory delivery ledger: `retracted`, by event id). Messages of this
197
+ * transition (`messages`) are never withdrawn, only not announced.
198
+ */
199
+ export declare function planTransition(rt: GroupRuntime, before: RetainedWindow, beforeTip: ClientState, after: RetainedWindow, afterTip: ClientState, messages: readonly MessageNotification[], retracted?: ReadonlySet<string>,
200
+ /**
201
+ * The window the notifications are diffed against when it differs from the
202
+ * persisted `after`: one reaching down to `before`'s floor, so commits a
203
+ * batch applied and the horizon already pruned from `after` still count.
204
+ */
205
+ diffAgainst?: RetainedWindow): Promise<TransitionPlan>;
206
+ /** Rewrites the ledger entries of `plan`'s withdrawn messages, AND its withdrawn self-updates (never announced
207
+ * as message-withdrawn, but withdrawn in the ledger all the same) and its withdrawn own commits (S1) — inside the transition's own transaction. */
208
+ export declare function markWithdrawn(view: KeyValueView, plan: TransitionPlan, at: number): Promise<void>;
209
+ /**
210
+ * Whether a message sent under the state `key.acceptedDigest` names is still
211
+ * on the group's canonical branch: that state is on `window`'s canonical
212
+ * path — or below the window's floor (pruned: nothing left to contradict
213
+ * it). A state at or above the floor that is not on the path was abandoned.
214
+ */
215
+ export declare function sentOnCanonicalBranch(window: RetainedWindow, key: OrderingKey): boolean;
216
+ /** The announcement of an own message whose send-time branch was abandoned before its confirmation (never kept). */
217
+ export declare function lostMessagePlan(rt: GroupRuntime, lost: MessageNotification): TransitionPlan;
218
+ /**
219
+ * Group extension marking that a persisted transition of the group rewound
220
+ * (left states it had been on) since the device service last rechecked the
221
+ * outcomes it settled from the group's tree (an approval's `enrolled`, a
222
+ * forget's `removed`). Written in the transition's own transaction, so a
223
+ * crash before the in-memory rewind announcement still leaves it; cleared
224
+ * by the device service only once its recheck is conclusive.
225
+ */
226
+ export declare const SETTLEMENT_RECHECK_EXTENSION = "marmot.settlement-recheck";
227
+ /**
228
+ * The marker: a token bumped by every rewind, and (S20 round 1) the leaf keys the rewinds since the last cleared
229
+ * recheck withdrew (`TransitionPlan.withdrawnLeaves`, accumulated). Stored `{ t, w }`; a marker written before S20
230
+ * round 1 is a bare token number (no leaf evidence: the recheck falls back to re-deriving it).
231
+ */
232
+ export interface SettlementRecheck {
233
+ readonly token: number;
234
+ /** `undefined` for a pre-S20 marker. */
235
+ readonly withdrawnLeaves?: readonly string[];
236
+ }
237
+ /**
238
+ * The marker's part of one recorded transition (inside its transaction). A rewind sets (or bumps) it — a later
239
+ * rewind gets a new token, so a recheck that read the old one cannot clear it — and adds the leaves it withdrew.
240
+ * S20 round 2: every transition, while a marker exists, first drops from its evidence the leaves present on the new
241
+ * canonical path: a withdrawn leaf seen canonically again (re-added) is not withdrawn any more, and must not reopen
242
+ * an approval after it LEAVES there (a resurrection). A transition that did not rewind never creates a marker.
243
+ */
244
+ export declare function updateSettlementRecheck(view: KeyValueView, plan: Pick<TransitionPlan, 'rewound' | 'withdrawnLeaves' | 'canonicalLeaves'>): Promise<void>;
245
+ /** The marker, or `undefined` when none is set. */
246
+ export declare function readSettlementRecheckRecord(view: KeyValueView): Promise<SettlementRecheck | undefined>;
247
+ /** The marker's token, or `undefined` when none is set. */
248
+ export declare function readSettlementRecheck(view: KeyValueView): Promise<number | undefined>;
249
+ /** Clears the marker when it still carries `token` (inside the caller's transaction). */
250
+ export declare function clearSettlementRecheck(view: KeyValueView, token: number): Promise<void>;
251
+ /**
252
+ * Group extension holding the history backend updates (withdrawals, appends)
253
+ * of transitions that committed but whose updates have not reached the
254
+ * backend yet. Written in the transition's own transaction, drained in
255
+ * order, each op deleted once the backend took it — so a crash between the
256
+ * commit and the delivery never leaves the backend holding a message the
257
+ * ledger already withdrew, or missing one it accepted.
258
+ */
259
+ export declare const HISTORY_OUTBOX_EXTENSION = "marmot.history-outbox";
260
+ /**
261
+ * A backend that keeps refusing one op gives it up after this many attempts
262
+ * (later ops are not held hostage); documented on `HistoryBackend`.
263
+ */
264
+ export declare const MAX_HISTORY_ATTEMPTS = 5;
265
+ /**
266
+ * The durable half of every own commit a transition withdrew, written in the SAME transaction as the withdrawal (a crash can never
267
+ * leave the withdrawal without its record; the caller only DRIVES the durable records afterwards, detached):
268
+ * - AC-RACE-1: one self-update re-enqueue record per withdrawn self-update (`reenqueuedFrom` = the root; a rekey stays a rekey);
269
+ * - epic marmot-rewound-own-commit-no-signal S1 (AC-REC-1/2, DD14): one `{ kind: 'commit', intent: { type: 'commit' } }` re-drive record per
270
+ * root with `changes` + `forkEpoch` (the fork-point breakdown; the record is the verdict carrier from here on) and the carried `attempts`.
271
+ */
272
+ declare function reenqueueAndRedriveWithdrawn(tx: GroupStoreTx, plan: TransitionPlan, epoch: bigint, dedupAcrossStates?: boolean): Promise<void>;
273
+ /**
274
+ * S5 (AC-RACE-1): a pending re-enqueue (`reenqueuedFrom`) whose ORIGINAL rotation this transition puts back on the
275
+ * canonical path — the withdrawn branch won fork recovery back — owes nothing: it is deleted and the rotation's
276
+ * ledger entries restored to `own`, in the transition's own transaction. That includes one whose envelope awaits
277
+ * its publish retry: no relay accepted it, it was minted on the branch this transition abandons, and its publish
278
+ * retry finds no record and does nothing. A `pending-confirm` one is KEPT: a relay accepted it, peers that applied
279
+ * it may converge on its branch, and this client cannot re-process its own commit from a relay — deleting the
280
+ * record would discard the only pending state that lets it follow, forking it off for good. `confirmRecord`
281
+ * resolves it through its normal path; the residual is a possible extra rotation when the original's branch also
282
+ * stays canonical (the group stays consistent — the accepted-own-commit class, BACKLOG
283
+ * `own-commit-ack-lost-max-attempts-terminal`). That keeping is the SELF-UPDATE re-enqueue's: a commit re-drive of a restored
284
+ * root is retired in every state, `pending-confirm` included (epic marmot-rewound-own-commit-no-signal S10, DD14, AC-REC-7; the `pending-confirm` case is defensive and has no known producer: ingest.ts refuses every batch while one exists, resolvePendingCommit refuses under it, an own confirmation never restores another record's root, and rebaseToWelcome restores a marked node only when a Welcome names exactly the state that commit produced, which a removal re-drive cannot meet; kept because the state is representable) --
285
+ * its change is carried by the original now, and a second terminal for it would be wrong. (Ingest refuses every batch while a record is pending-confirm, so a
286
+ * restoring transition reaches one only through an own confirmation's transition.) Atomic with the restoring transition, so
287
+ * it holds even when the same catch-up prunes that node below the rewind horizon (`plan.canonicalTags` includes
288
+ * `diffAgainst`'s path for exactly that). Returns the cancelled records' intent ids (since S1 also those of commit re-drive records, `changes` set: a consumer must tolerate ids
289
+ * that are not self-update re-enqueues); the caller re-evaluates any
290
+ * sibling that waited behind one once the transaction committed.
291
+ *
292
+ * This is the ONLY cancel — there is no drive-time re-check (pipeline.ts `driveReenqueuedSelfUpdate`), and
293
+ * none is needed, on two premises: (1) the canonical path changes only here — `rt.window` is assigned only by
294
+ * `deliverTransition` and by rebuild/load from the stored window, and every writer that changes the window's tip
295
+ * (ingest's transition, `confirmRecord`) writes it in the same transaction as `recordTransition`, while the other
296
+ * window writers (`remintStaleReenqueue`, `settlePublishedRecord`'s stale path, `restageExcludedProposals`) add fork
297
+ * nodes or re-snapshot nodes with the tip unchanged, and groups.restore/create start from a cleared store
298
+ * (test/client/write-window-sites.test.ts pins the writer list); (2) every `selfUpdateIntentId` ledger writer
299
+ * outside this transaction either names a non-canonical node or deletes the root's only record in the same
300
+ * transaction. A pending-confirm record kept here goes only to `confirmRecord`, which deletes it.
301
+ */
302
+ /**
303
+ * ledger-retention-vs-rewind-horizon: the confirmation tags of every node of the stored rewind window (tip, canonical
304
+ * path and fork nodes) — the nodes a later fork flip can still abandon or restore. A terminal-ledger entry naming one
305
+ * (`node`) is what `planTransition`'s withdrawal detection and {@link cancelRestoredReenqueues} key off, so age-based
306
+ * retention (`pruneTerminalLedger`) must keep it however old it is: the window is commit-bounded, the ledger's age
307
+ * bound is not, and in a quiet group a node can outlive `LEDGER_RETENTION_S`. Read in the prune's own transaction.
308
+ * A pending re-enqueue needs no separate pin: its original can only be restored while the original's node is
309
+ * still in this window. Empty when no window is stored.
310
+ */
311
+ export declare function retainedLedgerNodes(tx: Pick<GroupStoreTx, 'artifact'>): Promise<ReadonlySet<string>>;
312
+ export declare function cancelRestoredReenqueues(tx: GroupStoreTx, plan: Pick<TransitionPlan, 'canonicalTags'> & Partial<Pick<TransitionPlan, 'restoredOwnCommits'>>, retired?: PendingIntentRecord[]): Promise<readonly string[]>;
313
+ /**
314
+ * Records `plan` in the transition's own transaction: the ledger entries of
315
+ * withdrawn messages turn `withdrawn`, each withdrawn self-update (AC-RACE-1) is re-enqueued atomically
316
+ * (so a crash between the withdrawal and its re-enqueue is impossible — the caller only has to DRIVE the
317
+ * already-durable record afterwards, detached), and — with a history backend — its backend updates are
318
+ * queued in the outbox, withdrawals before appends. `epoch` is the transition's resulting epoch (the new
319
+ * tip's), used as the re-enqueued record's `parentEpoch`. Returns the ids of the records {@link cancelRestoredReenqueues} deleted:
320
+ * self-update re-enqueues AND (S1) commit re-drive records.
321
+ */
322
+ export declare function recordTransition(rt: GroupRuntime, tx: GroupStoreTx, plan: TransitionPlan, epoch: bigint): Promise<readonly string[]>;
323
+ /** How long one history backend call may take before it counts as a failed attempt (ms). */
324
+ export declare const HISTORY_BACKEND_TIMEOUT_MS = 10000;
325
+ /**
326
+ * One history backend call through the guard, bounded by
327
+ * `historyBackendTimeoutMs`: a call that does not settle in time rejects
328
+ * here (the consumer's promise may still settle later — calls are
329
+ * at-least-once and idempotent by `eventId`, see `HistoryBackend`).
330
+ */
331
+ export declare function boundedHistoryCall<T>(ctx: ClientContext, guard: ReentrancyGuard, groupId: string, fn: () => T | Promise<T>): Promise<T>;
332
+ /**
333
+ * Issues one mutating backend call and remembers it until it actually
334
+ * settles, however long that takes: no later call — the next op, or the
335
+ * teardown purge — is issued before it did, so a call that timed out can
336
+ * never land after (and undo) an update meant to come after it.
337
+ */
338
+ export declare function issueMutation(rt: GroupRuntime, fn: () => void | Promise<void>): Promise<void>;
339
+ /**
340
+ * Waits up to the history call timeout for the group's last mutating backend
341
+ * call to settle; rejects when it still has not (the teardown step fails and
342
+ * is retried — a purge never overtakes an append still in flight).
343
+ */
344
+ export declare function awaitHistoryCallSettled(rt: GroupRuntime): Promise<void>;
345
+ /**
346
+ * Hands the outbox to the history backend on the group's own history worker
347
+ * — serialized per group, but OUTSIDE the group's operation queue and every
348
+ * consumer frame, so a slow or hanging backend never holds up a send, an
349
+ * ingest or a teardown (the history backend is optional; live delivery never
350
+ * waits on it). In order, each op deleted once the backend took it; a
351
+ * failing (or timed-out, see {@link boundedHistoryCall}) op stops the pass
352
+ * and is retried by the next one — the next transition's delivery, the
353
+ * group's next load, a `history()` read — until {@link MAX_HISTORY_ATTEMPTS}.
354
+ * A drain requested while one runs makes it run once more. Resolves when the
355
+ * worker is idle; never rejects.
356
+ */
357
+ export declare function scheduleHistoryDrain(rt: GroupRuntime): Promise<void>;
358
+ /**
359
+ * Stops the group's history worker for good (teardown): no further backend
360
+ * call is started; resolves once the call in flight settled or timed out.
361
+ */
362
+ export declare function stopHistoryDrain(rt: GroupRuntime): Promise<void>;
363
+ /**
364
+ * Announces a persisted transition: `rt.window` moves to the plan's window,
365
+ * the notifications go to the listeners, and the history outbox the
366
+ * transition filled is handed to the group's history worker (not awaited).
367
+ * Never throws — it runs after the transition committed, so nothing may undo it.
368
+ */
369
+ export declare function deliverTransition(rt: GroupRuntime, plan: TransitionPlan, defer?: ReadonlySet<string>): Promise<void>;
370
+ /**
371
+ * Hands the Welcomes of a commit re-drive record that is about to be (or was just) deleted to the invitations service as an
372
+ * ALREADY-WITHDRAWN invite record: `recordCommitted` under the record's id, the staged commit's event id and the node it produced,
373
+ * then `withdrawCommit` (so `welcomeFailed` `commit-withdrawn` fires, exactly as for any abandoned invite commit).
374
+ *
375
+ * Why: a started invite re-drive's Welcomes reach the invitations service only when its confirmation runs. The two paths that delete
376
+ * such a record while RETAINING its commit (the stale re-mint of a stored/confirmed envelope, the DD14 retire at `pending-confirm`) would
377
+ * otherwise leave a commit that can still win -- peers extend it -- with a member nobody ever sent a Welcome. With the record parked,
378
+ * a later restore of that node is the ordinary `reconcileInvites` -> `restoreCommit` (`welcomeRestored`), which delivers.
379
+ *
380
+ * The record is keyed `<intentId>:<commit event id>`, never the bare intent id: a re-mint keeps its intent id, so a bare key would make the
381
+ * re-mint's own `recordCommitted` at confirm a no-op against this parked record (the re-mint would then be a member nobody sent a Welcome),
382
+ * and a second discarded commit of the same record would collide with the first.
383
+ *
384
+ * Idempotent (`recordCommitted` keeps progress, `withdrawCommit` is idempotent): a second park of the same commit is a no-op. Cross-store (account
385
+ * store, outside the group transaction that deletes the record) -- the ONE intentional divergence: in the re-mint it runs BEFORE that
386
+ * transaction, so a crash in between leaves a parked record next to a still-durable record (harmless: the retry parks again, a no-op).
387
+ * Best-effort like {@link reconcileInvites}: `strict` false throws (the caller still holds the
388
+ * record and retries); `strict` true (after a committed transition) reports `welcomeReconcileFailed` and moves on -- the Welcomes of that
389
+ * commit are then recoverable only by the application's `retryWelcome` of a re-invite, never lost silently.
390
+ */
391
+ export declare function parkWithdrawnWelcomes(rt: GroupRuntime, record: PendingIntentRecord, afterCommit?: boolean): Promise<void>;
392
+ /**
393
+ * Brings the group's undelivered invite Welcomes in line with the canonical path: an invite commit whose node is in
394
+ * `abandoned` lost its race, so its Welcomes that are not yet published must not go out (the invitee would consume and
395
+ * rotate its KeyPackage for a branch the group left); one whose node is in `canonical` again (it came back through
396
+ * equivocation credit or a longer branch) has the deliveries withdrawn earlier restored. Idempotent and best-effort:
397
+ * a failure is reported as `welcomeReconcileFailed` and leaves the deliveries as they were (a crash before it has the
398
+ * same effect, and the next load reconciles against the stored window, {@link reconcileInvitesWithWindow}).
399
+ *
400
+ * Never withdraws a node the new canonical path shares with the old one: a branch switch (`rebaseToWelcome`) only
401
+ * lands on a competing branch (`judgeCompetingWelcome` rejects a C descending from an H node at or above H's root), so
402
+ * a node common to both paths is never in `abandoned`.
403
+ */
404
+ export declare function reconcileInvites(rt: GroupRuntime, abandoned: ReadonlySet<string>, canonical: ReadonlySet<string>,
405
+ /** The roots the transition restored / wrote a re-drive record for (none: a load, which decides from the store alone). */
406
+ roots?: {
407
+ readonly restoredRoots: ReadonlySet<string>;
408
+ readonly redriveRoots: ReadonlySet<string>;
409
+ }): Promise<void>;
410
+ /** {@link reconcileInvites} against a stored window: nodes off its canonical path are abandoned (a load after a crash). */
411
+ export declare function reconcileInvitesWithWindow(rt: GroupRuntime, window: RetainedWindow): Promise<void>;
412
+ /**
413
+ * ADR-016 (SC-6): merges engine-reported equivocation evidence into `into`, one record per key — the engine re-reports
414
+ * the same evidence on every selection pass, and further sibling digests of the same leaf at the same node are the
415
+ * same evidence (their digests merged in). Throws `MarmotError('invalid-options')`, leaving `into` untouched, when any
416
+ * entry is not recordable evidence ({@link isRecordableEquivocation}).
417
+ */
418
+ export declare function noteEquivocations(into: Map<string, EquivocationRecord>, reported: readonly LeafEquivocation[]): void;
419
+ /**
420
+ * ADR-016 (SC-6): records evidence an engine drain reported OUTSIDE an ingest batch — the convergence continuation's
421
+ * drive and the pooled re-ingest after a rollback or a proposal drop, whose results are otherwise discarded — in its
422
+ * own store transaction (only keys absent before it), and announces exactly the records that transaction wrote, once
423
+ * it committed. A later selection pass re-reports evidence only while its fork is still eligible, and one drain can
424
+ * carry the tip past the horizon before its only pass, so evidence first reported here is recorded here.
425
+ */
426
+ export declare function recordEquivocations(rt: GroupRuntime, reported: readonly LeafEquivocation[]): Promise<void>;
427
+ /**
428
+ * `history()` from inside the group's own history backend call would wait on
429
+ * the worker that is waiting on that very call: refused `reentrant` at once.
430
+ */
431
+ export declare function assertNotInHistoryBackend(rt: GroupRuntime): void;
432
+ export declare function historyOf(rt: GroupRuntime): AsyncIterable<Rumor>;
433
+ /** Refuses an operation on a fenced group: `fenced`, carrying the fencing error as `cause`. */
434
+ export declare function assertNotFenced(rt: GroupRuntime, operation: string): void;
435
+ /**
436
+ * The session fence was just recorded on `rt`: every `synced()` wait for the group's first catch-up fails `fenced` now —
437
+ * a fenced group never opens its send gate. In-memory only and independent of the durable intent cleanup
438
+ * (`failAwaitingIntents`), so a fence whose store work failed or never runs still settles every waiter.
439
+ */
440
+ export declare function rejectSyncWaitersFenced(rt: GroupRuntime): void;
441
+ /**
442
+ * Every pending `synced()` wait for the group's first catch-up fails now, each with its own error from `errorOf`: the
443
+ * condition that ends it (a fence, a lost lease) means the send gate never opens in this session.
444
+ */
445
+ export declare function rejectSyncWaiters(rt: GroupRuntime, errorOf: () => Error): void;
446
+ /** The cause of a client-wide lease end signalled by the account store (`AccountStore.onLeaseEnded`). */
447
+ export declare function accountLeaseEndedError(): MarmotError;
448
+ /** The `no-lease` refusal of a `synced()` wait: the stores lost their lease before the group's first catch-up. */
449
+ export declare function syncedLeaseLostError(rt: GroupRuntime, cause: unknown): MarmotError;
450
+ /**
451
+ * Fences the group for good: the marker is persisted first (a reload stays
452
+ * fenced), then every further operation is refused. Idempotent.
453
+ */
454
+ export declare function fenceGroup(rt: GroupRuntime, cause: Error): Promise<void>;
455
+ export declare function encryptMediaOp(rt: GroupRuntime, bytes: unknown, options?: EncryptMediaOptions): Promise<EncryptedMedia>;
456
+ export declare function decryptMediaOp(rt: GroupRuntime, media: EncryptedMedia): Promise<Uint8Array>;
457
+ /** Test-only handles on module internals (mirrors pipeline.ts `__internal`); not part of any public surface. */
458
+ export declare const __internal: Readonly<{
459
+ reenqueueAndRedriveWithdrawn: typeof reenqueueAndRedriveWithdrawn;
460
+ }>;
461
+ export {};