@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,52 @@
1
+ /**
2
+ * The convergence policy every `marmot` engine runs: MIP-03 policy v1 with
3
+ * app-payload witnesses switched off, so the branch choice is structural
4
+ * only (commit depth, then tip committer, then tip digest) and the same on
5
+ * every member. A deliberate, documented deviation — rationale and interop
6
+ * impact in specs/epic-marmot-client/architecture.md, "Structural branch
7
+ * selection".
8
+ *
9
+ * Witnesses cannot make that choice consistently here: a witness is an
10
+ * application message that decrypts on a candidate branch, and a sender can
11
+ * never decrypt its own messages. In a same-epoch race each committer counts
12
+ * the other branch's messages but not its own branch's, so each prefers the
13
+ * other's commit. With `witnessQuorumSendersPerEpoch: 0` no branch scores a
14
+ * witness; `maxWitnessOverrideDepth: 0` keeps the policy valid (it must not
15
+ * exceed `maxRewindCommits`). The rollback horizon is unchanged.
16
+ *
17
+ * It lives in `history/` (re-exported by `client/client-config.ts`) so the
18
+ * persisted rewind window's horizon ({@link REWIND_HORIZON}) and the engines'
19
+ * selection horizon read ONE constant: a horizon change that moved only one of
20
+ * them would make selection narrower than retention (silently) or retention
21
+ * narrower than selection (unsafe). Changing the horizon itself (ADR-016
22
+ * AC-ARCH-3 recommends 3) is a build-wide protocol parameter decided in its own
23
+ * ADR — peers with different horizons diverge on retention. That ADR must also
24
+ * re-decide removal finality (ADR-017 R-6, AR-R7, AR-R8; its Evolution Trigger
25
+ * "The horizon changes"): the rule reaches h - 1 commits past the removal's
26
+ * parent and the replay loop costs h + 1 commits per round, so a shorter
27
+ * horizon shrinks both.
28
+ */
29
+ import { DEFAULT_CONVERGENCE_POLICY } from '@941design/marmot-engine/core';
30
+ export const MARMOT_CONVERGENCE_POLICY = Object.freeze({
31
+ ...DEFAULT_CONVERGENCE_POLICY,
32
+ witnessQuorumSendersPerEpoch: 0,
33
+ maxWitnessOverrideDepth: 0,
34
+ });
35
+ /** The rollback horizon `marmot`'s engines select with and its persisted rewind window retains. */
36
+ export const REWIND_HORIZON = MARMOT_CONVERGENCE_POLICY.maxRewindCommits;
37
+ /**
38
+ * The hidden-credit policy of the branch-aware own-leaf fence (ADR-016 D6; epic `marmot-branch-aware-own-leaf-fence`,
39
+ * spec Design Decision 7, OQ-1): the one value `group-runtime.ts` hands every engine it builds. It decides how much
40
+ * credit the real device assumes for the branch of its own cloned leaf that it cannot open.
41
+ *
42
+ * - `conservative` (shipped until 2026-11-09, when the owner's OQ-1 answer took effect): the hidden subtree may carry up to `U` credit, so the
43
+ * device never stays on a branch the group may have abandoned. An attacker whose burst outgrows canonical's
44
+ * other-leaf credit still fences the real device, visibly, with the `leaf-equivocation` recorded (ADR-016 AR-6′).
45
+ * - `anchored-zero` (the default since 2026-11-09 — owner decision 17, OQ-1 (ii); the spec's recommendation): an opaque head by the device's own leaf, anchored at its parent,
46
+ * earns no hidden credit there, so the device stays on canonical whenever canonical carries other-leaf credit, at
47
+ * the price of staying behind if other members built on the clone's branch (told through its own record).
48
+ *
49
+ * Local to the device (no wire effect, no stored format): the default is this one constant. It is
50
+ * not a public option; tests choose the other value through the internal `engineOptions` hook of the client.
51
+ */
52
+ export const MARMOT_HIDDEN_CREDIT_POLICY = 'anchored-zero';
@@ -0,0 +1,215 @@
1
+ /**
2
+ * The persisted rewind window (S10; the `rewindTree` group artifact of
3
+ * ADR-007 §1): the part of the engine's full-fork history tree fork recovery
4
+ * needs — every state on the canonical path within the rollback horizon
5
+ * (`maxRewindCommits` commits below the tip), the commit that produced each,
6
+ * with the confirmation-time stamp of an own commit, and every fork node
7
+ * hanging off that path.
8
+ *
9
+ * The engine keeps this only in memory, and `marmot` rebuilds engines from
10
+ * `ClientState` alone on every reload and rollback. A rebuilt engine had no
11
+ * retained root at the fork epoch, so a sibling commit arriving after it was
12
+ * skipped as `beyond-anchor` and the group forked for good; and an own commit
13
+ * confirmed by a rebuild (a resumed or retried confirmation) carried no stamp,
14
+ * so it could never be a candidate again (a committer cannot replay its own
15
+ * commit). The window is written in the same transaction as every
16
+ * `clientState` that moves the tip and handed back to every engine built over
17
+ * that state ({@link restoreHistory}), so fork recovery works the same across
18
+ * a reload as it does in one process.
19
+ *
20
+ * Layout: `tip` → the tip node (no snapshot: the stored `clientState` is it);
21
+ * `node:<tag>` → every other node, with its serialized state. A node's tag
22
+ * does not pin its content: the engine re-snapshots a retained node when a
23
+ * proposal is staged onto it (`GroupHistoryTree.updateSnapshot`, same tag),
24
+ * so a write rewrites every node whose stored encoding differs.
25
+ */
26
+ import { type BranchScore } from '@941design/marmot-engine/core';
27
+ import { GroupHistoryTree, RetainedHistoryStore, type OwnCommitConvergenceStamp } from '@941design/marmot-engine/engine';
28
+ import { type ClientState, type MlsMessage } from '@941design/marmot-engine/mls';
29
+ import type { KeyValueView } from '../storage/index.js';
30
+ import { hexOf } from './hex.js';
31
+ import { REWIND_HORIZON } from './policy.js';
32
+ export { hexOf, REWIND_HORIZON };
33
+ /**
34
+ * What a device recorded when it joined a group by Welcome (epic marmot-welcome-race-joiner): the lowercase hex
35
+ * `commitDigest` of the commit that produced the joined state (the Welcome's `commit` tag) and the hex account
36
+ * pubkey of the member that signed the Welcome's GroupInfo (the commit's committer). It is the joined node's only
37
+ * record of its own commit: the node has no parent link, and `WindowNode.sender` is a leaf index of some parent
38
+ * state, not an account.
39
+ */
40
+ export interface JoinEvidence {
41
+ readonly digest: string;
42
+ readonly committer: string;
43
+ }
44
+ export interface WindowNode {
45
+ /** Hex MLS confirmation tag: the node identity. */
46
+ readonly tag: string;
47
+ readonly epoch: number;
48
+ /** The node it was committed from; absent for the window's root. */
49
+ readonly parentTag?: string;
50
+ /** Serialized state; absent for the tip (the stored `clientState` is it). */
51
+ readonly snapshot?: Uint8Array;
52
+ /** The commit from `parentTag`: an own-commit record when stamped, else the MLS wire bytes. */
53
+ readonly commit?: Uint8Array;
54
+ /** Hex SHA-256 of the commit's MLS wire bytes (its `commitDigest`). */
55
+ readonly digest?: string;
56
+ /**
57
+ * The commit's authenticated member sender at `parentTag` — the engine's history-tree edge sender, whatever the
58
+ * commit's wire framing (epic-marmot-rewind-takeover-stale-leaf-snapshot AC-FIX-9). Absent for a non-member sender
59
+ * and on a node written before it was stored (restored from the framing then: ADR-016 AR-7).
60
+ */
61
+ readonly sender?: number;
62
+ /**
63
+ * The join evidence of a window root a Welcome created (`tipOnlyWindow(state, evidence)`); absent on every other
64
+ * node, on a window written before it existed, and on one restored from an imported snapshot (which never supplies
65
+ * it). It stays on its node through every window operation and leaves the window only with that node.
66
+ */
67
+ readonly joinEvidence?: JoinEvidence;
68
+ }
69
+ export interface RetainedWindow {
70
+ readonly tipTag: string;
71
+ readonly nodes: ReadonlyMap<string, WindowNode>;
72
+ }
73
+ export declare function tagOf(state: ClientState): string;
74
+ /** The window of a state with no retained history: the tip alone, carrying `evidence` when the device joined into it. */
75
+ export declare function tipOnlyWindow(state: ClientState, evidence?: JoinEvidence): RetainedWindow;
76
+ /** The commit a node carries: its MLS message and, for an own commit, its stamp. */
77
+ export declare function commitOf(node: WindowNode): {
78
+ readonly message: MlsMessage;
79
+ readonly stamp?: OwnCommitConvergenceStamp;
80
+ } | undefined;
81
+ /**
82
+ * Whether `node`'s link carries what restoring it needs ({@link restoreHistory}, and a rewind's notifications):
83
+ * a commit record that decodes to a framed MLS Commit — anything else (an application message, a proposal, a
84
+ * Welcome) would be recorded as a fabricated commit edge — and the digest of that message's wire bytes. Never throws.
85
+ */
86
+ export declare function linkRestorable(node: WindowNode): boolean;
87
+ /**
88
+ * The window of an engine's history tree around `tip` (the engine's current
89
+ * state): every node within the horizon, with the snapshots and commit
90
+ * records the tree holds for them. The engine's tree knows nothing of a join, so
91
+ * the join evidence of the window this capture replaces (`prior`) is carried over
92
+ * by node tag: a captured node gets the evidence `prior` holds for its tag, and
93
+ * evidence of a node the capture no longer holds leaves with it.
94
+ */
95
+ export declare function captureWindow(tree: GroupHistoryTree, tip: ClientState, horizon: number | undefined, prior: RetainedWindow | undefined): Promise<RetainedWindow>;
96
+ /**
97
+ * `window` with an own commit applied on top of its tip: the old tip becomes
98
+ * a node with `parentState`'s snapshot (the state the commit was built from,
99
+ * its staged proposals included), and the new state is the tip.
100
+ */
101
+ export declare function extendWindow(window: RetainedWindow, link: {
102
+ readonly parentState: ClientState;
103
+ readonly commit: Uint8Array;
104
+ readonly newState: ClientState;
105
+ readonly stamp?: OwnCommitConvergenceStamp;
106
+ }, horizon?: number): RetainedWindow;
107
+ /**
108
+ * `window` with an own commit that is NOT on the canonical path added as a fork node: the commit was built from
109
+ * `parentState` (a node the window holds, with its snapshot) and a foreign commit at the same epoch won, so the tip
110
+ * stays where it is. The node carries `newState`'s snapshot, the own-commit record and the device's own leaf as
111
+ * sender — exactly what {@link extendWindow} stores for a confirmed own commit — so {@link restoreHistory} hands the
112
+ * engine's history tree the edge fork recovery needs to decrypt a peer's commit built on top of it.
113
+ *
114
+ * `undefined` when it cannot be retained: the parent is not in the window (or has no snapshot — it is the tip), or
115
+ * the node falls below the horizon. A node already in the window leaves it unchanged.
116
+ */
117
+ export declare function withForkNode(window: RetainedWindow, link: {
118
+ readonly parentState: ClientState;
119
+ readonly commit: Uint8Array;
120
+ readonly newState: ClientState;
121
+ readonly stamp?: OwnCommitConvergenceStamp;
122
+ }, horizon?: number): RetainedWindow | undefined;
123
+ /**
124
+ * `window` rewound onto its tip's parent: the tip node (and anything hanging off it) removed, the parent the new tip.
125
+ * Every other node stays — in particular each fork node whose ancestry reaches a kept canonical node, which is what lets
126
+ * a rebuilt engine weigh a competitor of the removed tip structurally, with no relay re-fetch. As everywhere, the tip
127
+ * carries no snapshot (the stored `clientState` is it).
128
+ *
129
+ * `undefined` when the window cannot be rewound: the tip has no link to a parent, the parent is not in the window, or
130
+ * it has no serialized state (the state the rewound `clientState` is read from).
131
+ */
132
+ export declare function rewoundToParent(window: RetainedWindow): {
133
+ readonly window: RetainedWindow;
134
+ readonly removed: WindowNode;
135
+ readonly parent: WindowNode & {
136
+ readonly snapshot: Uint8Array;
137
+ };
138
+ } | undefined;
139
+ /**
140
+ * `window` without the nodes not in `keep` (and anything hanging off them):
141
+ * what an engine's history held before a drain whose result was discarded.
142
+ * The tip is always kept.
143
+ */
144
+ export declare function restrictWindow(window: RetainedWindow, keep: ReadonlySet<string>): RetainedWindow;
145
+ /**
146
+ * The canonical path of `window`, root first. Total over any window: the walk from the tip stops at a node with
147
+ * no parent link, at a link leaving the window, and at a link back to a node already on the path (a cycle no
148
+ * window marmot writes has, but one a snapshot from elsewhere could carry — `openGroupSnapshot` refuses it); the
149
+ * path then starts at the node whose link was cut, with that link still set.
150
+ */
151
+ export declare function canonicalPath(window: RetainedWindow): WindowNode[];
152
+ /** A stored sender leaf index: a non-negative safe integer, else none. */
153
+ export declare function senderOfStored(raw: unknown): number | undefined;
154
+ /**
155
+ * The authenticated sender of a window node's commit `message`: the stored `sender`, else — a node written before
156
+ * senders were stored (ADR-016 AR-7) — the framing's, via the engine's one resolver. The single place this fallback is
157
+ * written for marmot (restoreHistory and the tests that re-derive a tip committer use it).
158
+ */
159
+ export declare function senderOfNode(node: Pick<WindowNode, 'sender'>, message: MlsMessage): number | undefined;
160
+ /** Whether two nodes carry the same content (tag, epoch, link, digest, sender, join evidence, snapshot, commit). */
161
+ export declare function sameNode(a: WindowNode, b: WindowNode): boolean;
162
+ /** Whether two windows describe the same tip and the same nodes, content included. */
163
+ export declare function sameWindow(a: RetainedWindow, b: RetainedWindow): boolean;
164
+ /** Writes `window` over whatever window is stored (inside the caller's transaction): a node is rewritten when its content differs. */
165
+ export declare function writeWindow(view: KeyValueView, window: RetainedWindow): Promise<void>;
166
+ /** The stored window, or `undefined` when none (or an unreadable one) is stored. */
167
+ export declare function readWindow(view: KeyValueView): Promise<RetainedWindow | undefined>;
168
+ /**
169
+ * The window an engine built over `state` starts from, and the "before" of
170
+ * its next transition: the stored window whenever it describes `state` (its
171
+ * tip). That includes a multi-node window `restoreHistory` could not hand to
172
+ * the engine (a root without a snapshot, a broken link) — the next
173
+ * transition still diffs against what is persisted, so a withdrawal is never
174
+ * missed for a node the engine dropped. Otherwise the tip alone — with the join
175
+ * evidence of the stored node of that state, if the stored window holds one.
176
+ */
177
+ export declare function windowFor(stored: RetainedWindow | undefined, state: ClientState): RetainedWindow;
178
+ export interface RestoredHistory {
179
+ readonly retained: RetainedHistoryStore;
180
+ readonly historyTree: GroupHistoryTree;
181
+ }
182
+ /**
183
+ * The engine options that hand `window`'s history to an engine built over
184
+ * `state`, or `undefined` when the window does not describe `state` (another
185
+ * tip) or holds nothing beyond it. `state` itself is the tip, in both the tree
186
+ * and the retained store, so the engine and its retained tip are one object.
187
+ */
188
+ export declare function restoreHistory(window: RetainedWindow | undefined, state: ClientState): RestoredHistory | undefined;
189
+ /** The MLS wire bytes of a commit message. */
190
+ export declare function wireOf(message: MlsMessage): Uint8Array;
191
+ /**
192
+ * The held branch's score, or what the window could not supply for it. An incomplete result carries no score at all,
193
+ * so it cannot be compared: there is no placeholder to rank (empty bytes sort lowest and would win a comparison).
194
+ */
195
+ export type HeldBranchScore = {
196
+ readonly complete: true;
197
+ readonly score: BranchScore;
198
+ } | {
199
+ readonly complete: false;
200
+ readonly missing: readonly ('digest' | 'committer')[];
201
+ };
202
+ /**
203
+ * The held side of the comparison a Welcome for an already-held group is decided by (`compareBranchScores`, epic
204
+ * marmot-welcome-race-joiner): the branch whose tip is `tip`, scored the way the members score it with witnesses off:
205
+ * `validCommitDepth` and `effectiveCommitDepth` the tip epoch, no witness quorum, `appWitnessScore` 0.
206
+ *
207
+ * `tipDigest` is the digest of the tip's own link when the tip has one (it was produced by a commit this window
208
+ * holds), else the digest of the join evidence recorded when the device joined into the tip; `tipCommitter` is the
209
+ * credential pubkey of the link's sender in the parent snapshot (`tipCommitterOf`), else the join evidence's
210
+ * committer. A tip with a link never mixes in the evidence (it describes another commit).
211
+ *
212
+ * A digest or committer the window cannot supply makes the result `{ complete: false, missing }` with no score, and a
213
+ * window that does not describe `tip` is incomplete on both.
214
+ */
215
+ export declare function heldBranchScore(window: RetainedWindow, tip: ClientState): HeldBranchScore;