@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,379 @@
1
+ /**
2
+ * What the device registry and enrolment (S8) need from the rest of the
3
+ * client, as ports `client/create-client.ts` wires — the `account` module
4
+ * never imports `client` (architecture.md: `client` imports `account`, not
5
+ * the reverse). Every consumer surface behind these ports (signer, stores,
6
+ * transport, verifier) is already routed through the client's re-entrancy
7
+ * guard on the account scope by the wiring.
8
+ *
9
+ * The group operations go through the ordinary group handles: an Add is
10
+ * `group.invite([keyPackage])` (S5's durable invite with its Welcome), a
11
+ * Remove is the pipeline's durable forget commit — each serialised on its
12
+ * group's own queue. Nothing here ever runs on, or waits for, the inbox's
13
+ * queue: inbox handlers may call `group.send`, and a group operation waiting
14
+ * on the inbox would deadlock against them (S7 review).
15
+ */
16
+ import type { NostrEvent } from '@941design/nostr-events/event';
17
+ import type { Signer } from '@941design/nostr-events/signer';
18
+ import type { TransportContract } from '@941design/nostr-events/transport/contract';
19
+ import type { CiphersuiteImpl } from '@941design/marmot-engine/mls';
20
+ import type { DeviceKeyRotationGroupOutcome, KeyPackageRetirementOutcome } from '../key-packages/index.js';
21
+ import type { AccountStoreTx } from '../storage/index.js';
22
+ /**
23
+ * One signature-key succession on a held group's canonical path (epic marmot-device-key-rotation, Design Decision 7):
24
+ * the leaf of `account` at `leafIndex` replaced `fromLeafKey` by `toLeafKey`. Shaped like `history/notifications.ts`
25
+ * `WindowSuccession`, so the client's port can hand over `successionsInWindow(window, tipState)` as is. The device
26
+ * service uses only the local account's.
27
+ */
28
+ export interface GroupSuccession {
29
+ readonly account: string;
30
+ readonly leafIndex: number;
31
+ readonly fromLeafKey: string;
32
+ readonly toLeafKey: string;
33
+ /** Hex digest of the commit that made it. */
34
+ readonly commitDigest?: string;
35
+ }
36
+ /** One held group as the device operations see it. */
37
+ export interface DeviceGroupView {
38
+ readonly groupId: string;
39
+ /** False once the local leaf was removed from the group. */
40
+ readonly member: boolean;
41
+ /** Every leaf of the local account: leaf index and signature key (hex). */
42
+ readonly accountLeaves: readonly {
43
+ readonly leafIndex: number;
44
+ readonly leafKey: string;
45
+ }[];
46
+ /**
47
+ * The LOCAL leaf (the one this client's private path belongs to): its index and signature key (hex), read with the
48
+ * tree. Absent when the local leaf was removed or the port predates the rotation epic. A rotation's per-group
49
+ * read-back compares its key with the target (`rekeyed` when equal) instead of searching `accountLeaves`, which also
50
+ * holds the account's other devices.
51
+ */
52
+ readonly ownLeaf?: {
53
+ readonly leafIndex: number;
54
+ readonly leafKey: string;
55
+ } | undefined;
56
+ /** An own commit of this group is recorded and not yet confirmed or terminal (it is retried by the pipeline). */
57
+ readonly ownCommitPending: boolean;
58
+ /**
59
+ * The engine's convergence window is open (a commit arrived within its
60
+ * quiescence window): a competing commit may still replace the state read
61
+ * here, so no outcome is concluded from it yet.
62
+ */
63
+ readonly syncing: boolean;
64
+ /**
65
+ * S20 follow-up: the group's settlement-recheck marker as of THIS snapshot (read on the group's queue together
66
+ * with the tree), absent when none is set; `withdrawnLeaves` absent for a marker written before S20 round 1.
67
+ */
68
+ readonly recheck?: {
69
+ readonly token: number;
70
+ readonly withdrawnLeaves?: readonly string[];
71
+ } | undefined;
72
+ /**
73
+ * The signature-key successions on this group's canonical path (the retained window), oldest first, read on the
74
+ * group's queue together with the tree. Optional: a port without it behaves as before rotation existed. Every
75
+ * lineage question (a forget's chain, an enrolment re-check, `devices.list()`) unites these with the registry's
76
+ * recorded links, so none depends on whether a notification or the catch-up feed already wrote the link.
77
+ */
78
+ readonly successions?: readonly GroupSuccession[] | undefined;
79
+ }
80
+ /** The account artifact holding device-registry entries (`<leafKey>`, with a tombstone once forgotten) and forget intents (`forget:<leafKey>`). */
81
+ export declare const DEVICE_REGISTRY_ARTIFACT = "deviceRegistry";
82
+ /**
83
+ * AC-RECHK-2/3: a registry entry's tombstone and its `forget:<leafKey>` record are judged
84
+ * against an approval's `approvedAt` SEPARATELY — never merged into one "whichever is found first" time
85
+ * (round 2's bug: a stale tombstone's time was returned ahead of a genuinely newer, still-live forget record,
86
+ * so an old, already-superseded departure could mask a brand new one and let a just-forgotten device be
87
+ * re-added). `departedAfterApproval` (enrolment.ts) and `supersedeDeparture` (device-registry.ts) both call these
88
+ * two helpers and reason about the two results independently; neither module re-derives the other's logic.
89
+ */
90
+ /** A registry entry's tombstone, read loosely (an untrusted/un-deep-validated raw store value). */
91
+ export interface LooseTombstone {
92
+ readonly at?: unknown;
93
+ readonly forgetStartedAt?: unknown;
94
+ }
95
+ /** A `forget:<leafKey>` record, read loosely (an untrusted/un-deep-validated raw store value). */
96
+ export interface LooseForgetRecord {
97
+ readonly startedAt?: unknown;
98
+ }
99
+ /**
100
+ * The tombstone's OWN departure time: `forgetStartedAt` (the forget that settled it, stamped at settle time) —
101
+ * preferred since it is the departure's true start, not when the tombstone happened to be written — else `at`
102
+ * (a pre-remediation tombstone with no `forgetStartedAt`), else `Infinity` for a present but non-numeric value
103
+ * (never silently loosened to "no departure"). `undefined` only when `tombstone` itself is `undefined` — there
104
+ * is no tombstone at all, as distinct from one whose time could not be read.
105
+ */
106
+ export declare function tombstoneDepartureTime(tombstone: LooseTombstone | undefined): number | undefined;
107
+ /**
108
+ * The forget record's OWN departure time: `startedAt`, else `Infinity` for a present but non-numeric value.
109
+ * `undefined` only when `forget` itself is `undefined` — no forget record at all.
110
+ */
111
+ export declare function forgetDepartureTime(forget: LooseForgetRecord | undefined): number | undefined;
112
+ export interface DeviceGroupPort {
113
+ /** Every group this client holds (the account group index). */
114
+ heldGroups(): Promise<readonly string[]>;
115
+ /** The group's current (exposed) state, or `undefined` when it is not held. */
116
+ snapshot(groupId: string): Promise<DeviceGroupView | undefined>;
117
+ /**
118
+ * AC-RECHK-1: the group's current tip epoch, as
119
+ * `Number(groupContext.epoch)` — matching `history/retained-window.ts`'s own `WindowNode.epoch`
120
+ * representation, since `approveEnrolment` compares this against it (`ApprovalGroupRecord.approvalEpoch`,
121
+ * recorded once per group at approval start so a reopened re-drive can refuse only a canonical departure AT
122
+ * OR AFTER it, never one strictly older — e.g. a `devices.forget` Remove that settled before the device
123
+ * re-enrolled). A PLAIN read of the exposed state, same as the public `MarmotGroup.epoch` getter — never a
124
+ * queued group op, so it never touches `pendingIntents` or interacts with a group's `ownCommitPending` /
125
+ * convergence timing the way `snapshot()` does. `undefined` when the group is not held.
126
+ */
127
+ groupEpoch(groupId: string): Promise<number | undefined>;
128
+ /**
129
+ * The group's tip as a plain read of the exposed state, never a queued group op: `<epoch>:<hex confirmation tag>`, `undefined`
130
+ * when the group is not held. Any commit, Welcome adoption, competing-Welcome switch or restore changes it - also one that lands
131
+ * at the same epoch, which the epoch alone would not show. Optional: the device service falls back to the epoch.
132
+ */
133
+ groupTip?(groupId: string): Promise<string | undefined>;
134
+ /**
135
+ * `group.invite([keyPackageEvent])`: one commit adding the device, then its Welcome (S5). Rejects like `invite`.
136
+ *
137
+ * `reopenedLeafKey` (S4 AC-RECHK-1): set when this Add re-drives a group whose approval record was reopened
138
+ * (`enrolment.ts` `reopened: true`). Evaluated as plain code inside the SAME invite group op this call issues —
139
+ * after its proposal policy settles and before the commit is recorded, never as a second awaited device op from
140
+ * a group consumer surface (that would trip S3's AC-RE-2 reentrant rejection): refuses, without committing, when
141
+ * the group's retained rewind window holds `reopenedLeafKey` on a canonical-path state at or after
142
+ * `approvalEpoch` while the tip does not.
143
+ *
144
+ * `reopenedLeafKey` may be a key SET (epic marmot-device-key-rotation AC-RM-3): the approved device's chain, passed when
145
+ * the device has more than one key; the refusal then applies to a leaf of the local account carrying any of them. A
146
+ * single key (a device that never rotated) is passed as the plain string, unchanged.
147
+ *
148
+ * `approvalEpoch` (AC-RECHK-1): the group's tip epoch as of when the approval
149
+ * was taken (`ApprovalGroupRecord.approvalEpoch`), paired with `reopenedLeafKey`. Bounds the refusal to a
150
+ * departure the group's OWN canonical history recorded no earlier than the approval — a `devices.forget`
151
+ * Remove that settled BEFORE the device re-enrolled must never cause refusal (AC-RECHK-2), only one that lands
152
+ * at or after this epoch (e.g. an ordinary Remove racing the reopen decision itself). `undefined` (a pre-
153
+ * remediation approval record with no recorded epoch) falls back to the whole window, unbounded — the original,
154
+ * strictly conservative AC-RECHK-1 behaviour.
155
+ *
156
+ * `origin` (epic marmot-rewound-own-commit-no-signal S9, DD10): `'approval'` is passed by the enrolment approval and
157
+ * stored on the Add's intent, which keeps the confirmed Add unmarked (`reopenApprovalsAfterRewind` owns it).
158
+ */
159
+ addDevice(groupId: string, keyPackageEvent: NostrEvent, reopenedLeafKey?: string | readonly string[], approvalEpoch?: number, origin?: 'approval'): Promise<void>;
160
+ /** One durable commit removing every leaf carrying `leafKey`; resolves `absent` when none is left. Rejects like `send`. */
161
+ removeLeaf(groupId: string, leafKey: string): Promise<'committed' | 'absent'>;
162
+ /**
163
+ * Whether this port's views report `successions` (and it announces new ones through {@link onRotation}). The device
164
+ * service runs its one-time succession catch-up only for a port that does; default: whether `onRotation` is defined.
165
+ */
166
+ readonly reportsSuccessions?: boolean;
167
+ /**
168
+ * `removeLeaf` for a whole device chain (Design Decision 8): one durable commit removing every leaf carrying any of
169
+ * `leafKeys`. Optional until the client implements it (S6/S11): without it a forget removes the chain's leaves one
170
+ * key at a time through {@link removeLeaf}, with the same read-back.
171
+ */
172
+ removeLeaves?(groupId: string, leafKeys: readonly string[]): Promise<'committed' | 'absent'>;
173
+ /**
174
+ * Epic marmot-device-key-rotation (S6, AC-REKEY-9): one durable commit replacing the local leaf's signature key with
175
+ * `target` (hex of the public key `deviceRegistry/self` holds), on the group's queue. `'satisfied'` without a commit
176
+ * when the local leaf already carries `target`, `'not-member'` when the local leaf was removed from the group; rejects
177
+ * like `send` otherwise (`reentrant` from a consumer surface, `commit-pending` while another own commit is pending,
178
+ * `send-rejected` with `details.reason` `superseded` when `target` is no longer the device key, `proof-invalid`, …).
179
+ * A duplicate same-account leaf holding `target` is removed in the same commit. Optional until the client implements
180
+ * it; the device service (S7) drives a rotation through it.
181
+ */
182
+ rekey?(groupId: string, target: string): Promise<'committed' | 'satisfied' | 'not-member'>;
183
+ /**
184
+ * `listener(groupId)` runs after a `leaf-key-rotated` notification of a held group (a sibling's or this client's own
185
+ * rotation commit joined its canonical path): its `DeviceGroupView.successions` may have grown. Called detached,
186
+ * outside the group's queue and every consumer frame; a throwing listener is ignored. Returns the unsubscribe. A
187
+ * withdrawn rotation is not announced: a recorded link is a fact about the device and is never undone.
188
+ */
189
+ onRotation?(listener: (groupId: string) => void): () => void;
190
+ /**
191
+ * S10 (V1 revisable settlement): `listener(groupId)` runs after a persisted
192
+ * transition of a held group withdrew commits — a fork rewind moved the
193
+ * group off a branch it had applied, so an outcome read from that branch's
194
+ * tree (an Add, a Remove) may no longer hold. Called detached, outside the
195
+ * group's queue and every consumer frame (it may run group operations);
196
+ * a throwing listener is ignored. Returns the unsubscribe.
197
+ */
198
+ onRewind(listener: (groupId: string) => void): () => void;
199
+ /**
200
+ * Owner decision 13: `listener(groupId)` runs after a `groups.restore` of a group succeeded (its owed-rotation marker,
201
+ * restore-rotation.ts, is durable by then). Detached, outside every queue; a throwing listener is ignored. Optional:
202
+ * a port without it leaves the marker to the next pass. Returns the unsubscribe.
203
+ */
204
+ onRestored?(listener: (groupId: string) => void): () => void;
205
+ /**
206
+ * The durable side of `onRewind`: every held group a persisted transition
207
+ * rewound since its last cleared recheck, with the marker's token. Written
208
+ * in the transition's own transaction — it survives a crash before the
209
+ * in-memory announcement. `withdrawnLeaves` (S20 round 1): the leaf keys the
210
+ * rewinds withdrew, decided when they were persisted (absent: a marker
211
+ * written before that, with no such evidence).
212
+ */
213
+ settlementRechecks(): Promise<readonly {
214
+ readonly groupId: string;
215
+ readonly token: number;
216
+ readonly withdrawnLeaves?: readonly string[];
217
+ }[]>;
218
+ /** Clears `groupId`'s recheck marker when it still carries `token` (a later rewind's marker stays). */
219
+ clearSettlementRecheck(groupId: string, token: number): Promise<void>;
220
+ /**
221
+ * S20: where `leafKey` (a leaf of this account) appears in the group's retained rewind window — on a state of the
222
+ * CURRENT canonical path (`canonical`; the current state included), and/or on a state a rewind abandoned
223
+ * (`abandoned`, a fork node of the window). `undefined` when the group is not held. Optional: a port without it
224
+ * keeps the S10 rule (absent now = withdrawn). `leafKey` may be a key set (a device chain, AC-RM-3): the leaf is then
225
+ * any leaf of this account carrying one of the keys.
226
+ */
227
+ leafOnBranches?(groupId: string, leafKey: string | readonly string[]): Promise<{
228
+ readonly canonical: boolean;
229
+ readonly abandoned: boolean;
230
+ } | undefined>;
231
+ }
232
+ /** The lifecycle-event emitter (`ctx.lifecycle.afterCommit`, AC-INBOX-6): the ONLY way `enrolmentApproved` / `deviceForgotten` are emitted. */
233
+ export interface DeviceLifecycle {
234
+ afterCommit<T>(event: 'enrolmentApproved', commit: () => Promise<T>, payload: (result: T) => {
235
+ readonly account: string;
236
+ readonly leafIndex: number;
237
+ readonly leafKey: string;
238
+ readonly groups: readonly string[];
239
+ }): Promise<T>;
240
+ afterCommit<T>(event: 'deviceForgotten', commit: () => Promise<T>, payload: (result: T) => {
241
+ readonly leafKey: string;
242
+ readonly groups: readonly string[];
243
+ }): Promise<T>;
244
+ /** Epic marmot-device-key-rotation (S7, AC-ROT-8): fires after the rotation's prepare transaction committed. */
245
+ afterCommit<T>(event: 'deviceKeyRotated', commit: () => Promise<T>, payload: (result: T) => {
246
+ readonly rotationId: string;
247
+ readonly from: readonly string[];
248
+ readonly to: string;
249
+ readonly groups: readonly string[];
250
+ }): Promise<T>;
251
+ /** Epic marmot-device-key-rotation (S7, AC-ROT-8): fires after the transaction that settled the rotation committed. */
252
+ afterCommit<T>(event: 'deviceKeyRotationSettled', commit: () => Promise<T>, payload: (result: T) => {
253
+ readonly rotationId: string;
254
+ readonly perGroupOutcome: Readonly<Record<string, DeviceKeyRotationGroupOutcome>>;
255
+ }): Promise<T>;
256
+ }
257
+ /**
258
+ * What `devices.rotateKey()` needs that the account module cannot build itself (epic marmot-device-key-rotation, S7): the
259
+ * ciphersuite implementation a fresh device key is generated with, and the KeyPackage retirement over the client's
260
+ * KeyPackage dependencies. Optional so a service built without them (an enrolment-only harness) refuses `rotateKey()`
261
+ * with `invalid-options` instead of failing to construct.
262
+ */
263
+ export interface DeviceRotationPorts {
264
+ /** The ciphersuite implementation (the client's default suite) `prepareDeviceKeyRotation` generates the key with. */
265
+ ciphersuiteImpl(): Promise<CiphersuiteImpl>;
266
+ /** `retireKeyPackagesSignedWith` over the client's KeyPackage dependencies (a rejection propagates). */
267
+ retireKeyPackages(keys: readonly string[]): Promise<KeyPackageRetirementOutcome>;
268
+ }
269
+ export interface DeviceServiceDeps {
270
+ readonly clock: {
271
+ now(): number;
272
+ };
273
+ readonly timers: {
274
+ set(callback: () => void, ms: number): unknown;
275
+ clear(handle: unknown): void;
276
+ };
277
+ readonly relays: {
278
+ readonly defaults: readonly string[];
279
+ readonly mode: 'discover' | 'fixed';
280
+ };
281
+ /** Deadline of relay lookups (inbox relays, KeyPackage events). */
282
+ readonly lookupTimeoutMs: number;
283
+ /** Most distinct enrolment requests one session id may have prompted within a minute (AC-DEV-5). */
284
+ readonly promptRateLimit: number;
285
+ /** Relay event-size budget of an own enrolment request's gift wrap (bytes; default `DEFAULT_MAX_GIFT_WRAP_BYTES`, 64 KiB). */
286
+ readonly maxGiftWrapBytes?: number;
287
+ /** The account-key signer (seals, deletions), routed through the guard. */
288
+ readonly signer: Signer;
289
+ /** The client's transport, routed through the guard. */
290
+ readonly transport: TransportContract;
291
+ readonly verifier: ((event: NostrEvent) => Promise<boolean>) | undefined;
292
+ /** `AccountStore.transaction`, routed through the guard. */
293
+ transaction<T>(fn: (tx: AccountStoreTx) => Promise<T> | T): Promise<T>;
294
+ readonly groups: DeviceGroupPort;
295
+ /** S4 `keyPackages.create()` (durable intent → publish → confirm). */
296
+ createKeyPackage(): Promise<NostrEvent>;
297
+ /** The relays a KeyPackage minted now would name (S4 `resolveWriteRelays` for the local account). */
298
+ keyPackageRelays(): Promise<readonly string[]>;
299
+ /** S4 `fetchKeyPackageEvents` for the local account. */
300
+ fetchKeyPackageEvents(pubkey: string): Promise<{
301
+ readonly events: readonly NostrEvent[];
302
+ readonly relays: readonly string[];
303
+ readonly timedOut: boolean;
304
+ }>;
305
+ readonly lifecycle: DeviceLifecycle;
306
+ /** S7: the primitives `devices.rotateKey()` is built on (see {@link DeviceRotationPorts}). */
307
+ readonly rotation?: DeviceRotationPorts;
308
+ /**
309
+ * Runs one device-queue operation inside the client's `DEVICE_SCOPE`
310
+ * re-entrancy frame (client/reentrancy-guard.ts): every consumer surface it
311
+ * reaches — an `onConfirm` hook of its commit, a store, a signer — carries it.
312
+ */
313
+ inDeviceFrame<T>(fn: () => Promise<T>): Promise<T>;
314
+ /** Throws `reentrant` when called from inside a `DEVICE_SCOPE` frame (a consumer surface a device operation is waiting on). */
315
+ assertNotInDeviceOperation(operation: string): void;
316
+ /**
317
+ * Throws `MarmotError('reentrant')` when called from inside a live `onConfirm`/`verifier`/`onProposal` frame
318
+ * of ANY group (S3 AC-RE-2) — before a device operation enqueues onto the device's serial queue. Without
319
+ * this, a group op awaiting one of these surfaces (which in turn awaits a device op) can deadlock against a
320
+ * second, concurrent device op that itself needs that very group's queue: the second device op would queue
321
+ * behind the first, which is blocked on the group's queue, which will not free until the first device op's
322
+ * surface call (the one causing the wait) settles — but that call is what tried to enqueue the second device
323
+ * op in the first place. Rejecting here, before `queue.run(...)`, breaks the cycle instead of joining it.
324
+ */
325
+ assertNotInGroupConsumerSurface(operation: string): void;
326
+ /**
327
+ * Background device work given up after {@link MAX_MAINTENANCE_FAILURES} counted failures (after the write
328
+ * committed): the client's `maintenanceFailed` event. `invitationId` names the record — the forgotten leaf
329
+ * key (`keypackage-deletion`, `device-forget`), the request id (`enrolment-approval`, `enrolment-request`), the
330
+ * rotation id (`device-rotation`), or the sentinel `'restore-rotation'` for the rotation restores owe (owner
331
+ * decision 13; `groups`: the restored groups still on the backed-up key).
332
+ */
333
+ onMaintenanceFailed(failure: {
334
+ readonly invitationId: string;
335
+ readonly kind: DeviceMaintenanceKind;
336
+ readonly reason: string;
337
+ /**
338
+ * `enrolment-approval`: the groups the device DID join before the approval was given up (it is finalized for them).
339
+ * `device-rotation` with `'restore-rotation'`: the restored groups whose owed rotation was given up.
340
+ */
341
+ readonly groups?: readonly string[];
342
+ }): void;
343
+ /** The approval prompt of an enrolment request that passed the replay, expiry and rate checks (after its record committed). */
344
+ onPrompt(prompt: EnrolmentPrompt): void;
345
+ isDisposed(): boolean;
346
+ }
347
+ /**
348
+ * Counted failures after which a piece of background device work is given up
349
+ * (`maintenanceFailed`) — S6's cap for invitation maintenance, with the same
350
+ * classification (`maintenanceFailureReason`, inbox/): explicitly transient
351
+ * causes (a signer timeout or locked key, a store lease) are never counted.
352
+ */
353
+ export declare const MAX_MAINTENANCE_FAILURES = 10;
354
+ /** Background device work that can be given up (W1): the `maintenanceFailed` kinds S8 adds, and S9's `teardown` (a group's leave/abandon/destroy intent, `invitationId` = the group id). */
355
+ export type DeviceMaintenanceKind = 'keypackage-deletion' | 'device-forget' | 'enrolment-approval' | 'enrolment-request' | 'teardown' | 'device-rotation';
356
+ /**
357
+ * The approval prompt data (AC-DEV-9): what a sibling device shows its user
358
+ * before `approveEnrolment`. Nothing in it is derived from the requested
359
+ * KeyPackages (their `d` slots, refs or keys).
360
+ */
361
+ export interface EnrolmentPrompt {
362
+ /** The request id: the sealed enrolment-request rumor's id — what `approveEnrolment` takes. */
363
+ readonly requestId: string;
364
+ readonly sessionId: string;
365
+ /** The requesting device's label, as it sent it. */
366
+ readonly label: string;
367
+ /** Seconds since the request was made (its rumor's `created_at`), on this client's clock. */
368
+ readonly ageSeconds: number;
369
+ /**
370
+ * The inbox relay(s) it arrived over: the relays that delivered its wrap
371
+ * (transport relay provenance, `DispatchContext.relays`) — the relay set the
372
+ * inbox was reading only for a delivery that carried no provenance.
373
+ */
374
+ readonly relays: readonly string[];
375
+ /** The groups the device asks to join. */
376
+ readonly groupIds: readonly string[];
377
+ /** Unix seconds after which the request is void. */
378
+ readonly expiresAt: number;
379
+ }
@@ -0,0 +1,36 @@
1
+ /** The account artifact holding device-registry entries (`<leafKey>`, with a tombstone once forgotten) and forget intents (`forget:<leafKey>`). */
2
+ export const DEVICE_REGISTRY_ARTIFACT = 'deviceRegistry';
3
+ /**
4
+ * The tombstone's OWN departure time: `forgetStartedAt` (the forget that settled it, stamped at settle time) —
5
+ * preferred since it is the departure's true start, not when the tombstone happened to be written — else `at`
6
+ * (a pre-remediation tombstone with no `forgetStartedAt`), else `Infinity` for a present but non-numeric value
7
+ * (never silently loosened to "no departure"). `undefined` only when `tombstone` itself is `undefined` — there
8
+ * is no tombstone at all, as distinct from one whose time could not be read.
9
+ */
10
+ export function tombstoneDepartureTime(tombstone) {
11
+ if (tombstone === undefined)
12
+ return undefined;
13
+ if (typeof tombstone.forgetStartedAt === 'number')
14
+ return tombstone.forgetStartedAt;
15
+ if (typeof tombstone.at === 'number')
16
+ return tombstone.at;
17
+ return Infinity;
18
+ }
19
+ /**
20
+ * The forget record's OWN departure time: `startedAt`, else `Infinity` for a present but non-numeric value.
21
+ * `undefined` only when `forget` itself is `undefined` — no forget record at all.
22
+ */
23
+ export function forgetDepartureTime(forget) {
24
+ if (forget === undefined)
25
+ return undefined;
26
+ if (typeof forget.startedAt === 'number')
27
+ return forget.startedAt;
28
+ return Infinity;
29
+ }
30
+ /**
31
+ * Counted failures after which a piece of background device work is given up
32
+ * (`maintenanceFailed`) — S6's cap for invitation maintenance, with the same
33
+ * classification (`maintenanceFailureReason`, inbox/): explicitly transient
34
+ * causes (a signer timeout or locked key, a store lease) are never counted.
35
+ */
36
+ export const MAX_MAINTENANCE_FAILURES = 10;
@@ -0,0 +1,199 @@
1
+ /**
2
+ * Device lineage (epic marmot-device-key-rotation, Design Decisions 4, 7 and 9).
3
+ *
4
+ * A device is the chain of leaf signature keys linked by successions: a rotation
5
+ * replaces the key `A` of a leaf by `B` and leaves the link `A -> B`. Every place
6
+ * that used to match a leaf key by equality matches by lineage instead
7
+ * ({@link DeviceLineage.sameDevice}), so a device that is half-way through a
8
+ * rotation (some groups re-keyed, some not), forgotten while it rotates, or
9
+ * observed by a sibling that saw only some of the commits stays one device.
10
+ *
11
+ * Two parts, kept apart on purpose:
12
+ *
13
+ * - {@link createDeviceLineage}: pure resolution over a set of `from -> to`
14
+ * edges. Edges come from the registry's `rotated:<fromKey>` records
15
+ * (`key-packages/device-rotation-records.ts`, strictly decoded) and may be
16
+ * united with the canonical-path successions a group's view reports
17
+ * ({@link viewSuccessionEdges}), so a caller never depends on whether a
18
+ * notification or the catch-up feed has already written the link. There is
19
+ * one primary edge per `fromKey` (the first one given wins; `headOf` follows
20
+ * it, for at most {@link MAX_LINEAGE_DEPTH} links, a cycle ending where it is
21
+ * detected, so a corrupt record set cannot loop); further edges of the same
22
+ * key are alternate evidence that still joins the device (`sameDevice`).
23
+ * - {@link recordSuccession} and the registry-entry helpers: the writes. A
24
+ * registry entry (label, enrolment time, leaf index, tombstone) lives at
25
+ * the lineage head; recording a link moves every older entry of the chain
26
+ * there in the same transaction.
27
+ *
28
+ * The lineage holds public keys only. It is a fact about what a device generated
29
+ * ("this key descends from that one"), never about which key a group's tip holds.
30
+ */
31
+ import type { Signer } from '@941design/nostr-events/signer';
32
+ import { MarmotError } from '../shared/index.js';
33
+ import type { AccountStoreTx, KeyValueView } from '../storage/index.js';
34
+ import { type DeviceKeyLinkSource } from '../key-packages/index.js';
35
+ import { type DeviceGroupView } from './device-deps.js';
36
+ /** Most links one head resolution follows (AC-LIN-1). */
37
+ export declare const MAX_LINEAGE_DEPTH = 64;
38
+ /** A lineage edge: the key a leaf had, and the key that replaced it. */
39
+ export type LineageEdge = readonly [from: string, to: string];
40
+ /**
41
+ * The keys `target` descends from: those from which it is reached along `edges` (the primary links and the alternate
42
+ * evidence alike), `target` itself excluded. THE directed-ancestry rule: not the lineage component, because two live
43
+ * installations that share an origin key are one component but two devices, and the other installation's keys are not this
44
+ * device's to retire, re-key from, refuse or recognise. Pure and total (a cycle ends at the closure).
45
+ */
46
+ export declare function directedAncestors(target: string, edges: Iterable<LineageEdge>): Set<string>;
47
+ export interface DeviceLineage {
48
+ /**
49
+ * The newest key of `key`'s chain along the first-recorded successor of each key (`key` itself when it has no link;
50
+ * where a cycle is detected, or after {@link MAX_LINEAGE_DEPTH} links, the key reached). So a chain of more than
51
+ * {@link MAX_LINEAGE_DEPTH} rotations resolves its oldest keys to a key that is not the real head; they remain the same
52
+ * device ({@link sameDevice} does not depend on the cap).
53
+ */
54
+ headOf(key: string): string;
55
+ /**
56
+ * The one key a device's registry entry is stored under: the head of the oldest key of its component. Equal to
57
+ * {@link headOf} for every key of a device with a single chain.
58
+ */
59
+ deviceHeadOf(key: string): string;
60
+ /** Every head of `key`'s device (more than one only when alternate evidence shows two successors of one key), sorted. */
61
+ headsOf(key: string): readonly string[];
62
+ /**
63
+ * Every key of the device `key` belongs to, oldest first (ties by key); `[key]` when it has no link. When the
64
+ * lineage was built knowing the live keys (`createDeviceLineage(edges, live)`) and a component has TWO OR MORE live
65
+ * heads (two installations that share an origin key, e.g. a restore while the original runs, both rotated), the
66
+ * component is not one device: a key that leads to exactly one live head belongs to that head's device (its directed
67
+ * ancestry); only a shared origin key reaches both and keeps the whole component.
68
+ */
69
+ keysOf(key: string): readonly string[];
70
+ /**
71
+ * The keys whose registry ENTRIES may be folded into `key`'s entry: {@link keysOf}, except that a component with
72
+ * several heads and no knowledge of which are live is left unfolded (`[key]`), so a write that cannot tell never merges
73
+ * the entries of two live installations.
74
+ */
75
+ entryKeysOf(key: string): readonly string[];
76
+ /**
77
+ * The keys a device is shown under: the live head(s) it leads to (one in the normal case, one per live head of a
78
+ * contested component), else the head a caller would store under ({@link deviceHeadOf}).
79
+ */
80
+ displayHeadsOf(key: string): readonly string[];
81
+ /** Keys of `key`'s component that are NOT its device's (the other installations of a contested component); empty otherwise. */
82
+ apartFrom(key: string): readonly string[];
83
+ /** Whether both keys belong to one device: an equivalence relation over ALL edges, alternates included. */
84
+ sameDevice(a: string, b: string): boolean;
85
+ /**
86
+ * The keys `key` descends from along ALL edges (see {@link directedAncestors}), `key` excluded, sorted: this device's
87
+ * retired keys when `key` is its current one. A sibling installation's keys are never among them.
88
+ */
89
+ ancestorsOf(key: string): readonly string[];
90
+ /** A frozen copy of the keys that were replaced by a successor (not heads): the synchronous "retired keys" snapshot. */
91
+ retiredKeys(): ReadonlySet<string>;
92
+ /** Whether `key` was replaced by a successor. */
93
+ isRetired(key: string): boolean;
94
+ }
95
+ /**
96
+ * Resolution over `edges`. For a key with several edges the first one given is the primary successor ({@link
97
+ * DeviceLineage.headOf} follows it); the others are alternate evidence: they still join their keys into the device
98
+ * ({@link DeviceLineage.sameDevice}, {@link DeviceLineage.keysOf}). All edges are the local account's own
99
+ * successions (signed under the old key), so a withdrawn rotation followed by a different one leaves ONE device.
100
+ * Pure, total and independent of the order edges arrive in apart from which duplicate is primary.
101
+ */
102
+ export declare function createDeviceLineage(edges: Iterable<LineageEdge>, live?: ReadonlySet<string>): DeviceLineage;
103
+ /** Prefix of an alternate-evidence row: `rotated-alt:<fromKey>:<toKey>` (kept apart from `rotated:` so the link codec is untouched). */
104
+ export declare const ROTATED_ALT_PREFIX = "rotated-alt:";
105
+ /** The local account's pubkey, asked of the signer once per signer (a rejection is not cached). */
106
+ export declare function localAccountOf(signer: Signer): Promise<string>;
107
+ /**
108
+ * The lineage edges a set of group views report for the local account — the one place a view's `successions` are read.
109
+ * The signer is asked for the account only when some view actually reports successions, so a port that reports none
110
+ * never needs the (possibly remote, possibly locked) signer. Another account's succession is never one (AC-LIN-3).
111
+ */
112
+ export declare function viewSuccessionEdges(signer: Signer, views: Iterable<DeviceGroupView | undefined>): Promise<LineageEdge[]>;
113
+ /**
114
+ * THE lineage rule: the registry's recorded links, then `extra` edges (the successions groups' views report), then the
115
+ * recorded alternates. A reader that goes on to WRITE must first {@link persistSuccessionEdges} the view edges in the same
116
+ * transaction, so a write is never keyed by a lineage the registry does not hold.
117
+ */
118
+ export declare function loadDeviceLineage(view: KeyValueView, extra?: Iterable<LineageEdge>, live?: ReadonlySet<string>): Promise<DeviceLineage>;
119
+ /**
120
+ * The closure of `seed` over `edges` without entering `apart` (the other installations of a contested component): how a
121
+ * forget's chain grows as successions are recorded, without ever pulling in a live device it was not asked to forget.
122
+ */
123
+ export declare function chainClosure(seed: Iterable<string>, edges: Iterable<LineageEdge>, apart?: Iterable<string>): Set<string>;
124
+ /** Every recorded edge: the links, then the alternates (strict decode). */
125
+ export declare function readRegistryEdges(view: KeyValueView): Promise<LineageEdge[]>;
126
+ /** Records every edge (idempotent, see {@link recordSuccession}) so the registry holds what a view showed before a write relies on it; returns whether it wrote. */
127
+ export declare function persistSuccessionEdges(tx: AccountStoreTx, edges: Iterable<LineageEdge>, now: () => number, live?: ReadonlySet<string>): Promise<boolean>;
128
+ /** A forgotten device: when it was forgotten, and the groups still holding its leaf then. */
129
+ export interface DeviceTombstone {
130
+ /** Client clock (ms) — when the forget SETTLED (the tombstone was written), not when it started. */
131
+ readonly at: number;
132
+ readonly groups: readonly string[];
133
+ /**
134
+ * AC-RECHK-2: the settling forget record's OWN `startedAt` (client clock, ms), stamped
135
+ * onto the tombstone at settle time. `reopenApprovalGroup` / `supersedeDeparture` compare THIS — never
136
+ * `at` — against an approval's `approvedAt`, so the tombstone and its originating forget record are judged
137
+ * by the SAME authoritative time; `at` (the settle time, always >= `forgetStartedAt`) previously let the two
138
+ * disagree when an approval raced a forget's settlement, leaving a re-added member with a stale tombstone.
139
+ * Absent on a tombstone written before this field existed.
140
+ */
141
+ readonly forgetStartedAt?: number;
142
+ }
143
+ /** The registry entry of one device, stored under its lineage head. */
144
+ export interface RegistryEntry {
145
+ readonly v: 1;
146
+ readonly leafKey: string;
147
+ readonly label: string;
148
+ readonly enrolledAt: number;
149
+ /** Last leaf index seen for it (kept for a tombstoned device no held group shows any more). */
150
+ readonly leafIndex?: number;
151
+ readonly tombstone?: DeviceTombstone;
152
+ }
153
+ export declare function malformedRegistryRecord(key: string): MarmotError;
154
+ export declare function readRegistryEntry(view: KeyValueView, leafKey: string): Promise<RegistryEntry | undefined>;
155
+ /**
156
+ * `moved`'s facts folded into `target` (which stays under its own key): the target's non-empty `label` wins, it takes the
157
+ * moved `enrolledAt` when its own is 0 and the moved `leafIndex` when it has none, and a moved tombstone follows the
158
+ * device (when both have one, the later `at`).
159
+ */
160
+ export declare function mergeRegistryEntries(target: RegistryEntry, moved: RegistryEntry): RegistryEntry;
161
+ /**
162
+ * Moves every entry stored under an older key of `head`'s chain to `head` (merging, see {@link mergeRegistryEntries};
163
+ * nearest the head first) and deletes the old rows. Returns the entry at `head` afterwards and whether anything moved.
164
+ * Writes nothing when no older key has an entry.
165
+ */
166
+ export declare function consolidateRegistryEntries(view: KeyValueView, lineage: DeviceLineage, head: string): Promise<{
167
+ readonly entry: RegistryEntry | undefined;
168
+ readonly moved: boolean;
169
+ }>;
170
+ export interface RecordSuccessionInput {
171
+ /** The key the leaf had. */
172
+ readonly from: string;
173
+ /** The key that replaced it. */
174
+ readonly to: string;
175
+ /** The group whose canonical path made the succession (informational: the link states a fact about the device, not about a group). */
176
+ readonly groupId: string;
177
+ /** The commit that made it (informational, as {@link groupId}). */
178
+ readonly commitDigest: string;
179
+ /** Client clock (ms). */
180
+ readonly at: number;
181
+ /** The keys currently held in groups (and the own key), when the caller knows them: lets a contested component keep its installations apart. */
182
+ readonly live?: ReadonlySet<string>;
183
+ /** Default `observed`; the prepare step of a rotation this client performs writes its own links itself. */
184
+ readonly source?: DeviceKeyLinkSource;
185
+ }
186
+ /**
187
+ * `recorded` — a link, an alternate or an entry move was written; `unchanged` — a repeat, nothing was written; `ignored` —
188
+ * the link is refused: a malformed or self link, or a link that would close a cycle.
189
+ */
190
+ export type RecordSuccessionResult = 'recorded' | 'unchanged' | 'ignored';
191
+ /**
192
+ * Records "`from` was succeeded by `to`" and, in the same transaction, moves the registry entries of the whole device to
193
+ * its entry key ({@link DeviceLineage.deviceHeadOf}). Idempotent and independent of arrival order. A `fromKey` that
194
+ * already has a link to a DIFFERENT key keeps it (the first is primary); the new one is persisted as alternate evidence
195
+ * (`rotated-alt:<from>:<to>`) unless both keys are already one device — the old key signed both successions, so the
196
+ * device is one (a rotation withdrawn by a fork, then a different one). The caller decides that the succession belongs
197
+ * to the local account (AC-LIN-3): this writes whatever it is given.
198
+ */
199
+ export declare function recordSuccession(tx: AccountStoreTx, input: RecordSuccessionInput): Promise<RecordSuccessionResult>;