@941design/marmot 0.0.0-stage → 0.2.0-alpha.0

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