@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,1365 @@
1
+ import { ADMISSION_LINEAGE_EXTENSION, advanceLineageRecords, breakdownWithdrawnCommit, forkPointNode, fencedError, canonicalPath, tagOf, equivocationKey, equivocationNotification, equivocationRecordOf, isRecordableEquivocation, leafTransition, readWindow, windowTransition, writeEquivocation, fenceCauseOf, writeFence, EQUIVOCATION_EXTENSION, FENCE_EXTENSION, } from '../history/index.js';
2
+ import { attachmentOf, decryptMedia, encryptMedia, sha256Hex } from '../media/index.js';
3
+ import { MarmotError } from '../shared/index.js';
4
+ import { nodeTypes } from '@941design/marmot-engine/mls';
5
+ import { deserializeClientState } from '@941design/marmot-engine/core';
6
+ import { deletePendingIntentRecord, isCommitRedrive, listPendingIntentRecords, nextSeq, OWN_COMMIT_EXTENSION, randomIntentId, raiseRootSpend, readOwnCommitMarker, redriveSpendOf, rootMarkerSpend, readTerminalLedgerEntry, writeOwnCommitMarker, writePendingIntentRecord, writeTerminalLedgerEntry, } from './group-records.js';
7
+ import { dropDelivered, enqueueTerminals, isTerminalNotification, OWN_CHANGE_OUTBOX_EXTENSION, readOutboxLenient, terminalKey } from './own-change-outbox.js';
8
+ import { clearOpaque, isEmptyOpaque, OPAQUE_EXTENSION } from './opaque-candidates.js';
9
+ import { ownAccountOf } from './rekey.js';
10
+ import { emitCleanupDispositions, noteCleanupCandidate } from './admission-cleanup.js';
11
+ // ---------------------------------------------------------------------------
12
+ // Notifications
13
+ // ---------------------------------------------------------------------------
14
+ export function subscribeNotifications(rt, listener) {
15
+ if (typeof listener !== 'function')
16
+ throw new MarmotError('invalid-options', 'MarmotGroup.onNotification: listener must be a function');
17
+ // A wrapper per registration: the same function registered twice is two subscriptions.
18
+ const entry = (n) => listener(n);
19
+ rt.notificationListeners.add(entry);
20
+ // S11: a terminal that found no listener (or that a crash or dispose left undelivered before this handle existed) stays in the
21
+ // outbox; the first listener is handed it now, detached from the caller's frame. Best effort: a failure leaves the entries for the next
22
+ // announcement -- the next terminal's commit, the next transition or the next first listener (a handle that subscribes again).
23
+ if (rt.notificationListeners.size === 1 && !rt.disposed) {
24
+ void Promise.resolve()
25
+ .then(() => rt.guard.detached(() => rt.run('terminalOutbox', (rtc) => announceTerminals(rtc))))
26
+ .catch(() => undefined);
27
+ }
28
+ return () => {
29
+ rt.notificationListeners.delete(entry);
30
+ };
31
+ }
32
+ /** Announces notifications whose state is already persisted (a settled disband, client/group-disband.ts). */
33
+ export function announceNotifications(rt, notifications) {
34
+ dispatch(rt, notifications);
35
+ }
36
+ /** 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. */
37
+ export function dispatch(rt, notifications) {
38
+ if (notifications.length === 0 || rt.notificationListeners.size === 0)
39
+ return;
40
+ for (const notification of notifications) {
41
+ const frozen = Object.freeze({ ...notification });
42
+ for (const listener of [...rt.notificationListeners]) {
43
+ rt.guard.detached(() => {
44
+ try {
45
+ listener(frozen);
46
+ }
47
+ catch {
48
+ // A throwing listener never breaks the operation that persisted the change.
49
+ }
50
+ });
51
+ }
52
+ }
53
+ }
54
+ /**
55
+ * S11 (AC-COMP-10, spec DD7 Delivery): hands every terminal in the outbox (`own-change-reapplied`, `own-change-lost`) to the
56
+ * group's listeners in the order it was decided, then removes what was handed over in a follow-up transaction. Called
57
+ * after a transaction that wrote terminals committed, when the first listener subscribes (the load path: a reloaded handle has
58
+ * no listener until the app attaches one) and ahead of every transition's own notifications (`deliverTransition`), so a
59
+ * retained terminal always precedes whatever this session adds. `resumePending` does not announce: on a first load it would
60
+ * find no listener, and every later case is covered by these.
61
+ *
62
+ * At-least-once, with the payload identical on every delivery: a crash or dispose before this runs leaves the entries for
63
+ * the next load; one after the dispatch and before the removal repeats them once. A disposed runtime delivers nothing and
64
+ * keeps the entries. With no listener nothing is delivered or removed (an entry is removed only once a listener was handed
65
+ * 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
66
+ * op (the queue serialises it with every other writer), except the `deliverTransition` path, which drops by key.
67
+ */
68
+ export async function announceTerminals(rt, except = new Set()) {
69
+ if (rt.disposed || rt.ctx.isDisposed() || rt.notificationListeners.size === 0)
70
+ return;
71
+ let entries;
72
+ let bad;
73
+ try {
74
+ const read = await rt.guard.call(rt.groupId, 'store', () => readOutboxLenient(rt.groupStore.extension(OWN_CHANGE_OUTBOX_EXTENSION)));
75
+ entries = read.entries.filter((e) => !except.has(e.key));
76
+ bad = read.bad;
77
+ }
78
+ catch {
79
+ return; // post-commit and best effort, like `dispatch`: the entries stay, the next announcement delivers them
80
+ }
81
+ if ((entries.length === 0 && bad.length === 0) || rt.disposed || rt.ctx.isDisposed())
82
+ return;
83
+ dispatch(rt, entries.map((e) => e.notification));
84
+ await removeDelivered(rt, entries, bad.map((b) => b.key));
85
+ // A row that does not decode is evicted by the drain above and reported once, like the other strict records (`groupStateFailed`).
86
+ for (const { error } of bad)
87
+ rt.ctx.emit('groupStateFailed', { groupId: rt.groupId, error });
88
+ }
89
+ /** Removes `delivered` from the outbox. A failure leaves them for the next announcement (one identical repeat); never throws. */
90
+ async function removeDelivered(rt, delivered, evict = []) {
91
+ try {
92
+ await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction(async (tx) => {
93
+ const view = tx.extension(OWN_CHANGE_OUTBOX_EXTENSION);
94
+ await dropDelivered(view, delivered);
95
+ for (const key of evict)
96
+ await view.delete(key);
97
+ }));
98
+ }
99
+ catch {
100
+ // Not delivered twice unless the next announcement finds the entries: that is the guarantee's one allowed repeat.
101
+ }
102
+ }
103
+ /** Ledger dispositions of a message this member delivered: `application` (received) or `own` (sent). */
104
+ const DELIVERED = new Set(['application', 'own']);
105
+ /** The ledger disposition of a message once withdrawn: still terminal (a redelivery is a duplicate), never withdrawn twice. */
106
+ export const WITHDRAWN_DISPOSITION = 'withdrawn';
107
+ /** Hex signature keys of every occupied leaf of `state`. */
108
+ function leafKeysOf(state) {
109
+ const out = new Set();
110
+ for (let i = 0; i < state.ratchetTree.length; i += 2) {
111
+ const node = state.ratchetTree[i];
112
+ if (node?.nodeType === nodeTypes.leaf)
113
+ out.add(Array.from(node.leaf.signaturePublicKey, (b) => b.toString(16).padStart(2, '0')).join(''));
114
+ }
115
+ return out;
116
+ }
117
+ /** Every leaf key on a state of the canonical paths of `windows` that `counts` (the tip state always). */
118
+ function canonicalLeavesOf(windows, afterTip, counts = () => true) {
119
+ const out = leafKeysOf(afterTip);
120
+ for (const window of windows) {
121
+ for (const node of canonicalPath(window)) {
122
+ if (!counts(node))
123
+ continue;
124
+ const state = node.tag === window.tipTag ? afterTip : node.snapshot === undefined ? undefined : deserializeClientState(node.snapshot);
125
+ if (state !== undefined)
126
+ for (const key of leafKeysOf(state))
127
+ out.add(key);
128
+ }
129
+ }
130
+ return out;
131
+ }
132
+ /**
133
+ * Leaf keys held by an abandoned state and by no state of the after canonical path from the fork point on (see
134
+ * TransitionPlan.withdrawnLeaves). The fork point is the last state both branches share; the canonical states
135
+ * before it are not what the rewind replaced. Counting them would hide a re-added leaf the rewind withdrew whenever
136
+ * the group had held that leaf earlier still (a device removed, then re-enrolled with the same leaf key, inside the
137
+ * horizon). A leaf the fork point itself holds is not withdrawn:
138
+ * it was there before either branch, and its absence on the new branch is a departure there, not a lost Add.
139
+ */
140
+ function withdrawnLeavesOf(before, beforeTip, abandoned, afters, afterTip) {
141
+ const stateOf = (window, tip, tag) => {
142
+ if (tag === window.tipTag)
143
+ return tip;
144
+ const snapshot = window.nodes.get(tag)?.snapshot;
145
+ return snapshot === undefined ? undefined : deserializeClientState(snapshot);
146
+ };
147
+ const onAbandoned = new Set();
148
+ for (const tag of abandoned) {
149
+ const state = stateOf(before, beforeTip, tag);
150
+ if (state !== undefined)
151
+ for (const key of leafKeysOf(state))
152
+ onAbandoned.add(key);
153
+ }
154
+ if (onAbandoned.size === 0)
155
+ return [];
156
+ // The fork point: the newest state of the old canonical path still on a new one. None retained (the fork is
157
+ // below every floor): every retained canonical state counts, as conservative as before.
158
+ const afterTags = new Set(afters.flatMap((w) => canonicalPath(w).map((n) => n.tag)));
159
+ const fork = canonicalPath(before).filter((n) => afterTags.has(n.tag)).at(-1);
160
+ const canonical = canonicalLeavesOf(afters, afterTip, (node) => fork === undefined || node.epoch >= fork.epoch);
161
+ return [...onAbandoned].filter((k) => !canonical.has(k)).sort();
162
+ }
163
+ /**
164
+ * {@link leafTransition} with the retired-key predicate of AC-NOTIF-6 wired in (epic marmot-device-key-rotation).
165
+ * The history layer asks `isRetiredKey` only for a `key_package`-source leaf a commit added (an Add), so the transition
166
+ * is first computed with a probe that answers `false` and notes whether it was asked at all: an ordinary transition
167
+ * (a message, a rotation, a Remove) never reads the account store. Only an Add commit takes the lineage snapshot
168
+ * (`devices.lineage()`: a frozen copy of the recorded links, awaited HERE, before the transition's store
169
+ * transaction) and recomputes with the real, synchronous predicate: a key the local registry holds as a non-head key
170
+ * of the local account's lineage. A head key and an unknown key answer `false`. Detection only — the snapshot
171
+ * failing means no `retired-key-readded`, never a refused or altered transition.
172
+ */
173
+ async function leafNotifications(rt, before, beforeTip, after, afterTip) {
174
+ let asked = false;
175
+ const probed = leafTransition(before, beforeTip, after, afterTip, {
176
+ isRetiredKey: () => {
177
+ asked = true;
178
+ return false;
179
+ },
180
+ });
181
+ const read = rt.ctx.deviceLineage?.read;
182
+ if (!asked || read === undefined)
183
+ return probed;
184
+ try {
185
+ const retired = await rt.guard.call(rt.groupId, 'store', () => read());
186
+ // The account is the local leaf's own credential in the after-state: ingest makes no signer call for this detection.
187
+ const self = ownAccountOf(afterTip);
188
+ if (self === undefined)
189
+ return probed;
190
+ return leafTransition(before, beforeTip, after, afterTip, { isRetiredKey: (account, leafKey) => account === self && retired.isRetired(leafKey) });
191
+ }
192
+ catch {
193
+ return probed;
194
+ }
195
+ }
196
+ /**
197
+ * The announcements of moving the group from `before` (tip `beforeTip`) to
198
+ * `after` (tip `afterTip`) with `messages` accepted on the way.
199
+ *
200
+ * A message delivered earlier is withdrawn when the state it was delivered
201
+ * under (its ledgered `node`, the ordering key's `acceptedDigest`) left the
202
+ * canonical path — whether this member received it (`application`) or sent
203
+ * it (`own`) — or when the engine retracted it itself (`invalidated`, its
204
+ * in-memory delivery ledger: `retracted`, by event id). Messages of this
205
+ * transition (`messages`) are never withdrawn, only not announced.
206
+ */
207
+ export async function planTransition(rt, before, beforeTip, after, afterTip, messages, retracted = new Set(),
208
+ /**
209
+ * The window the notifications are diffed against when it differs from the
210
+ * persisted `after`: one reaching down to `before`'s floor, so commits a
211
+ * batch applied and the horizon already pruned from `after` still count.
212
+ */
213
+ diffAgainst = after) {
214
+ const transition = windowTransition(before, beforeTip, diffAgainst, afterTip);
215
+ // marmot-leaf-removed-notification: per-leaf removals over the same canonical-path change.
216
+ const leafChanges = await leafNotifications(rt, before, beforeTip, diffAgainst, afterTip);
217
+ const abandoned = new Set(transition.abandonedTags);
218
+ const batchIds = new Set(messages.map((m) => m.eventId));
219
+ const kept = messages.filter((m) => !abandoned.has(m.orderingKey.acceptedDigest));
220
+ const withdrawn = [];
221
+ // Carries the ledger entry's own `at` (client-clock ms when CONFIRMED — finer-grained and always present,
222
+ // unlike `createdAt`'s second-precision Nostr timestamp) alongside the public shape purely to SORT by it
223
+ // below — `view.keys()`'s own enumeration order is a storage-layer detail (event ids are content hashes;
224
+ // nothing chronological about it), so without sorting, a rewind withdrawing SEVERAL of this member's own
225
+ // self-updates at once would hand `reenqueueWithdrawnSelfUpdates` (pipeline.ts) an effectively arbitrary
226
+ // order to assign `seq` in — and `seq` is what the re-enqueue drive's own deterministic-leader pick
227
+ // (driveReenqueuedSelfUpdate) relies on to mean "original withdrawal order".
228
+ // A same-millisecond tie (a frozen or coarse clock, two confirmations in one tick) falls back to the commit's own
229
+ // epoch — the abandoned node's, from `before` — and only then to the event id, so the order stays chronological.
230
+ const withdrawnSelfUpdates = [];
231
+ const ownCommitCandidates = [];
232
+ if (abandoned.size > 0 || retracted.size > 0) {
233
+ const view = rt.groupStore.artifact('terminalLedger');
234
+ const ids = abandoned.size > 0 ? await rt.guard.call(rt.groupId, 'store', () => view.keys()) : [...retracted];
235
+ for (const eventId of ids) {
236
+ if (batchIds.has(eventId))
237
+ continue;
238
+ const entry = await rt.guard.call(rt.groupId, 'store', () => readTerminalLedgerEntry(view, eventId));
239
+ if (entry === undefined || !DELIVERED.has(entry.disposition) || entry.node === undefined)
240
+ continue;
241
+ if (abandoned.has(entry.node) || retracted.has(eventId)) {
242
+ // S9/S1 (AC-MARK-1/2): an own commit that declared a change (`ownCommitRoot`) never had a message notification
243
+ // either — never surface it as message-withdrawn. It is classified below ({@link ownCommitTransition}): marked
244
+ // withdrawn in the ledger by `markWithdrawn`, and re-driven when its marker says what it changed.
245
+ if (entry.ownCommitRoot !== undefined) {
246
+ if (abandoned.has(entry.node)) {
247
+ const epoch = before.nodes.get(entry.node)?.epoch ?? diffAgainst.nodes.get(entry.node)?.epoch ?? Number.MAX_SAFE_INTEGER;
248
+ ownCommitCandidates.push({ eventId, entry: { ...entry, node: entry.node }, at: entry.at, epoch });
249
+ }
250
+ continue;
251
+ }
252
+ // A self-update commit's own entry never had a message notification: mark it withdrawn in the
253
+ // ledger (recordTransition/markWithdrawn) but never surface it as message-withdrawn (AC-RACE-1).
254
+ if (entry.selfUpdateIntentId !== undefined) {
255
+ const epoch = before.nodes.get(entry.node)?.epoch ?? diffAgainst.nodes.get(entry.node)?.epoch ?? Number.MAX_SAFE_INTEGER;
256
+ withdrawnSelfUpdates.push({ eventId, originalIntentId: entry.selfUpdateIntentId, attempts: entry.attempts ?? 0, ...(entry.rekey === undefined ? {} : { rekey: entry.rekey }), at: entry.at, epoch });
257
+ }
258
+ else {
259
+ withdrawn.push({ type: 'message-withdrawn', eventId, acceptedDigest: entry.node });
260
+ }
261
+ }
262
+ }
263
+ withdrawnSelfUpdates.sort((a, b) => a.at - b.at || a.epoch - b.epoch || (a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0));
264
+ }
265
+ const withdrawnLeaves = abandoned.size > 0 ? withdrawnLeavesOf(before, beforeTip, abandoned, [after, diffAgainst], afterTip) : [];
266
+ const canonicalTags = new Set([...canonicalPath(after), ...canonicalPath(diffAgainst)].map((n) => n.tag));
267
+ const own = await ownCommitTransition(rt, { before, beforeTip, afters: after === diffAgainst ? [after] : [after, diffAgainst], afterTip, canonicalTags, candidates: ownCommitCandidates });
268
+ return {
269
+ window: after,
270
+ // Order: state withdrawals, leaf withdrawals, message withdrawals, then (AC-SIG-1) the own changes the withdrawal
271
+ // named, the applied changes, and the own changes a restore put back in force.
272
+ notifications: [...transition.withdrawn, ...leafChanges.withdrawn, ...withdrawn, ...own.withdrawnNotifications, ...transition.applied, ...leafChanges.applied, ...own.reappliedNotifications, ...kept],
273
+ kept,
274
+ withdrawn,
275
+ rewound: abandoned.size > 0 || transition.withdrawn.length > 0 || retracted.size > 0,
276
+ ...(withdrawnLeaves.length === 0 ? {} : { withdrawnLeaves }),
277
+ ...(abandoned.size === 0 ? {} : { abandonedTags: [...abandoned] }),
278
+ ...(withdrawnSelfUpdates.length === 0 ? {} : { selfUpdateOrder: Object.fromEntries(withdrawnSelfUpdates.map((w) => [w.eventId, { at: w.at, epoch: w.epoch }])) }),
279
+ ...(withdrawnSelfUpdates.length === 0 ? {} : { withdrawnSelfUpdates: withdrawnSelfUpdates.map(({ eventId, originalIntentId, attempts, rekey }) => ({ eventId, originalIntentId, attempts, ...(rekey === undefined ? {} : { rekey }) })) }),
280
+ canonicalLeaves: () => {
281
+ const wasCanonical = new Set(canonicalPath(before).map((n) => n.tag));
282
+ return canonicalLeavesOf([after, diffAgainst], afterTip, (node) => !wasCanonical.has(node.tag));
283
+ },
284
+ canonicalTags,
285
+ ...(own.withdrawn.length === 0 ? {} : { withdrawnOwnCommits: own.withdrawn }),
286
+ ...(own.entries.length === 0 ? {} : { withdrawnOwnCommitEntries: own.entries }),
287
+ ...(own.unreadable.length === 0 ? {} : { unreadableOwnCommits: own.unreadable }),
288
+ ...(own.restored.length === 0 ? {} : { restoredOwnCommits: own.restored }),
289
+ lineage: { before, diff: diffAgainst, tip: afterTip },
290
+ };
291
+ }
292
+ /**
293
+ * Epic marmot-invitation-outcomes S5 (SC-6 I16): the `admission-removed` changes of a marker — those its change list already holds (a
294
+ * re-drive's marker, a later withdrawal), else one per target its intent declared (`declared.admissions`).
295
+ */
296
+ function admissionChangesOf(marker) {
297
+ if (marker.changes !== undefined)
298
+ return marker.changes.filter((c) => c.change.type === 'admission-removed');
299
+ return (marker.declared?.admissions ?? []).map((target) => ({
300
+ change: { type: 'admission-removed', account: target.account, leafKey: target.anchor.leafKey, candidateId: target.candidateId },
301
+ fork: {},
302
+ target,
303
+ }));
304
+ }
305
+ /** `MarkerChange`s of `forked`: an Add gets the KeyPackage the marker kept for that leaf key (`undefined`: the marker names none — unreadable). */
306
+ function markerChangesOf(forked, marker) {
307
+ const out = [];
308
+ for (const c of forked) {
309
+ if (c.change.type !== 'member-added') {
310
+ out.push(c);
311
+ continue;
312
+ }
313
+ const leafKey = c.change.leafKey;
314
+ const invitee = marker.invitees?.find((i) => i.leafKey === leafKey);
315
+ if (invitee === undefined)
316
+ return undefined;
317
+ out.push({ ...c, keyPackage: { event: invitee.event, inviteeRef: invitee.inviteeRef } });
318
+ }
319
+ return out;
320
+ }
321
+ /**
322
+ * Epic marmot-rewound-own-commit-no-signal S1 (DD2, DD11-DD14, DD17): the own-commit half of a transition's plan.
323
+ * - Every `candidate` (an own-commit ledger entry whose node the transition abandoned) is withdrawn in the ledger.
324
+ * One without a marker is a DD17 link-only entry (the stale-retained settle path): withdrawn silently, nothing else.
325
+ * - A marked one is broken down into the changes its intent declared with their fork-point values
326
+ * ({@link breakdownWithdrawnCommit}); a marker that already holds `changes` (a later withdrawal of the same node, or a
327
+ * re-drive commit's marker) is used as it stands (DD14: written once). An unreadable commit has no named changes: it
328
+ * is listed in `unreadable` and nothing else happens (see {@link TransitionPlan.unreadableOwnCommits}).
329
+ * - A marker node of the plan's canonical path whose entry is `withdrawn` is a restore (DD14): decided on the marker, per root.
330
+ * One notification per change, for the most recent marked node of each root (one signal per root and withdrawal).
331
+ * The `invitee-missing` unreadable and the missing-digest guard are belt-and-braces: a marker written by the confirm writer always names the
332
+ * invitee of each Add it declared, and every node an own commit leaves in the window carries its digest.
333
+ */
334
+ async function ownCommitTransition(rt, input) {
335
+ const { before, beforeTip, afters, afterTip, canonicalTags } = input;
336
+ const store = (fn) => rt.guard.call(rt.groupId, 'store', fn);
337
+ const markers = rt.groupStore.extension(OWN_COMMIT_EXTENSION);
338
+ const nodeOf = (tag) => before.nodes.get(tag) ?? afters.map((w) => w.nodes.get(tag)).find((n) => n !== undefined);
339
+ // Two mechanisms carry it (both needed): this max over the retained markers seeds every record, whatever node is withdrawn (covers
340
+ // a retained stale node that was never restored over); the raise of a restored node's marker (cancelRestoredReenqueues) keeps the
341
+ // spend on the original itself once the abandoned branches' markers are pruned below the window floor.
342
+ // DD9 (AC-DRIVE-4): the publish budget is the ROOT's, not the node's. A restore cycle (the original comes back, the re-drive's
343
+ // branch is abandoned, then the original is abandoned again) must not reset the spend to the original's marker: the record a
344
+ // withdrawal writes starts from the highest `attempts` any retained marker of the root carries.
345
+ const spendByRoot = new Map();
346
+ let spendRead = false;
347
+ const rootSpend = async (root) => {
348
+ if (!spendRead) {
349
+ spendRead = true;
350
+ for (const eventId of await store(() => markers.keys())) {
351
+ const m = await store(() => readOwnCommitMarker(markers, eventId));
352
+ if (m !== undefined)
353
+ spendByRoot.set(m.root, Math.max(spendByRoot.get(m.root) ?? 0, m.attempts));
354
+ }
355
+ }
356
+ return spendByRoot.get(root) ?? 0;
357
+ };
358
+ const withdrawn = [];
359
+ const entries = [];
360
+ const unreadable = [];
361
+ const withdrawnNotifications = [];
362
+ const found = [];
363
+ const candidates = [...input.candidates].sort((a, b) => a.at - b.at || a.epoch - b.epoch || (a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0));
364
+ for (const c of candidates) {
365
+ entries.push(c.eventId);
366
+ const marker = await store(() => readOwnCommitMarker(markers, c.eventId));
367
+ if (marker === undefined)
368
+ continue; // DD17: a link-only entry
369
+ const node = nodeOf(c.entry.node);
370
+ const commitDigest = node?.digest;
371
+ if (node === undefined || commitDigest === undefined) {
372
+ unreadable.push({ eventId: c.eventId, rootIntentId: marker.root, node: c.entry.node, reason: 'state-missing' });
373
+ continue;
374
+ }
375
+ // Fork-point values, forkEpoch and winner evidence are RECOMPUTED at every withdrawal (against this transition's windows).
376
+ // What is written once (DD14) is only WHICH changes the original's marker lists: a marker that already holds `changes`
377
+ // (a later withdrawal of the same node, or a re-drive commit's marker) filters the diff by change identity; the values it
378
+ // carries are not authoritative.
379
+ const declared = marker.changes !== undefined
380
+ ? { only: marker.changes.map((m) => m.change) }
381
+ : { ...marker.declared, ...(marker.invitees === undefined ? {} : { added: marker.invitees.map((i) => i.leafKey) }) };
382
+ const broken = breakdownWithdrawnCommit({ before, beforeTip, afters, afterTip, node, declared });
383
+ if (!broken.readable) {
384
+ unreadable.push({ eventId: c.eventId, rootIntentId: marker.root, node: c.entry.node, reason: broken.reason });
385
+ continue;
386
+ }
387
+ // Epic marmot-invitation-outcomes S5 (SC-6 I16): a scoped cleanup's change is DECLARED (the marker's `declared.admissions`, or the
388
+ // `admission-removed` entries a marker's change list already holds), never derived from the diff — whose `member-removed` a
389
+ // cleanup never declares, so it is filtered out above. It carries its target; it has no fork-point values.
390
+ const admissions = admissionChangesOf(marker);
391
+ if (broken.changes.length === 0 && admissions.length === 0)
392
+ continue; // nothing the intent declared shows in the diff: nothing to re-drive or name
393
+ const diffChanges = markerChangesOf(broken.changes, marker);
394
+ if (diffChanges === undefined) {
395
+ unreadable.push({ eventId: c.eventId, rootIntentId: marker.root, node: c.entry.node, reason: 'invitee-missing' });
396
+ continue;
397
+ }
398
+ const changes = [...diffChanges, ...admissions];
399
+ // Set exactly when the diff's `changes` are non-empty; a cleanup-only commit takes the fork point of the same windows.
400
+ const forkEpoch = broken.forkEpoch ?? forkPointNode(before, afters)?.epoch;
401
+ if (forkEpoch === undefined) {
402
+ unreadable.push({ eventId: c.eventId, rootIntentId: marker.root, node: c.entry.node, reason: 'state-missing' });
403
+ continue;
404
+ }
405
+ found.push({
406
+ epoch: c.epoch,
407
+ at: c.at,
408
+ commit: {
409
+ eventId: c.eventId,
410
+ rootIntentId: marker.root,
411
+ node: c.entry.node,
412
+ at: c.at,
413
+ epoch: c.epoch,
414
+ commitDigest,
415
+ changes,
416
+ forkEpoch,
417
+ attempts: Math.max(marker.attempts, await rootSpend(marker.root)),
418
+ ...(marker.changes === undefined ? { markerUpdate: { ...marker, changes, forkEpoch } } : {}),
419
+ },
420
+ });
421
+ }
422
+ // One entry per root: the most recent marked node (deepest epoch, then latest `at`). Every candidate was listed in `entries`
423
+ // above for the ledger flip.
424
+ const best = new Map();
425
+ for (const f of found) {
426
+ const known = best.get(f.commit.rootIntentId);
427
+ if (known === undefined || f.epoch > known.epoch || (f.epoch === known.epoch && f.at > known.at))
428
+ best.set(f.commit.rootIntentId, f);
429
+ }
430
+ for (const f of found) {
431
+ if (best.get(f.commit.rootIntentId) !== f)
432
+ continue;
433
+ withdrawn.push(f.commit);
434
+ for (const change of f.commit.changes)
435
+ withdrawnNotifications.push({ type: 'own-change-withdrawn', intentId: f.commit.rootIntentId, commitDigest: f.commit.commitDigest, change: change.change });
436
+ }
437
+ // DD14: a marked node on the canonical path whose entry is `withdrawn` is restored (decided on the marker, per root).
438
+ const restoredByRoot = new Map();
439
+ if (canonicalTags.size > 0) {
440
+ const ledger = rt.groupStore.artifact('terminalLedger');
441
+ for (const eventId of await store(() => markers.keys())) {
442
+ const marker = await store(() => readOwnCommitMarker(markers, eventId));
443
+ if (marker === undefined || !canonicalTags.has(marker.node))
444
+ continue;
445
+ const entry = await store(() => readTerminalLedgerEntry(ledger, eventId));
446
+ if (entry?.disposition !== WITHDRAWN_DISPOSITION || entry.ownCommitRoot === undefined)
447
+ continue;
448
+ const node = nodeOf(marker.node);
449
+ const known = restoredByRoot.get(marker.root);
450
+ const epoch = node?.epoch ?? -1;
451
+ if (known === undefined)
452
+ restoredByRoot.set(marker.root, { eventIds: [eventId], epoch, commitDigest: node?.digest, changes: marker.changes ?? [] });
453
+ else {
454
+ known.eventIds.push(eventId);
455
+ if (epoch > known.epoch)
456
+ Object.assign(known, { epoch, commitDigest: node?.digest, changes: marker.changes ?? [] });
457
+ }
458
+ }
459
+ }
460
+ // Deterministic order: the chosen node's epoch, then the root id (the markers' enumeration order is a storage detail).
461
+ const restoredRoots = [...restoredByRoot].sort(([ra, a], [rb, b]) => a.epoch - b.epoch || (ra < rb ? -1 : ra > rb ? 1 : 0));
462
+ const restored = restoredRoots.map(([rootIntentId, r]) => ({ rootIntentId, eventIds: r.eventIds.sort() }));
463
+ const reappliedNotifications = [];
464
+ for (const [rootIntentId, r] of restoredRoots) {
465
+ if (r.commitDigest === undefined)
466
+ continue; // no digest to name: restored in the ledger, not announced
467
+ for (const change of r.changes)
468
+ reappliedNotifications.push({ type: 'own-change-reapplied', intentId: rootIntentId, commitDigest: r.commitDigest, change: change.change });
469
+ }
470
+ return { withdrawn, entries, unreadable, restored, withdrawnNotifications, reappliedNotifications };
471
+ }
472
+ /** Rewrites the ledger entries of `plan`'s withdrawn messages, AND its withdrawn self-updates (never announced
473
+ * as message-withdrawn, but withdrawn in the ledger all the same) and its withdrawn own commits (S1) — inside the transition's own transaction. */
474
+ export async function markWithdrawn(view, plan, at) {
475
+ for (const eventId of plan.withdrawnOwnCommitEntries ?? []) {
476
+ const entry = await readTerminalLedgerEntry(view, eventId);
477
+ if (entry === undefined)
478
+ continue;
479
+ await writeTerminalLedgerEntry(view, eventId, { ...entry, disposition: WITHDRAWN_DISPOSITION, at });
480
+ }
481
+ for (const w of plan.withdrawn) {
482
+ const entry = await readTerminalLedgerEntry(view, w.eventId);
483
+ if (entry === undefined)
484
+ continue;
485
+ await writeTerminalLedgerEntry(view, w.eventId, { ...entry, disposition: WITHDRAWN_DISPOSITION, at });
486
+ }
487
+ for (const w of plan.withdrawnSelfUpdates ?? []) {
488
+ const entry = await readTerminalLedgerEntry(view, w.eventId);
489
+ if (entry === undefined)
490
+ continue;
491
+ await writeTerminalLedgerEntry(view, w.eventId, { ...entry, disposition: WITHDRAWN_DISPOSITION, at });
492
+ }
493
+ }
494
+ /**
495
+ * Whether a message sent under the state `key.acceptedDigest` names is still
496
+ * on the group's canonical branch: that state is on `window`'s canonical
497
+ * path — or below the window's floor (pruned: nothing left to contradict
498
+ * it). A state at or above the floor that is not on the path was abandoned.
499
+ */
500
+ export function sentOnCanonicalBranch(window, key) {
501
+ const path = canonicalPath(window);
502
+ if (key.acceptedDigest !== '' && path.some((n) => n.tag === key.acceptedDigest))
503
+ return true;
504
+ return Number(key.epoch) < (path[0]?.epoch ?? 0);
505
+ }
506
+ /** The announcement of an own message whose send-time branch was abandoned before its confirmation (never kept). */
507
+ export function lostMessagePlan(rt, lost) {
508
+ return {
509
+ window: rt.window,
510
+ notifications: [{ type: 'message-withdrawn', eventId: lost.eventId, acceptedDigest: lost.orderingKey.acceptedDigest }],
511
+ kept: [],
512
+ withdrawn: [],
513
+ rewound: false,
514
+ canonicalTags: new Set(),
515
+ };
516
+ }
517
+ // ---------------------------------------------------------------------------
518
+ // Settlement recheck marker (device outcomes read from a branch a rewind left)
519
+ // ---------------------------------------------------------------------------
520
+ /**
521
+ * Group extension marking that a persisted transition of the group rewound
522
+ * (left states it had been on) since the device service last rechecked the
523
+ * outcomes it settled from the group's tree (an approval's `enrolled`, a
524
+ * forget's `removed`). Written in the transition's own transaction, so a
525
+ * crash before the in-memory rewind announcement still leaves it; cleared
526
+ * by the device service only once its recheck is conclusive.
527
+ */
528
+ export const SETTLEMENT_RECHECK_EXTENSION = 'marmot.settlement-recheck';
529
+ const RECHECK_KEY = 'pending';
530
+ function decodeRecheck(raw) {
531
+ if (typeof raw === 'number')
532
+ return { token: raw };
533
+ if (typeof raw !== 'object' || raw === null)
534
+ return undefined;
535
+ const r = raw;
536
+ if (typeof r.t !== 'number')
537
+ return undefined;
538
+ const leaves = Array.isArray(r.w) && r.w.every((k) => typeof k === 'string') ? r.w : [];
539
+ return { token: r.t, withdrawnLeaves: leaves };
540
+ }
541
+ /**
542
+ * The marker's part of one recorded transition (inside its transaction). A rewind sets (or bumps) it — a later
543
+ * rewind gets a new token, so a recheck that read the old one cannot clear it — and adds the leaves it withdrew.
544
+ * S20 round 2: every transition, while a marker exists, first drops from its evidence the leaves present on the new
545
+ * canonical path: a withdrawn leaf seen canonically again (re-added) is not withdrawn any more, and must not reopen
546
+ * an approval after it LEAVES there (a resurrection). A transition that did not rewind never creates a marker.
547
+ */
548
+ export async function updateSettlementRecheck(view, plan) {
549
+ const current = decodeRecheck(await view.get(RECHECK_KEY));
550
+ if (current === undefined && !plan.rewound)
551
+ return;
552
+ const canonical = current?.withdrawnLeaves !== undefined && current.withdrawnLeaves.length > 0 ? plan.canonicalLeaves?.() : undefined;
553
+ const kept = (current?.withdrawnLeaves ?? []).filter((k) => canonical === undefined || !canonical.has(k));
554
+ const leaves = [...new Set([...kept, ...(plan.rewound ? (plan.withdrawnLeaves ?? []) : [])])].sort();
555
+ if (!plan.rewound) {
556
+ // A pre-S20 marker (no evidence) stays as it is; an unchanged one is not rewritten.
557
+ if (current === undefined || current.withdrawnLeaves === undefined || leaves.length === current.withdrawnLeaves.length)
558
+ return;
559
+ await view.put(RECHECK_KEY, { t: current.token, w: leaves });
560
+ return;
561
+ }
562
+ await view.put(RECHECK_KEY, { t: (current?.token ?? 0) + 1, w: leaves });
563
+ }
564
+ /** The marker, or `undefined` when none is set. */
565
+ export async function readSettlementRecheckRecord(view) {
566
+ return decodeRecheck(await view.get(RECHECK_KEY));
567
+ }
568
+ /** The marker's token, or `undefined` when none is set. */
569
+ export async function readSettlementRecheck(view) {
570
+ return (await readSettlementRecheckRecord(view))?.token;
571
+ }
572
+ /** Clears the marker when it still carries `token` (inside the caller's transaction). */
573
+ export async function clearSettlementRecheck(view, token) {
574
+ if ((await readSettlementRecheck(view)) === token)
575
+ await view.delete(RECHECK_KEY);
576
+ }
577
+ // ---------------------------------------------------------------------------
578
+ // The history outbox: backend updates are durable with the transition
579
+ // ---------------------------------------------------------------------------
580
+ /**
581
+ * Group extension holding the history backend updates (withdrawals, appends)
582
+ * of transitions that committed but whose updates have not reached the
583
+ * backend yet. Written in the transition's own transaction, drained in
584
+ * order, each op deleted once the backend took it — so a crash between the
585
+ * commit and the delivery never leaves the backend holding a message the
586
+ * ledger already withdrew, or missing one it accepted.
587
+ */
588
+ export const HISTORY_OUTBOX_EXTENSION = 'marmot.history-outbox';
589
+ const SEQ_KEY = 'seq';
590
+ const OP_PREFIX = 'op:';
591
+ /**
592
+ * A backend that keeps refusing one op gives it up after this many attempts
593
+ * (later ops are not held hostage); documented on `HistoryBackend`.
594
+ */
595
+ export const MAX_HISTORY_ATTEMPTS = 5;
596
+ function encodeOp(op) {
597
+ if (op.kind === 'withdraw')
598
+ return { k: 'withdraw', ids: [...op.eventIds], n: op.attempts };
599
+ const { orderingKey: o } = op.entry;
600
+ return {
601
+ k: 'append',
602
+ e: op.entry.eventId,
603
+ r: op.entry.rumor,
604
+ o: { account: o.account, leafIndex: o.leafIndex, epoch: o.epoch, generation: o.generation, acceptedDigest: o.acceptedDigest },
605
+ n: op.attempts,
606
+ };
607
+ }
608
+ function decodeOp(groupId, raw) {
609
+ if (typeof raw !== 'object' || raw === null || raw instanceof Uint8Array || Array.isArray(raw))
610
+ return undefined;
611
+ const r = raw;
612
+ const attempts = typeof r.n === 'number' ? r.n : 0;
613
+ if (r.k === 'withdraw' && Array.isArray(r.ids) && r.ids.every((id) => typeof id === 'string'))
614
+ return { kind: 'withdraw', eventIds: r.ids, attempts };
615
+ const o = r.o;
616
+ if (r.k !== 'append' || typeof r.e !== 'string' || typeof r.r !== 'object' || r.r === null || typeof o !== 'object' || o === null)
617
+ return undefined;
618
+ if (typeof o.account !== 'string' || typeof o.leafIndex !== 'number' || typeof o.epoch !== 'bigint' || typeof o.generation !== 'number' || typeof o.acceptedDigest !== 'string')
619
+ return undefined;
620
+ const orderingKey = Object.freeze({ account: o.account, leafIndex: o.leafIndex, epoch: o.epoch, generation: o.generation, acceptedDigest: o.acceptedDigest });
621
+ return { kind: 'append', entry: { groupId, eventId: r.e, rumor: r.r, orderingKey }, attempts };
622
+ }
623
+ /**
624
+ * The durable half of every own commit a transition withdrew, written in the SAME transaction as the withdrawal (a crash can never
625
+ * leave the withdrawal without its record; the caller only DRIVES the durable records afterwards, detached):
626
+ * - AC-RACE-1: one self-update re-enqueue record per withdrawn self-update (`reenqueuedFrom` = the root; a rekey stays a rekey);
627
+ * - epic marmot-rewound-own-commit-no-signal S1 (AC-REC-1/2, DD14): one `{ kind: 'commit', intent: { type: 'commit' } }` re-drive record per
628
+ * root with `changes` + `forkEpoch` (the fork-point breakdown; the record is the verdict carrier from here on) and the carried `attempts`.
629
+ */
630
+ async function reenqueueAndRedriveWithdrawn(tx, plan, epoch, dedupAcrossStates = true) {
631
+ const selfUpdates = plan.withdrawnSelfUpdates ?? [];
632
+ const ownCommits = plan.withdrawnOwnCommits ?? [];
633
+ if (selfUpdates.length === 0 && ownCommits.length === 0)
634
+ return;
635
+ const view = tx.artifact('pendingIntents');
636
+ // The commits' markers get their change list once, at the first withdrawal (DD14).
637
+ const markers = tx.extension(OWN_COMMIT_EXTENSION);
638
+ for (const w of ownCommits)
639
+ if (w.markerUpdate !== undefined)
640
+ await writeOwnCommitMarker(markers, w.eventId, w.markerUpdate);
641
+ const restoredRoots = new Set((plan.restoredOwnCommits ?? []).map((r) => r.rootIntentId));
642
+ // Deduplicated by root across EVERY record state (a record already carrying it was already re-driven), both families alike.
643
+ const existing = new Set(dedupAcrossStates ? (await listPendingIntentRecords(view)).map((r) => r.reenqueuedFrom).filter((id) => id !== undefined) : []);
644
+ const items = [];
645
+ for (const w of selfUpdates) {
646
+ items.push({
647
+ at: plan.selfUpdateOrder?.[w.eventId]?.at ?? 0,
648
+ epoch: plan.selfUpdateOrder?.[w.eventId]?.epoch ?? 0,
649
+ eventId: w.eventId,
650
+ rank: 0,
651
+ write: async () => {
652
+ if (existing.has(w.originalIntentId))
653
+ return;
654
+ existing.add(w.originalIntentId); // the SAME plan never double-withdraws one root id, but stay defensive
655
+ await writePendingIntentRecord(view, {
656
+ v: 1,
657
+ intentId: randomIntentId(),
658
+ seq: await nextSeq(view),
659
+ kind: 'self-update',
660
+ state: 'pending-publish',
661
+ parentEpoch: epoch,
662
+ // AC-REKEY-7: a withdrawn rekey is re-driven as a rekey toward the same target (a plain one stays plain).
663
+ intent: w.rekey === undefined ? { type: 'self-update' } : { type: 'self-update', rekey: { target: w.rekey } },
664
+ attempts: w.attempts,
665
+ reenqueuedFrom: w.originalIntentId,
666
+ });
667
+ },
668
+ });
669
+ }
670
+ for (const w of ownCommits) {
671
+ items.push({
672
+ at: w.at ?? 0,
673
+ epoch: w.epoch ?? 0,
674
+ eventId: w.eventId,
675
+ rank: 1,
676
+ write: async () => {
677
+ // A restored root writes nothing (DD14; cancelRestoredReenqueues would delete it anyway — this spares the write-then-delete).
678
+ if (restoredRoots.has(w.rootIntentId) || existing.has(w.rootIntentId))
679
+ return;
680
+ existing.add(w.rootIntentId);
681
+ await writePendingIntentRecord(view, {
682
+ v: 1,
683
+ intentId: randomIntentId(),
684
+ seq: await nextSeq(view),
685
+ kind: 'commit',
686
+ state: 'pending-publish',
687
+ parentEpoch: epoch,
688
+ intent: { type: 'commit' },
689
+ attempts: w.attempts,
690
+ reenqueuedFrom: w.rootIntentId,
691
+ changes: w.changes,
692
+ forkEpoch: w.forkEpoch,
693
+ });
694
+ },
695
+ });
696
+ }
697
+ items.sort((x, y) => x.at - y.at || x.epoch - y.epoch || (x.eventId < y.eventId ? -1 : x.eventId > y.eventId ? 1 : 0) || x.rank - y.rank);
698
+ for (const item of items)
699
+ await item.write();
700
+ }
701
+ /**
702
+ * S5 (AC-RACE-1): a pending re-enqueue (`reenqueuedFrom`) whose ORIGINAL rotation this transition puts back on the
703
+ * canonical path — the withdrawn branch won fork recovery back — owes nothing: it is deleted and the rotation's
704
+ * ledger entries restored to `own`, in the transition's own transaction. That includes one whose envelope awaits
705
+ * its publish retry: no relay accepted it, it was minted on the branch this transition abandons, and its publish
706
+ * retry finds no record and does nothing. A `pending-confirm` one is KEPT: a relay accepted it, peers that applied
707
+ * it may converge on its branch, and this client cannot re-process its own commit from a relay — deleting the
708
+ * record would discard the only pending state that lets it follow, forking it off for good. `confirmRecord`
709
+ * resolves it through its normal path; the residual is a possible extra rotation when the original's branch also
710
+ * stays canonical (the group stays consistent — the accepted-own-commit class, BACKLOG
711
+ * `own-commit-ack-lost-max-attempts-terminal`). That keeping is the SELF-UPDATE re-enqueue's: a commit re-drive of a restored
712
+ * 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) --
713
+ * 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
714
+ * restoring transition reaches one only through an own confirmation's transition.) Atomic with the restoring transition, so
715
+ * it holds even when the same catch-up prunes that node below the rewind horizon (`plan.canonicalTags` includes
716
+ * `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
717
+ * that are not self-update re-enqueues); the caller re-evaluates any
718
+ * sibling that waited behind one once the transaction committed.
719
+ *
720
+ * This is the ONLY cancel — there is no drive-time re-check (pipeline.ts `driveReenqueuedSelfUpdate`), and
721
+ * none is needed, on two premises: (1) the canonical path changes only here — `rt.window` is assigned only by
722
+ * `deliverTransition` and by rebuild/load from the stored window, and every writer that changes the window's tip
723
+ * (ingest's transition, `confirmRecord`) writes it in the same transaction as `recordTransition`, while the other
724
+ * window writers (`remintStaleReenqueue`, `settlePublishedRecord`'s stale path, `restageExcludedProposals`) add fork
725
+ * nodes or re-snapshot nodes with the tip unchanged, and groups.restore/create start from a cleared store
726
+ * (test/client/write-window-sites.test.ts pins the writer list); (2) every `selfUpdateIntentId` ledger writer
727
+ * outside this transaction either names a non-canonical node or deletes the root's only record in the same
728
+ * transaction. A pending-confirm record kept here goes only to `confirmRecord`, which deletes it.
729
+ */
730
+ /**
731
+ * ledger-retention-vs-rewind-horizon: the confirmation tags of every node of the stored rewind window (tip, canonical
732
+ * path and fork nodes) — the nodes a later fork flip can still abandon or restore. A terminal-ledger entry naming one
733
+ * (`node`) is what `planTransition`'s withdrawal detection and {@link cancelRestoredReenqueues} key off, so age-based
734
+ * retention (`pruneTerminalLedger`) must keep it however old it is: the window is commit-bounded, the ledger's age
735
+ * bound is not, and in a quiet group a node can outlive `LEDGER_RETENTION_S`. Read in the prune's own transaction.
736
+ * A pending re-enqueue needs no separate pin: its original can only be restored while the original's node is
737
+ * still in this window. Empty when no window is stored.
738
+ */
739
+ export async function retainedLedgerNodes(tx) {
740
+ const window = await readWindow(tx.artifact('rewindTree'));
741
+ return new Set(window === undefined ? [] : window.nodes.keys());
742
+ }
743
+ export async function cancelRestoredReenqueues(tx, plan, retired) {
744
+ if (plan.canonicalTags.size === 0)
745
+ return [];
746
+ const pendingView = tx.artifact('pendingIntents');
747
+ const reenqueues = (await listPendingIntentRecords(pendingView)).filter((r) => r.reenqueuedFrom !== undefined);
748
+ const records = reenqueues.filter((r) => r.state !== 'pending-confirm');
749
+ const ledger = tx.artifact('terminalLedger');
750
+ const cancelled = [];
751
+ // Epic marmot-rewound-own-commit-no-signal S1 (DD14, AC-REC-3): a marked own commit that came back — decided on the
752
+ // marker (`plan.restoredOwnCommits`, computed with the plan), per root — returns to `own`, and the root's commit re-drive
753
+ // record is deleted with it in whatever state it is in (S10, AC-REC-3/4/7): not started, started with an envelope awaiting its
754
+ // publish retry, or `pending-confirm` (a relay accepted it). The original now carries the change, so the re-drive is retired --
755
+ // never published again, never `intentFailed` -- and a later confirm of it finds no record (confirmRecord), so the one
756
+ // `own-change-reapplied` the plan carries (naming the ORIGINAL's commit) is the only terminal of the change. A withdrawn
757
+ // re-drive of the same root in this plan got no record (recordTransition). `own-change-reapplied` is in the plan.
758
+ const restored = plan.restoredOwnCommits ?? [];
759
+ if (restored.length > 0) {
760
+ const roots = new Set(restored.map((r) => r.rootIntentId));
761
+ // DD9: the restored nodes' markers take the root's highest spend (re-drive publishes of the abandoned branches), so the budget
762
+ // survives those branches' markers being pruned: the next withdrawal of a restored node seeds its record from its own marker.
763
+ const markerView = tx.extension(OWN_COMMIT_EXTENSION);
764
+ const spend = new Map();
765
+ for (const root of roots)
766
+ spend.set(root, await rootMarkerSpend(markerView, root));
767
+ // The record being retired holds spend no marker does yet (`redriveSpendOf`). A record with an envelope that is only
768
+ // awaiting its retry has had every failed publish counted already.
769
+ for (const record of reenqueues) {
770
+ if (!isCommitRedrive(record) || record.reenqueuedFrom === undefined || !roots.has(record.reenqueuedFrom))
771
+ continue;
772
+ spend.set(record.reenqueuedFrom, Math.max(spend.get(record.reenqueuedFrom) ?? 0, redriveSpendOf(record)));
773
+ }
774
+ for (const { rootIntentId, eventIds } of restored) {
775
+ for (const eventId of eventIds) {
776
+ const entry = await readTerminalLedgerEntry(ledger, eventId);
777
+ if (entry?.disposition === WITHDRAWN_DISPOSITION)
778
+ await writeTerminalLedgerEntry(ledger, eventId, { ...entry, disposition: 'own' });
779
+ }
780
+ await raiseRootSpend(markerView, rootIntentId, spend.get(rootIntentId) ?? 0, eventIds);
781
+ }
782
+ for (const record of reenqueues) {
783
+ if (!isCommitRedrive(record) || record.reenqueuedFrom === undefined || !roots.has(record.reenqueuedFrom))
784
+ continue;
785
+ await deletePendingIntentRecord(pendingView, record.intentId);
786
+ cancelled.push(record.intentId);
787
+ // A published (pending-confirm) invite re-drive owns Welcomes only this record holds (they reach the invitations service at confirm); a relay
788
+ // accepted its commit, which peers may extend: handed over after the transition. One still awaiting its publish retry was never accepted: nothing to park.
789
+ if (record.state === 'pending-confirm' && record.welcomes !== undefined && record.welcomes.length > 0)
790
+ retired?.push(record);
791
+ }
792
+ }
793
+ const candidates = records.filter((r) => !isCommitRedrive(r));
794
+ if (candidates.length === 0)
795
+ return cancelled;
796
+ const entries = [];
797
+ for (const eventId of await ledger.keys()) {
798
+ const entry = await readTerminalLedgerEntry(ledger, eventId);
799
+ if (entry?.selfUpdateIntentId !== undefined && entry.node !== undefined && plan.canonicalTags.has(entry.node))
800
+ entries.push({ eventId, entry });
801
+ }
802
+ for (const record of candidates) {
803
+ const selfRestored = entries.filter(({ entry }) => entry.selfUpdateIntentId === record.reenqueuedFrom);
804
+ if (selfRestored.length === 0)
805
+ continue;
806
+ await deletePendingIntentRecord(pendingView, record.intentId);
807
+ for (const { eventId, entry } of selfRestored) {
808
+ if (entry.disposition === WITHDRAWN_DISPOSITION)
809
+ await writeTerminalLedgerEntry(ledger, eventId, { ...entry, disposition: 'own' });
810
+ }
811
+ cancelled.push(record.intentId);
812
+ }
813
+ return cancelled;
814
+ }
815
+ /**
816
+ * Records `plan` in the transition's own transaction: the ledger entries of
817
+ * withdrawn messages turn `withdrawn`, each withdrawn self-update (AC-RACE-1) is re-enqueued atomically
818
+ * (so a crash between the withdrawal and its re-enqueue is impossible — the caller only has to DRIVE the
819
+ * already-durable record afterwards, detached), and — with a history backend — its backend updates are
820
+ * queued in the outbox, withdrawals before appends. `epoch` is the transition's resulting epoch (the new
821
+ * tip's), used as the re-enqueued record's `parentEpoch`. Returns the ids of the records {@link cancelRestoredReenqueues} deleted:
822
+ * self-update re-enqueues AND (S1) commit re-drive records.
823
+ */
824
+ export async function recordTransition(rt, tx, plan, epoch) {
825
+ await markWithdrawn(tx.artifact('terminalLedger'), plan, rt.ctx.clock.now());
826
+ // S11 (AC-COMP-10): the plan's terminals (the DD14 restore's `own-change-reapplied`) become durable in this very transaction.
827
+ await enqueueTerminals(tx.extension(OWN_CHANGE_OUTBOX_EXTENSION), plan.notifications.filter(isTerminalNotification));
828
+ await reenqueueAndRedriveWithdrawn(tx, plan, epoch);
829
+ const retired = [];
830
+ const cancelled = await cancelRestoredReenqueues(tx, plan, retired);
831
+ if (retired.length > 0)
832
+ retiredWelcomes.set(plan, retired);
833
+ await updateSettlementRecheck(tx.extension(SETTLEMENT_RECHECK_EXTENSION), plan);
834
+ // S4 (SC-4 I11, canonical-path rule): admission lineage advances here and only here — each checkpoint the persisted
835
+ // window would leave unprovable moves to the new window root, in the transaction that persists that window.
836
+ if (plan.lineage !== undefined)
837
+ await advanceLineageRecords(tx.extension(ADMISSION_LINEAGE_EXTENSION), { before: plan.lineage.before, diff: plan.lineage.diff, after: plan.window }, plan.lineage.tip);
838
+ if (rt.ctx.history === undefined)
839
+ return cancelled;
840
+ const ops = [
841
+ ...(plan.withdrawn.length === 0 ? [] : [{ kind: 'withdraw', eventIds: plan.withdrawn.map((w) => w.eventId), attempts: 0 }]),
842
+ ...plan.kept.map((m) => ({ kind: 'append', entry: { groupId: rt.groupId, eventId: m.eventId, rumor: m.rumor, orderingKey: m.orderingKey }, attempts: 0 })),
843
+ ];
844
+ if (ops.length === 0)
845
+ return cancelled;
846
+ const view = tx.extension(HISTORY_OUTBOX_EXTENSION);
847
+ const stored = await view.get(SEQ_KEY);
848
+ let seq = typeof stored === 'number' ? stored : 0;
849
+ for (const op of ops) {
850
+ await view.put(OP_PREFIX + String(seq).padStart(12, '0'), encodeOp(op));
851
+ seq += 1;
852
+ }
853
+ await view.put(SEQ_KEY, seq);
854
+ return cancelled;
855
+ }
856
+ /** How long one history backend call may take before it counts as a failed attempt (ms). */
857
+ export const HISTORY_BACKEND_TIMEOUT_MS = 10_000;
858
+ /**
859
+ * One history backend call through the guard, bounded by
860
+ * `historyBackendTimeoutMs`: a call that does not settle in time rejects
861
+ * here (the consumer's promise may still settle later — calls are
862
+ * at-least-once and idempotent by `eventId`, see `HistoryBackend`).
863
+ */
864
+ export function boundedHistoryCall(ctx, guard, groupId, fn) {
865
+ return bounded(ctx, guard.call(groupId, 'historyBackend', fn));
866
+ }
867
+ /** `call`, or a rejection once `historyBackendTimeoutMs` passed without it settling. */
868
+ function bounded(ctx, call) {
869
+ return new Promise((resolve, reject) => {
870
+ let settled = false;
871
+ const timer = ctx.timers.set(() => {
872
+ if (settled)
873
+ return;
874
+ settled = true;
875
+ reject(new Error(`history backend: no answer within ${ctx.historyBackendTimeoutMs} ms`));
876
+ }, ctx.historyBackendTimeoutMs);
877
+ call.then((value) => {
878
+ if (settled)
879
+ return;
880
+ settled = true;
881
+ ctx.timers.clear(timer);
882
+ resolve(value);
883
+ }, (error) => {
884
+ if (settled)
885
+ return;
886
+ settled = true;
887
+ ctx.timers.clear(timer);
888
+ reject(error);
889
+ });
890
+ });
891
+ }
892
+ /**
893
+ * Issues one mutating backend call and remembers it until it actually
894
+ * settles, however long that takes: no later call — the next op, or the
895
+ * teardown purge — is issued before it did, so a call that timed out can
896
+ * never land after (and undo) an update meant to come after it.
897
+ */
898
+ export function issueMutation(rt, fn) {
899
+ const raw = rt.guard.call(rt.groupId, 'historyBackend', fn);
900
+ const settled = raw.then(() => undefined, () => undefined);
901
+ rt.historyDrain.inFlight = settled;
902
+ void settled.then(() => {
903
+ if (rt.historyDrain.inFlight === settled)
904
+ rt.historyDrain.inFlight = undefined;
905
+ });
906
+ return bounded(rt.ctx, raw);
907
+ }
908
+ /**
909
+ * Waits up to the history call timeout for the group's last mutating backend
910
+ * call to settle; rejects when it still has not (the teardown step fails and
911
+ * is retried — a purge never overtakes an append still in flight).
912
+ */
913
+ export async function awaitHistoryCallSettled(rt) {
914
+ const inFlight = rt.historyDrain.inFlight;
915
+ if (inFlight !== undefined)
916
+ await bounded(rt.ctx, inFlight);
917
+ }
918
+ /** One pass over the outbox, oldest op first; stops at the first failing op (order is kept). */
919
+ async function drainOnce(rt) {
920
+ const history = rt.ctx.history;
921
+ if (history === undefined)
922
+ return;
923
+ try {
924
+ const view = rt.groupStore.extension(HISTORY_OUTBOX_EXTENSION);
925
+ const keys = (await rt.guard.call(rt.groupId, 'store', () => view.keys())).filter((k) => k.startsWith(OP_PREFIX)).sort();
926
+ for (const key of keys) {
927
+ if (rt.historyDrain.stopped || rt.disposed)
928
+ return;
929
+ const inFlight = rt.historyDrain.inFlight;
930
+ if (inFlight !== undefined) {
931
+ // A call that timed out has not settled yet: nothing is issued after it; the drain resumes once it has.
932
+ void inFlight.then(() => scheduleHistoryDrain(rt));
933
+ return;
934
+ }
935
+ const op = decodeOp(rt.groupId, await rt.guard.call(rt.groupId, 'store', () => view.get(key)));
936
+ let taken = true;
937
+ if (op !== undefined) {
938
+ try {
939
+ if (op.kind === 'withdraw')
940
+ await issueMutation(rt, () => history.withdraw(rt.groupId, op.eventIds));
941
+ else
942
+ await issueMutation(rt, () => history.append(op.entry));
943
+ }
944
+ catch {
945
+ taken = op.attempts + 1 >= MAX_HISTORY_ATTEMPTS;
946
+ if (!taken) {
947
+ const retry = { ...op, attempts: op.attempts + 1 };
948
+ await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction((tx) => tx.extension(HISTORY_OUTBOX_EXTENSION).put(key, encodeOp(retry))));
949
+ return;
950
+ }
951
+ }
952
+ }
953
+ await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction((tx) => tx.extension(HISTORY_OUTBOX_EXTENSION).delete(key)));
954
+ }
955
+ }
956
+ catch {
957
+ // A store failure: the outbox is durable, the next drain picks it up.
958
+ }
959
+ }
960
+ /**
961
+ * Hands the outbox to the history backend on the group's own history worker
962
+ * — serialized per group, but OUTSIDE the group's operation queue and every
963
+ * consumer frame, so a slow or hanging backend never holds up a send, an
964
+ * ingest or a teardown (the history backend is optional; live delivery never
965
+ * waits on it). In order, each op deleted once the backend took it; a
966
+ * failing (or timed-out, see {@link boundedHistoryCall}) op stops the pass
967
+ * and is retried by the next one — the next transition's delivery, the
968
+ * group's next load, a `history()` read — until {@link MAX_HISTORY_ATTEMPTS}.
969
+ * A drain requested while one runs makes it run once more. Resolves when the
970
+ * worker is idle; never rejects.
971
+ */
972
+ export function scheduleHistoryDrain(rt) {
973
+ const worker = rt.historyDrain;
974
+ if (rt.ctx.history === undefined || worker.stopped)
975
+ return Promise.resolve();
976
+ if (worker.running !== undefined) {
977
+ worker.again = true;
978
+ return worker.running;
979
+ }
980
+ const running = rt.guard.detached(async () => {
981
+ do {
982
+ worker.again = false;
983
+ await drainOnce(rt);
984
+ } while (worker.again && !worker.stopped && !rt.disposed);
985
+ });
986
+ worker.running = running.finally(() => {
987
+ worker.running = undefined;
988
+ });
989
+ return worker.running;
990
+ }
991
+ /**
992
+ * Stops the group's history worker for good (teardown): no further backend
993
+ * call is started; resolves once the call in flight settled or timed out.
994
+ */
995
+ export function stopHistoryDrain(rt) {
996
+ rt.historyDrain.stopped = true;
997
+ return rt.historyDrain.running ?? Promise.resolve();
998
+ }
999
+ /**
1000
+ * Announces a persisted transition: `rt.window` moves to the plan's window,
1001
+ * the notifications go to the listeners, and the history outbox the
1002
+ * transition filled is handed to the group's history worker (not awaited).
1003
+ * Never throws — it runs after the transition committed, so nothing may undo it.
1004
+ */
1005
+ export async function deliverTransition(rt, plan, defer = new Set()) {
1006
+ rt.window = plan.window;
1007
+ // DD8: the invite reconciliation (`welcomeFailed` commit-withdrawn) comes BEFORE the group notifications, so `own-change-withdrawn` follows it.
1008
+ // It is store-only and independent of the dispatch below (it never reads a notification).
1009
+ if (plan.abandonedTags !== undefined) {
1010
+ await reconcileInvites(rt, new Set(plan.abandonedTags), plan.canonicalTags, {
1011
+ restoredRoots: new Set((plan.restoredOwnCommits ?? []).map((r) => r.rootIntentId)),
1012
+ redriveRoots: new Set((plan.withdrawnOwnCommits ?? []).map((w) => w.rootIntentId)),
1013
+ });
1014
+ }
1015
+ for (const record of retiredWelcomes.get(plan) ?? [])
1016
+ await parkWithdrawnWelcomes(rt, record, true);
1017
+ retiredWelcomes.delete(plan);
1018
+ // S11 (AC-COMP-10): a disposed runtime delivers no terminal -- exactly like `announceTerminals` -- and removes none: the plan's outbox
1019
+ // entries (recordTransition) stay for the reload. Every other notification keeps its behaviour (a disposed handle still hears it).
1020
+ const disposed = rt.disposed || rt.ctx.isDisposed();
1021
+ // Order (DD7, AC-PROP-1): a terminal still retained in the outbox is older than anything this plan announces, so it is handed over
1022
+ // FIRST -- a queued subscribe-time announce can run after a transition that withdraws the same change again. The plan's own
1023
+ // terminals (just written by recordTransition) go out with the plan, after the withdrawals they end.
1024
+ // `defer`: outbox keys the caller announces itself after the plan (the confirming transaction's own reapplied).
1025
+ if (!disposed)
1026
+ await announceTerminals(rt, new Set([...plan.notifications.filter(isTerminalNotification).map(terminalKey), ...defer]));
1027
+ dispatch(rt, disposed ? plan.notifications.filter((n) => !isTerminalNotification(n)) : plan.notifications);
1028
+ // The plan's terminals went out with the rest of its notifications (withdrawn first, so a terminal never precedes the
1029
+ // withdrawal it ends); their outbox entries are removed now. Nobody listening: they stay.
1030
+ if (!disposed && rt.notificationListeners.size > 0)
1031
+ await dropPlanTerminals(rt, plan);
1032
+ if (plan.rewound)
1033
+ rt.announceRewind();
1034
+ // The device port's `onRotation`: only an applied `leaf-key-rotated`, never the withdrawn variant (a recorded link is a fact about the device).
1035
+ if (plan.notifications.some((n) => n.type === 'leaf-key-rotated'))
1036
+ rt.announceRotation();
1037
+ // Epic marmot-invitation-outcomes S5 (SC-12): a transition may change a cleanup's disposition (confirmed, withdrawn, restored,
1038
+ // settled): every candidate a withdrawn cleanup names joins the session's reported ones, then each changed report is emitted
1039
+ // (detached, best effort, reads only).
1040
+ for (const w of plan.withdrawnOwnCommits ?? [])
1041
+ for (const c of w.changes)
1042
+ if (c.change.type === 'admission-removed')
1043
+ noteCleanupCandidate(rt, c.change.candidateId);
1044
+ emitCleanupDispositions(rt);
1045
+ void scheduleHistoryDrain(rt);
1046
+ }
1047
+ /** Removes the outbox entries of the terminals `plan` just dispatched. Never throws. */
1048
+ async function dropPlanTerminals(rt, plan) {
1049
+ const keys = new Set(plan.notifications.filter(isTerminalNotification).map(terminalKey));
1050
+ if (keys.size === 0)
1051
+ return;
1052
+ try {
1053
+ const { entries } = await rt.guard.call(rt.groupId, 'store', () => readOutboxLenient(rt.groupStore.extension(OWN_CHANGE_OUTBOX_EXTENSION)));
1054
+ await removeDelivered(rt, entries.filter((e) => keys.has(e.key)));
1055
+ }
1056
+ catch {
1057
+ // Left for the next announcement.
1058
+ }
1059
+ }
1060
+ /**
1061
+ * The started invite re-drives a plan's DD14 restore retired (their Welcomes still live only on the deleted record), by plan: handed over in
1062
+ * {@link deliverTransition}. Accepted residual: this hand-over lives in memory across the gap between the transition's commit and its delivery
1063
+ * (a crash in between loses it; the path is defensive -- no real producer reaches a pending-confirm re-drive, and the confirm itself records
1064
+ * the Welcomes before its transaction, so the invitations service usually holds them already).
1065
+ *
1066
+ * Accepted residual of the same kind (delivered-on-abandoned-branch): `reconcileInvites` runs in {@link deliverTransition}, after the transition's
1067
+ * commit. A crash in that gap, then a re-drive that confirms before the load-time reconcile ran, leaves the abandoned commit's delivered Welcome
1068
+ * unmarked for a moment; the load-time reconcile (no plan, decided from the store) then marks it, and signals it only if no re-drive record is
1069
+ * pending for the root -- so the signal can be missed or come late, never doubled (the mark makes it once).
1070
+ */
1071
+ const retiredWelcomes = new WeakMap();
1072
+ /**
1073
+ * Hands the Welcomes of a commit re-drive record that is about to be (or was just) deleted to the invitations service as an
1074
+ * ALREADY-WITHDRAWN invite record: `recordCommitted` under the record's id, the staged commit's event id and the node it produced,
1075
+ * then `withdrawCommit` (so `welcomeFailed` `commit-withdrawn` fires, exactly as for any abandoned invite commit).
1076
+ *
1077
+ * Why: a started invite re-drive's Welcomes reach the invitations service only when its confirmation runs. The two paths that delete
1078
+ * such a record while RETAINING its commit (the stale re-mint of a stored/confirmed envelope, the DD14 retire at `pending-confirm`) would
1079
+ * otherwise leave a commit that can still win -- peers extend it -- with a member nobody ever sent a Welcome. With the record parked,
1080
+ * a later restore of that node is the ordinary `reconcileInvites` -> `restoreCommit` (`welcomeRestored`), which delivers.
1081
+ *
1082
+ * 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
1083
+ * 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),
1084
+ * and a second discarded commit of the same record would collide with the first.
1085
+ *
1086
+ * Idempotent (`recordCommitted` keeps progress, `withdrawCommit` is idempotent): a second park of the same commit is a no-op. Cross-store (account
1087
+ * store, outside the group transaction that deletes the record) -- the ONE intentional divergence: in the re-mint it runs BEFORE that
1088
+ * transaction, so a crash in between leaves a parked record next to a still-durable record (harmless: the retry parks again, a no-op).
1089
+ * Best-effort like {@link reconcileInvites}: `strict` false throws (the caller still holds the
1090
+ * record and retries); `strict` true (after a committed transition) reports `welcomeReconcileFailed` and moves on -- the Welcomes of that
1091
+ * commit are then recoverable only by the application's `retryWelcome` of a re-invite, never lost silently.
1092
+ */
1093
+ export async function parkWithdrawnWelcomes(rt, record, afterCommit = false) {
1094
+ const welcomes = record.welcomes;
1095
+ const envelope = record.envelope;
1096
+ if (welcomes === undefined || welcomes.length === 0 || typeof envelope?.id !== 'string' || record.pending === undefined)
1097
+ return;
1098
+ try {
1099
+ const commitTag = tagOf(deserializeClientState(record.pending.newState));
1100
+ await rt.guard.call(rt.groupId, 'store', async () => {
1101
+ // A confirm that was blocked after its hand-over already recorded this commit's Welcomes (under the bare intent id): not recorded twice.
1102
+ const known = (await rt.invitations.trackedCommits(rt.groupId)).some((c) => c.commitEventId === envelope.id);
1103
+ if (!known)
1104
+ await rt.invitations.recordCommitted({ inviteId: `${record.intentId}:${envelope.id}`, groupId: rt.groupId, commitEventId: envelope.id, commitTag, welcomes });
1105
+ await rt.invitations.withdrawCommit(rt.groupId, envelope.id);
1106
+ });
1107
+ }
1108
+ catch (error) {
1109
+ if (!afterCommit)
1110
+ throw error;
1111
+ rt.ctx.emit('welcomeReconcileFailed', { groupId: rt.groupId, error });
1112
+ }
1113
+ }
1114
+ /**
1115
+ * Brings the group's undelivered invite Welcomes in line with the canonical path: an invite commit whose node is in
1116
+ * `abandoned` lost its race, so its Welcomes that are not yet published must not go out (the invitee would consume and
1117
+ * rotate its KeyPackage for a branch the group left); one whose node is in `canonical` again (it came back through
1118
+ * equivocation credit or a longer branch) has the deliveries withdrawn earlier restored. Idempotent and best-effort:
1119
+ * a failure is reported as `welcomeReconcileFailed` and leaves the deliveries as they were (a crash before it has the
1120
+ * same effect, and the next load reconciles against the stored window, {@link reconcileInvitesWithWindow}).
1121
+ *
1122
+ * Never withdraws a node the new canonical path shares with the old one: a branch switch (`rebaseToWelcome`) only
1123
+ * lands on a competing branch (`judgeCompetingWelcome` rejects a C descending from an H node at or above H's root), so
1124
+ * a node common to both paths is never in `abandoned`.
1125
+ */
1126
+ export async function reconcileInvites(rt, abandoned, canonical,
1127
+ /** The roots the transition restored / wrote a re-drive record for (none: a load, which decides from the store alone). */
1128
+ roots = { restoredRoots: new Set(), redriveRoots: new Set() }) {
1129
+ try {
1130
+ await rt.guard.call(rt.groupId, 'store', async () => {
1131
+ for (const commit of await rt.invitations.trackedCommits(rt.groupId)) {
1132
+ if (commit.commitTag === undefined)
1133
+ continue;
1134
+ if ((commit.open || commit.delivered) && abandoned.has(commit.commitTag)) {
1135
+ const signalDelivered = commit.delivered && (await signalsStrandedInvitee(rt, commit.commitEventId, roots));
1136
+ await rt.invitations.withdrawCommit(rt.groupId, commit.commitEventId, { signalDelivered });
1137
+ }
1138
+ else if ((commit.withdrawn || commit.deliveredAbandoned) && canonical.has(commit.commitTag))
1139
+ await rt.invitations.restoreCommit(rt.groupId, commit.commitEventId);
1140
+ }
1141
+ });
1142
+ }
1143
+ catch (error) {
1144
+ rt.ctx.emit('welcomeReconcileFailed', { groupId: rt.groupId, error });
1145
+ }
1146
+ }
1147
+ /**
1148
+ * Whether an abandoned invite commit with a DELIVERED Welcome is worth a `welcomeFailed` `delivered-on-abandoned-branch`: only when nothing
1149
+ * automatic re-delivers to its invitee. The commit's marker names its root; (a) the transition restored that root (the original is back, the
1150
+ * abandoned commit was a re-drive's: the invitee holds a branch the group left and the restored Welcome is below its tip, ADR-018), or (b) the
1151
+ * root gets no re-drive (no record in this plan, none pending: an unreadable diff, a marker without changes). The decision is taken once, here: a
1152
+ * re-drive written by this very plan that later loses the change is told to the application as `own-change-lost`, never as this reason. A commit without a marker (an enrolment
1153
+ * approval, whose Add `reopenApprovalsAfterRewind` re-issues; a commit that carried staged Adds) is never signalled. Never throws.
1154
+ */
1155
+ async function signalsStrandedInvitee(rt, commitEventId, roots) {
1156
+ try {
1157
+ const marker = await readOwnCommitMarker(rt.groupStore.extension(OWN_COMMIT_EXTENSION), commitEventId);
1158
+ if (marker === undefined)
1159
+ return false;
1160
+ if (roots.restoredRoots.has(marker.root))
1161
+ return true;
1162
+ if (roots.redriveRoots.has(marker.root))
1163
+ return false;
1164
+ const pending = await listPendingIntentRecords(rt.groupStore.artifact('pendingIntents'));
1165
+ return !pending.some((r) => isCommitRedrive(r) && r.reenqueuedFrom === marker.root);
1166
+ }
1167
+ catch {
1168
+ return false;
1169
+ }
1170
+ }
1171
+ /** {@link reconcileInvites} against a stored window: nodes off its canonical path are abandoned (a load after a crash). */
1172
+ export function reconcileInvitesWithWindow(rt, window) {
1173
+ const canonical = new Set(canonicalPath(window).map((n) => n.tag));
1174
+ const abandoned = new Set([...window.nodes.keys()].filter((tag) => !canonical.has(tag)));
1175
+ return reconcileInvites(rt, abandoned, canonical);
1176
+ }
1177
+ /**
1178
+ * ADR-016 (SC-6): merges engine-reported equivocation evidence into `into`, one record per key — the engine re-reports
1179
+ * the same evidence on every selection pass, and further sibling digests of the same leaf at the same node are the
1180
+ * same evidence (their digests merged in). Throws `MarmotError('invalid-options')`, leaving `into` untouched, when any
1181
+ * entry is not recordable evidence ({@link isRecordableEquivocation}).
1182
+ */
1183
+ export function noteEquivocations(into, reported) {
1184
+ // Every entry is checked before `into` is touched: a drain whose result filter let a non-evidence result through
1185
+ // fails here, loudly, instead of merging (and later persisting) a record no reader returns.
1186
+ const bad = reported.findIndex((e) => !isRecordableEquivocation(e));
1187
+ if (bad !== -1)
1188
+ throw new MarmotError('invalid-options', 'not well-formed leaf-equivocation evidence', { details: { index: bad } });
1189
+ for (const e of reported) {
1190
+ const record = equivocationRecordOf(e);
1191
+ const key = equivocationKey(record);
1192
+ const known = into.get(key);
1193
+ into.set(key, known === undefined ? record : { ...known, commitDigests: [...new Set([...known.commitDigests, ...record.commitDigests])].sort() });
1194
+ }
1195
+ }
1196
+ /**
1197
+ * ADR-016 (SC-6): records evidence an engine drain reported OUTSIDE an ingest batch — the convergence continuation's
1198
+ * drive and the pooled re-ingest after a rollback or a proposal drop, whose results are otherwise discarded — in its
1199
+ * own store transaction (only keys absent before it), and announces exactly the records that transaction wrote, once
1200
+ * it committed. A later selection pass re-reports evidence only while its fork is still eligible, and one drain can
1201
+ * carry the tip past the horizon before its only pass, so evidence first reported here is recorded here.
1202
+ */
1203
+ export async function recordEquivocations(rt, reported) {
1204
+ if (reported.length === 0)
1205
+ return;
1206
+ const records = new Map();
1207
+ noteEquivocations(records, reported);
1208
+ let wrote = [];
1209
+ await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction(async (tx) => {
1210
+ const run = [];
1211
+ for (const record of records.values())
1212
+ if (await writeEquivocation(tx.extension(EQUIVOCATION_EXTENSION), record))
1213
+ run.push(record);
1214
+ wrote = run;
1215
+ }));
1216
+ dispatch(rt, wrote.map(equivocationNotification));
1217
+ }
1218
+ // ---------------------------------------------------------------------------
1219
+ // history()
1220
+ // ---------------------------------------------------------------------------
1221
+ /**
1222
+ * `history()` from inside the group's own history backend call would wait on
1223
+ * the worker that is waiting on that very call: refused `reentrant` at once.
1224
+ */
1225
+ export function assertNotInHistoryBackend(rt) {
1226
+ if (rt.guard.within(rt.groupId, 'historyBackend')) {
1227
+ throw new MarmotError('reentrant', `MarmotGroup.history: called from inside group ${rt.groupId}'s own history backend call`, {
1228
+ details: { scope: rt.groupId, operation: 'history', surface: 'historyBackend' },
1229
+ });
1230
+ }
1231
+ }
1232
+ export async function* historyOf(rt) {
1233
+ // AC-INV-5: a fenced group surfaces `fenced` on every operation, reads included — before anything is read or drained.
1234
+ assertNotFenced(rt, 'history');
1235
+ const history = rt.ctx.history;
1236
+ if (history === undefined)
1237
+ return;
1238
+ // Checked again here: the iterable may have been created outside and be iterated inside such a call.
1239
+ assertNotInHistoryBackend(rt);
1240
+ // The outbox first (a crash may have left updates of committed transitions): history() reads its own writes —
1241
+ // up to an update the backend failed or timed out on, which stays queued for a later drain.
1242
+ await scheduleHistoryDrain(rt);
1243
+ const entries = await boundedHistoryCall(rt.ctx, rt.guard, rt.groupId, () => history.list(rt.groupId));
1244
+ for (const entry of entries)
1245
+ yield entry.rumor;
1246
+ }
1247
+ // ---------------------------------------------------------------------------
1248
+ // Fencing (AC-HIST-4)
1249
+ // ---------------------------------------------------------------------------
1250
+ /** Refuses an operation on a fenced group: `fenced`, carrying the fencing error as `cause`. */
1251
+ export function assertNotFenced(rt, operation) {
1252
+ if (rt.fence !== undefined)
1253
+ throw fencedError(rt.groupId, operation, rt.fence);
1254
+ }
1255
+ /**
1256
+ * The session fence was just recorded on `rt`: every `synced()` wait for the group's first catch-up fails `fenced` now —
1257
+ * a fenced group never opens its send gate. In-memory only and independent of the durable intent cleanup
1258
+ * (`failAwaitingIntents`), so a fence whose store work failed or never runs still settles every waiter.
1259
+ */
1260
+ export function rejectSyncWaitersFenced(rt) {
1261
+ const fence = rt.fence;
1262
+ if (fence === undefined)
1263
+ return;
1264
+ rejectSyncWaiters(rt, () => fencedError(rt.groupId, 'synced', fence));
1265
+ }
1266
+ /**
1267
+ * Every pending `synced()` wait for the group's first catch-up fails now, each with its own error from `errorOf`: the
1268
+ * condition that ends it (a fence, a lost lease) means the send gate never opens in this session.
1269
+ */
1270
+ export function rejectSyncWaiters(rt, errorOf) {
1271
+ const waiters = [...rt.syncWaiters];
1272
+ rt.syncWaiters.clear();
1273
+ for (const waiter of waiters)
1274
+ waiter.reject(errorOf());
1275
+ }
1276
+ /** The cause of a client-wide lease end signalled by the account store (`AccountStore.onLeaseEnded`). */
1277
+ export function accountLeaseEndedError() {
1278
+ return new MarmotError('no-lease', 'the account store reported that its lease ended');
1279
+ }
1280
+ /** The `no-lease` refusal of a `synced()` wait: the stores lost their lease before the group's first catch-up. */
1281
+ export function syncedLeaseLostError(rt, cause) {
1282
+ return new MarmotError('no-lease', `synced: the stores lost their lease before group ${rt.groupId} completed its first sync`, { cause, details: { groupId: rt.groupId } });
1283
+ }
1284
+ /**
1285
+ * Fences the group for good: the marker is persisted first (a reload stays
1286
+ * fenced), then every further operation is refused. Idempotent.
1287
+ */
1288
+ export async function fenceGroup(rt, cause) {
1289
+ if (rt.fence !== undefined)
1290
+ return;
1291
+ // Epic marmot-invitation-outcomes S1: the marker records the fence's coarse cause (additive on v:1).
1292
+ const record = { at: rt.ctx.clock.now(), epoch: String(rt.exposedState.groupContext.epoch), message: cause.message, cause: fenceCauseOf(cause) };
1293
+ // The held opaque record goes with the marker, in the same transaction: a fenced group keeps none (a reload must not
1294
+ // resurrect them), and the marker never outlives a record that still names candidates that decide nothing any more.
1295
+ const clearOpaqueRecord = !isEmptyOpaque(rt.opaque);
1296
+ try {
1297
+ await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction(async (tx) => {
1298
+ await writeFence(tx.extension(FENCE_EXTENSION), record);
1299
+ if (clearOpaqueRecord)
1300
+ await clearOpaque(tx.extension(OPAQUE_EXTENSION));
1301
+ }));
1302
+ }
1303
+ catch (error) {
1304
+ // The verdict outlives the failed write. The engine may already have released the held candidate it came from
1305
+ // (it does once the verdict is yielded), so this session is fenced in memory and the next operation reloads the
1306
+ // durable state first: no write of a candidate-free record can follow a lost fence write, and the durable record
1307
+ // still holds the candidate, which a reload re-decides. Assigning the fence still publishes it to the group's
1308
+ // availability observers and records it as this session's (the reload never reads clear: SC-10 A-7).
1309
+ rt.fence = cause;
1310
+ rt.needsReload = true;
1311
+ rejectSyncWaitersFenced(rt);
1312
+ throw error;
1313
+ }
1314
+ if (clearOpaqueRecord)
1315
+ rt.opaque = undefined;
1316
+ rt.fence = cause;
1317
+ rejectSyncWaitersFenced(rt);
1318
+ }
1319
+ // ---------------------------------------------------------------------------
1320
+ // Media (AC-MEDIA-1/2)
1321
+ // ---------------------------------------------------------------------------
1322
+ export async function encryptMediaOp(rt, bytes, options) {
1323
+ if (!(bytes instanceof Uint8Array))
1324
+ throw new MarmotError('invalid-options', 'MarmotGroup.encryptMedia: bytes must be a Uint8Array');
1325
+ const media = await encryptMedia(rt.exposedState, rt.engine.ciphersuite, bytes, options);
1326
+ const cache = rt.ctx.mediaCache;
1327
+ if (cache !== undefined)
1328
+ await rt.guard.call(rt.groupId, 'mediaCache', () => cache.put(media.locator, media.ciphertext));
1329
+ return media;
1330
+ }
1331
+ export async function decryptMediaOp(rt, media) {
1332
+ if (typeof media !== 'object' || media === null || !Array.isArray(media.imeta))
1333
+ throw new MarmotError('invalid-options', 'MarmotGroup.decryptMedia: media must carry an imeta tag set');
1334
+ const attachment = attachmentOf(media.imeta);
1335
+ if (attachment === undefined)
1336
+ throw new MarmotError('invalid-options', 'MarmotGroup.decryptMedia: no valid encrypted-media-v1 imeta tag', { details: { reason: 'invalid-imeta' } });
1337
+ // The cache is keyed by the blob's content address as the authenticated imeta tag names it — never by a
1338
+ // caller-supplied locator, which could name another blob.
1339
+ const locator = attachment.ciphertextSha256;
1340
+ const cache = rt.ctx.mediaCache;
1341
+ let ciphertext = media.ciphertext instanceof Uint8Array && media.ciphertext.length > 0 ? media.ciphertext : undefined;
1342
+ const fromCache = ciphertext === undefined;
1343
+ if (ciphertext === undefined && cache !== undefined)
1344
+ ciphertext = await rt.guard.call(rt.groupId, 'mediaCache', () => cache.get(locator));
1345
+ if (ciphertext === undefined)
1346
+ throw new MarmotError('invalid-options', `MarmotGroup.decryptMedia: no ciphertext given and none cached under ${locator}`, { details: { reason: 'not-found', locator } });
1347
+ if ((await sha256Hex(ciphertext)) !== locator) {
1348
+ throw new MarmotError('invalid-options', 'MarmotGroup.decryptMedia: the ciphertext is not the blob the imeta tag names', { details: { reason: 'ciphertext-mismatch', locator } });
1349
+ }
1350
+ // Every epoch the group retains, newest first: the media key is the one of the epoch the carrying message went out in.
1351
+ const states = [rt.exposedState, ...rt.engine.retainedStates().filter((s) => s.groupContext.epoch !== rt.exposedState.groupContext.epoch)];
1352
+ let plaintext;
1353
+ try {
1354
+ plaintext = await decryptMedia(states, rt.engine.ciphersuite, ciphertext, attachment);
1355
+ }
1356
+ catch (error) {
1357
+ throw new MarmotError('invalid-options', 'MarmotGroup.decryptMedia: the media does not decrypt under any epoch this group retains', { cause: error, details: { reason: 'undecryptable', locator } });
1358
+ }
1359
+ const fetched = ciphertext;
1360
+ if (!fromCache && cache !== undefined)
1361
+ await rt.guard.call(rt.groupId, 'mediaCache', () => cache.put(locator, fetched));
1362
+ return plaintext;
1363
+ }
1364
+ /** Test-only handles on module internals (mirrors pipeline.ts `__internal`); not part of any public surface. */
1365
+ export const __internal = Object.freeze({ reenqueueAndRedriveWithdrawn });