@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,9 @@
1
+ import { type PermissionDeclaration } from '@941design/nostr-events/signer/permissions';
2
+ /**
3
+ * Signer permissions `marmot` needs from the account key (AC-API-7): signing
4
+ * KeyPackages (30443), seals (13), deletions (5), relay AUTH (22242) and the
5
+ * identity-proof template (450), plus NIP-44. Kinds 445 and 1059 are signed
6
+ * by ephemeral keys and are deliberately absent.
7
+ */
8
+ export declare const ACCOUNT_KEY_SIGN_KINDS: readonly [30443, 13, 5, 22242, 450];
9
+ export declare const permissions: PermissionDeclaration;
@@ -0,0 +1,12 @@
1
+ import { declarePermissions } from '@941design/nostr-events/signer/permissions';
2
+ /**
3
+ * Signer permissions `marmot` needs from the account key (AC-API-7): signing
4
+ * KeyPackages (30443), seals (13), deletions (5), relay AUTH (22242) and the
5
+ * identity-proof template (450), plus NIP-44. Kinds 445 and 1059 are signed
6
+ * by ephemeral keys and are deliberately absent.
7
+ */
8
+ export const ACCOUNT_KEY_SIGN_KINDS = Object.freeze([30443, 13, 5, 22242, 450]);
9
+ export const permissions = declarePermissions({
10
+ signEventKinds: ACCOUNT_KEY_SIGN_KINDS,
11
+ nip44: true,
12
+ });
@@ -0,0 +1,583 @@
1
+ /**
2
+ * Intent -> publish -> confirm pipeline (S3): AC-PIPE-1, 2, 3, 11, 13.
3
+ *
4
+ * `sendIntent` implements `MarmotGroup.send`'s body (already running inside
5
+ * `rt.run('send', ...)` — the caller, `group-runtime.ts`'s handle, provides
6
+ * the serial-queue + re-entrancy guarding). `resumePending` drains every
7
+ * durable pending-intent record of a group, on load and at the start of
8
+ * every mutating op (`sendIntent` itself calls it first).
9
+ *
10
+ * S5 adds, on the same records: the invite commit (`inviteIntent`, AC-INVITE-1:
11
+ * its Welcome rumors are stored at staging with the envelope and handed to the
12
+ * invitations service once a relay accepted the commit), the pending-proposal
13
+ * policy in front of every own commit (`onProposal`, AC-INVITE-4), and the
14
+ * durable queue of application rumors that wait for the next confirmed commit
15
+ * (`advanceQueue`, AC-INVITE-3). `not-a-member` is refused before anything is
16
+ * recorded (AC-INVITE-7).
17
+ *
18
+ * S9 adds the admin-list commit (`setAdminsIntent`, AC-ADMIN-1; the demotion of
19
+ * `departAsAdmin`), the local leaf's SelfRemove proposal (`leave()`), and the
20
+ * publication of the engine's SelfRemove auto-commit election
21
+ * (`scheduleSelfRemoveCommit`, AC-ADMIN-9): all through the same records.
22
+ *
23
+ * S18 adds the pre-sync send gate (AC-PIPE-15, `GroupRuntime.sendGateOpen`):
24
+ * after a load, no own envelope is minted until the group's first post-load
25
+ * sync completes — `send()` records `awaiting-sync` intents, the other own
26
+ * commits are refused, background minting waits; see "the pre-sync send gate".
27
+ *
28
+ * epic-marmot-client-hardening S8 adds the post-load own-ratchet skip (AC-RATCH-1, `GroupRuntime.ratchetSkipPending`):
29
+ * the first own application message minted after a load jumps the sender ratchet `ratchetSkipMargin` generations
30
+ * (engine `SendIntent.ratchetSkip`), persisted only with that message's staged envelope together with a skip marker
31
+ * that a relay's acceptance of an own application message marks delivered (`settlePublishedRecord`); a load does not
32
+ * re-arm the skip over an undelivered one of the same epoch state (group-records.ts `ratchetSkipArmed`).
33
+ */
34
+ import type { NostrEvent } from '@941design/nostr-events/event';
35
+ import { type ActiveAdminLeaverPredicate } from '@941design/marmot-engine/engine';
36
+ import type { PendingState } from '@941design/marmot-engine/engine';
37
+ import { type ClientState, type Proposal } from '@941design/marmot-engine/mls';
38
+ import { type Invitee } from '../invitations/index.js';
39
+ import { MarmotError } from '../shared/index.js';
40
+ import type { GroupStoreTx } from '../storage/index.js';
41
+ import type { GroupIntent } from './create-client.js';
42
+ import { type MessageNotification } from '../history/index.js';
43
+ import { type TransitionPlan } from './group-history.js';
44
+ import { type OwnCommitMarker, type PendingIntentRecord, type StorableIntent } from './group-records.js';
45
+ import type { GroupRuntime } from './group-runtime.js';
46
+ export declare function assertNotDisposed(rt: GroupRuntime): void;
47
+ export declare function backoffMs(count: number): number;
48
+ /**
49
+ * The marker an own commit that {@link declaresOwnChange} leaves at confirm. An intent's marker carries `invitees` (each
50
+ * KeyPackage event, its ref and its leaf signature key, DD8/DD16) and what the intent `declared` (DD2). A re-drive record's
51
+ * marker carries the record's own changes instead, verdict-stripped and without the ones already decided lost (the
52
+ * re-drive commit carries the survivors; a later withdrawal of it re-drives exactly those), its `forkEpoch`, and the invitees
53
+ * its `member-added` changes name — so each marked node of the root carries what a later withdrawal needs, even once the
54
+ * original's marker was pruned (DD6, S1 lead decision). The fork-point values on a marker's changes are NOT authoritative (the codec
55
+ * requires them): a withdrawal uses the list only as a filter by change identity and recomputes the values.
56
+ */
57
+ declare function ownCommitMarkerOf(record: PendingIntentRecord, node: string): OwnCommitMarker;
58
+ declare function terminalFail(rt: GroupRuntime, record: PendingIntentRecord, hasCaller: boolean, cause: unknown, extraDetails?: Record<string, unknown>): Promise<void>;
59
+ /** The fields of an own intent's record a settlement names. */
60
+ type SettledRecord = Pick<PendingIntentRecord, 'intentId' | 'kind' | 'reenqueuedFrom'>;
61
+ /** Tells the runtime's settled-intent listeners (group-runtime.ts `groups.restore`) that `record` confirmed or went terminal. Never throws. */
62
+ export declare function notifySettled(rt: GroupRuntime, record: SettledRecord, error: MarmotError | undefined): void;
63
+ /** A genuine trigger (new send, ingested proposal): the held queue commit may be attempted again now. */
64
+ export declare function releaseQueueCommitHold(rt: GroupRuntime): void;
65
+ /**
66
+ * One Remove per leaf of `state` whose signature key (hex) is `leafKeys` or in it: a single key, or a key set (a device
67
+ * chain, epic marmot-device-key-rotation AC-RM-3/4). The leaf index is resolved here, from the tree at hand.
68
+ */
69
+ declare function removeProposalsFor(state: ClientState, leafKeys: string | readonly string[]): Proposal[];
70
+ /** Whether `state`'s tree holds a leaf carrying signature key `leafKey` (hex), or any key of the set `leafKey`. */
71
+ export declare function holdsLeafKey(state: ClientState, leafKey: string | readonly string[]): boolean;
72
+ /**
73
+ * S10: an own application message, confirmed, as the `message` notification
74
+ * (and history entry) every other member derives from it — the ordering key
75
+ * read from its own envelope under the state it was sent in.
76
+ */
77
+ export declare function ownMessage(rt: GroupRuntime, record: PendingIntentRecord, envelope: NostrEvent): Promise<MessageNotification | undefined>;
78
+ declare function confirmRecord(rt: GroupRuntime, record: PendingIntentRecord, attempt: number, live: PendingState | undefined, hasCaller?: boolean): Promise<void>;
79
+ /**
80
+ * Whether a background retry that failed with `error` must stop rather than
81
+ * reschedule: the client/runtime is gone, or the stores lost their lease (the
82
+ * next holder resumes the durable record). Anything else — a store or
83
+ * transport hiccup — is retried on the backoff.
84
+ *
85
+ * A lost lease is permanent for this client (every later write of its stores
86
+ * rejects `no-lease`), so no own intent of the group can settle here any more:
87
+ * the runtime's terminal signal fires (`reason: 'no-lease'`) so a wait on the
88
+ * group making progress (`groups.restore`'s self-update) ends instead of
89
+ * waiting for a settlement that never comes. `rt.leaseLost` remembers it for
90
+ * the checks made after the signal fired (a before-publish pass of a later
91
+ * resume must publish nothing).
92
+ */
93
+ export declare function backgroundRetryEnds(rt: GroupRuntime, error: unknown): boolean;
94
+ /**
95
+ * A signer call made on behalf of a group op: framed on the account scope AND
96
+ * the group's scope, so a signer that awaits a mutating call on this group
97
+ * (which would queue behind the op awaiting the signer) is rejected
98
+ * `reentrant` instead of deadlocking; other groups stay reachable.
99
+ */
100
+ export declare function callSignerForGroup<T>(rt: GroupRuntime, fn: () => T | Promise<T>): Promise<T>;
101
+ /**
102
+ * The shared start of every own-intent operation: resumes durable records,
103
+ * then refuses while a confirmation is blocked. Returns the remaining records.
104
+ */
105
+ export declare function preflight(rt: GroupRuntime, operation: string): Promise<PendingIntentRecord[]>;
106
+ /** AC-INVITE-7: a removed local leaf sends nothing — refused before any record or transport call. */
107
+ export declare function assertMember(rt: GroupRuntime, operation: string): void;
108
+ export declare function assertNoOwnCommitPending(rt: GroupRuntime, remaining: readonly PendingIntentRecord[], operation: string): void;
109
+ export declare function recordIntent(rt: GroupRuntime, kind: GroupIntent['type'], intent: StorableIntent, state?: 'pending-publish' | 'awaiting-sync', parentEpoch?: bigint,
110
+ /** Epic marmot-invitation-outcomes S5 (SC-5 I13): further writes in the SAME transaction as the record (the cleanup ledger entry). */
111
+ alsoWrite?: (tx: GroupStoreTx, record: PendingIntentRecord) => Promise<void>): Promise<PendingIntentRecord>;
112
+ /** What `sendIntent` hands back to the group handle. */
113
+ export interface SendOutcome {
114
+ /**
115
+ * Set when an application rumor was queued (AC-INVITE-3): settles once the
116
+ * rumor is published — awaited by the handle OUTSIDE the group's queue.
117
+ */
118
+ readonly queued?: Promise<void>;
119
+ }
120
+ /** What a caller of {@link sendIntent} may observe of the intent it drives. */
121
+ export interface SendObserver {
122
+ /**
123
+ * Called with the id of the record this call writes for the intent (for a self-update over staged Adds: the
124
+ * self-update's own record, not the Add commit's), as soon as it is durable — before it is driven, so a caller
125
+ * matching settlements by id (group-runtime.ts `groups.restore`) never misses one reported during the drive.
126
+ */
127
+ onRecorded?(intentId: string): void;
128
+ }
129
+ export declare function sendIntent(rt: GroupRuntime, intent: GroupIntent, observer?: SendObserver): Promise<SendOutcome>;
130
+ /**
131
+ * A self-update over staged Add proposals is two own commits: an Add-only
132
+ * commit carries no UpdatePath (the committer's leaf would not rotate), and the
133
+ * engine's self-update path discards the MLS Welcome the Adds need. So the
134
+ * staged proposals are committed first — Welcomes and all — and once that
135
+ * commit is confirmed the self-update runs at the next epoch as a real engine
136
+ * `selfUpdate` (one own commit in flight).
137
+ *
138
+ * Both intents are durable before anything is published (S13, AC-PIPE-1): ONE
139
+ * transaction writes the Add commit and the self-update, the latter carrying
140
+ * `after: <commit intentId>` (see {@link resolveDependency}). This one routine
141
+ * serves the live send (`update` undefined: the self-update record is created
142
+ * here) and every self-update record driven while Adds are staged (a resume
143
+ * after a failed staging write, a peer's Add having arrived meanwhile).
144
+ *
145
+ * With a caller: if no relay accepted the Add commit (it stays a durable
146
+ * intent and is retried) the call is refused `commit-pending` (reason
147
+ * `staged-adds-commit-unconfirmed`); if its confirmation is blocked,
148
+ * `confirm-blocked` — either way `details.selfUpdateIntentId` names the
149
+ * self-update, which stays durable and follows the commit once it confirms.
150
+ * Those refusals mean "the self-update has not run yet". If the Add commit
151
+ * goes terminal with the epoch unchanged, the self-update is dropped with it
152
+ * and the caller gets the commit's `send-rejected` (the self-update's own
153
+ * settlement is reported to the settled-intent listeners too). If it goes terminal because
154
+ * a foreign commit confirmed at its epoch (`stale-parent`), nothing holds the
155
+ * self-update back: it is re-parented and driven in the same call, which
156
+ * resolves once it is published (or rejects with the self-update's own error)
157
+ * — one rotation, nothing left for the caller to retry. If the self-update
158
+ * itself fails, the caller gets that error while the first commit stays confirmed.
159
+ */
160
+ declare function driveSelfUpdateOverStagedAdds(rt: GroupRuntime, update: PendingIntentRecord | undefined, hasCaller: boolean, observer?: SendObserver): Promise<void>;
161
+ /**
162
+ * Writes, in one transaction, the own commit of the staged proposals and the
163
+ * self-update that must follow it (`update`, re-sequenced behind it, or a new
164
+ * record): resume drives records in `seq` order, so the commit comes first.
165
+ */
166
+ declare function linkStagedAddsCommit(rt: GroupRuntime, update: PendingIntentRecord | undefined): Promise<{
167
+ readonly first: PendingIntentRecord;
168
+ readonly linked: PendingIntentRecord;
169
+ }>;
170
+ /**
171
+ * Where a self-update's `after` dependency stands. `waiting` while the commit
172
+ * it follows is still a record. `terminal` when that record is gone and the
173
+ * group is still at the self-update's parent epoch — the commit was dropped
174
+ * without moving the epoch — and the self-update record is deleted here;
175
+ * except that a re-enqueued self-update (AC-RACE-1) with budget left is
176
+ * `requeued` instead: kept without `after`, one attempt spent, its drive
177
+ * scheduled. Otherwise the commit (or a foreign one) moved the epoch on: the self-update
178
+ * is re-parented to the current epoch without `after`, durably, and returned
179
+ * to be driven like any self-update. A record without `after` is returned as is.
180
+ */
181
+ declare function resolveDependency(rt: GroupRuntime, record: PendingIntentRecord): Promise<PendingIntentRecord | 'waiting' | 'terminal' | 'requeued'>;
182
+ /**
183
+ * After a background confirmation of own commit `intentId` (a publish or
184
+ * confirm retry): a self-update waiting on it follows now rather than at the
185
+ * group's next op. A failure here leaves the self-update to a background resume.
186
+ */
187
+ declare function followDependents(rt: GroupRuntime, intentId: string): Promise<void>;
188
+ /**
189
+ * A commit-kind record just confirmed (or went terminal), which is exactly the change a re-enqueued
190
+ * self-update held back as "another own commit pending" (or as a later sibling) waits on. The queue drain only
191
+ * resumes pending records while `queuedHint` says something may be queued, so each still-envelope-less
192
+ * `reenqueuedFrom` record other than the one that just settled is re-evaluated directly here.
193
+ */
194
+ declare function retryDeferredSelfUpdateReenqueues(rt: GroupRuntime, justSettledIntentId: string): Promise<void>;
195
+ /**
196
+ * Runs {@link retryDeferredSelfUpdateReenqueues} as its own detached group op (S3 `detached-dispatch-rule`) —
197
+ * never awaited by the settlement that triggers it: a confirmation or terminal failure is already durable, and
198
+ * its own follow-up work (routing, resync, Welcome delivery, the queue drain, the caller's result) must not
199
+ * depend on this discovery's store read. A failed discovery leaves the deferred records durable; the queue
200
+ * drain is re-armed on its capped backoff (`queuedHint` cleared), which resumes them through the same rules.
201
+ */
202
+ export declare function scheduleDeferredReenqueueRetry(rt: GroupRuntime, justSettledIntentId: string): void;
203
+ /**
204
+ * A re-enqueued self-update (AC-RACE-1) is re-parented to the current epoch rather than failed as stale: it
205
+ * carries no epoch-specific payload, and the epoch it was recorded at routinely moves before it is driven (a
206
+ * sibling re-enqueue confirming first, a foreign commit ingested meanwhile) — the same move `resolveDependency`
207
+ * makes for the S13 self-update-after-a-commit chain. Only an envelope-less record without an `after`
208
+ * dependency qualifies (a minted envelope is bound to its epoch; `after` is `resolveDependency`'s to resolve).
209
+ */
210
+ declare function reparentReenqueued(rt: GroupRuntime, record: PendingIntentRecord): Promise<PendingIntentRecord>;
211
+ /** What {@link remintStaleReenqueue} did with a stale re-enqueue. */
212
+ type RemintOutcome = 'done' | 'fenced' | 'budget';
213
+ /**
214
+ * A re-enqueued self-update (AC-RACE-1) whose envelope was minted at an epoch a foreign commit has since moved
215
+ * the group past (its publish failed and was waiting on a retry). Its envelope can never be confirmed, but the
216
+ * rotation it stands for is still owed — unlike an ordinary own commit, it is not failed as stale. While the
217
+ * original's `maxPublishAttempts` budget lasts, the stale envelope is ledgered as a withdrawn rotation of the
218
+ * original (so a later fork choice landing on it is recognised by `cancelRestoredReenqueues`), the record is put
219
+ * back envelope-less with one attempt spent, and its drive is scheduled to re-mint it at the tip. (A rotation of
220
+ * the same original that became canonical again never reaches here: the restoring transition already deleted this
221
+ * record — see {@link driveReenqueuedSelfUpdate}.)
222
+ *
223
+ * Returns `'done'` when handled, `'fenced'` (fence / removal: the caller fails it at once, without probing) or
224
+ * `'budget'` (the budget is spent: the caller fails it terminally, once, under the original id, after one more stale
225
+ * probe that may still retain a stored commit). Only ever reached without a caller — a re-enqueue is driven in the
226
+ * background.
227
+ *
228
+ * The stale envelope's commit is retained as a fork node of the rewind window (staleOwnCommitWindow), so if a relay
229
+ * stored it despite the failed publish (a probe finds it; a timeout spends an attempt and retries, bounded by the
230
+ * budget — see staleProbe) and other members extend it, this client can follow that branch, and the withdrawn ledger
231
+ * entry written here names that node. If the probe found the envelope absent the entry is written as before but
232
+ * names no node of the window.
233
+ */
234
+ declare function remintStaleReenqueue(rt: GroupRuntime, record: PendingIntentRecord, fromRetryTimer: boolean): Promise<RemintOutcome>;
235
+ /** What one evaluation of a re-enqueued self-update did (see {@link driveReenqueuedSelfUpdate}). */
236
+ type ReenqueueDrive =
237
+ /** Nothing to drive: no such record, a fenced or finally removed group (its stranded records failed), or the test seam. */
238
+ 'absent'
239
+ /** Already minted: its own publish retry / confirmation owns it. */
240
+ | 'started'
241
+ /** Waits for another own commit, an earlier sibling, its `after` dependency, or the S18 send gate. */
242
+ | 'waiting'
243
+ /** Held by a revisable removal, the AC-RACE-2 election wait or a deferred proposal (AC-INVITE-4); `queuedHint` cleared. */
244
+ | 'held'
245
+ /** Driven (published, confirmed, retrying, or failed terminally through the ordinary path). */
246
+ | 'driven';
247
+ /**
248
+ * The one set of rules for driving an envelope-less self-update a rewind re-enqueued (AC-RACE-1,
249
+ * `own-self-update-reenqueue-on-rewind`). Rules 1-4 are {@link reenqueueTurn}'s, shared with the commit re-drive
250
+ * ({@link driveCommitRedrive}); 5-7 are this drive's own. Every path that reaches such a record — the detached drive scheduled at
251
+ * the withdrawal, a confirmation or terminal failure re-evaluating deferred siblings, the queue drain, the load-time
252
+ * and post-sync resumes (`resumePending`) — goes through here, so the rules cannot diverge between them:
253
+ *
254
+ * 1. the AC-RACE-3 test seam (`disableSelfUpdateReenqueueForTest`) stops here; a fenced or finally removed group
255
+ * fails its stranded re-enqueues; a revisable removal holds them (a winning sibling may restore the leaf);
256
+ * 2. nothing is minted before the S18 send gate opens (`releaseAwaitingSync` resumes it);
257
+ * 3. a record that already has an envelope (or is pending-confirm) belongs to its own retry/confirmation path —
258
+ * driving it again would mint a second commit at the same epoch;
259
+ * 4. another own commit-kind record that has actually started (an envelope, or pending-confirm) blocks it, and
260
+ * among envelope-less re-enqueue siblings only the lowest `seq` (withdrawal order) drives — the rest wait for
261
+ * `retryDeferredSelfUpdateReenqueues` after it settles (siblings never block each other otherwise);
262
+ * 5. an S13 `after` dependency is resolved first (`resolveDependency`);
263
+ * 6. the AC-RACE-2 election wait and a deferred proposal hold it, clearing `queuedHint` so the release (the wait's
264
+ * timer, a staged-set change) drains for real (`queue-drain-queuedHint-gate`);
265
+ * 7. otherwise it is driven, re-parented to the current epoch (`reparentReenqueued`, inside `driveIntent`), which
266
+ * routes a staged-Adds tip through the S13 two-commit path on its own.
267
+ *
268
+ * There is no drive-time "is the original rotation canonical again?" check: the restoring transition already
269
+ * cancelled such a record atomically (group-history.ts `cancelRestoredReenqueues`, over the transition's whole
270
+ * canonical path), because (a) the canonical path (`rt.window`'s tip) only ever changes through `recordTransition` —
271
+ * every writer that moves the tip writes the window in the same transaction as `recordTransition`, the other window
272
+ * writers only add fork nodes or re-snapshot nodes with the tip unchanged (pinned by
273
+ * test/client/write-window-sites.test.ts), and groups.restore/create start from a cleared store; and (b) every other
274
+ * writer of a ledger entry's `selfUpdateIntentId` names a non-canonical node or deletes the root's only record in the
275
+ * same transaction. A pending-confirm record the first tier keeps is resolved by `confirmRecord`, never driven here.
276
+ */
277
+ declare function driveReenqueuedSelfUpdate(rt: GroupRuntime, originalIntentId: string): Promise<ReenqueueDrive>;
278
+ /**
279
+ * Drives the re-enqueue of `originalIntentId` again after `delayMs` (clamped to the platform timer limit): a
280
+ * pipeline timer (tracked in `rt.pipelineTimers`, cancelled on dispose, its body detached) that calls
281
+ * {@link scheduleSelfUpdateReenqueue}. At most one is pending per original; the record itself stays durable, so a
282
+ * load resumes it (and re-arms for whatever is left of its `retryAt`).
283
+ */
284
+ declare function armReenqueueRetry(rt: GroupRuntime, originalIntentId: string, delayMs: number, redrive?: boolean): void;
285
+ /**
286
+ * Schedules {@link driveReenqueuedSelfUpdate} detached (S3 `detached-dispatch-rule`) — outside the ingest
287
+ * batch or confirmation frame that discovered the withdrawal (reachable from inside a device op's own commit,
288
+ * via `confirmRecord`), as its own group op. Never throws. A failure before anything was minted (a store or
289
+ * signer fault) leaves the record durable and envelope-less; nothing else may come along to drive it, so the
290
+ * queue drain is re-armed (`queuedHint` cleared) on its capped backoff, which resumes it through the same rules.
291
+ */
292
+ export declare function scheduleSelfUpdateReenqueue(rt: GroupRuntime, originalIntentId: string): void;
293
+ /**
294
+ * Schedules the drives of everything a transition withdrew: each withdrawn self-update (AC-RACE-1) and each withdrawn own
295
+ * commit (epic marmot-rewound-own-commit-no-signal, DD1) — detached, after the transition's transaction committed. The one
296
+ * call site for the transition producers (ingest, a confirmation, a branch switch).
297
+ */
298
+ export declare function scheduleWithdrawnRedrives(rt: GroupRuntime, plan: Pick<TransitionPlan, 'withdrawnSelfUpdates' | 'withdrawnOwnCommits'> | undefined): void;
299
+ /**
300
+ * Schedules {@link driveCommitRedrive} detached, exactly as {@link scheduleSelfUpdateReenqueue} does for a self-update
301
+ * (never throws; a failure before anything was minted leaves the record durable and re-arms the queue drain).
302
+ */
303
+ export declare function scheduleCommitRedrive(rt: GroupRuntime, rootIntentId: string): void;
304
+ /**
305
+ * The drive of the commit re-drive record of root `rootIntentId` (epic marmot-rewound-own-commit-no-signal, DD1/DD11): the
306
+ * record a withdrawal wrote, checked against the current tip and built as ONE fresh commit. Reached from the detached
307
+ * schedule after a transition, a settling sibling's retry, the queue drain and the load-time resume (`resumePending`).
308
+ * The shared rules (stranded, gate, started, leadership) are {@link reenqueueTurn}'s; the election wait and a deferred
309
+ * proposal hold it like any own commit. No timer is involved: the first attempt is made as soon as the group queue allows.
310
+ * Publishing, confirmation and retry are the ordinary pipeline's (`driveIntent`), which spend `attempts` like any commit.
311
+ */
312
+ declare function driveCommitRedrive(rt: GroupRuntime, rootIntentId: string): Promise<ReenqueueDrive>;
313
+ /**
314
+ * A re-enqueued self-update left envelope-less (never published) when the group is fenced, or when its
315
+ * removal settles for good (`removedFromGroup`, no longer revisable) can never be driven. Unlike an
316
+ * `awaiting-sync` intent, `failAwaitingIntents` never looks at a `reenqueuedFrom` record, so each such record is
317
+ * deleted and failed `intentFailed` once, under the ORIGINAL intent id (`reportedIntentIdOf`) a caller actually
318
+ * saw — never the fresh id this particular re-enqueue attempt was given.
319
+ *
320
+ * Crash safety: the removal's settlement deletes them in the SAME transaction that clears the removal marker
321
+ * ({@link takeStrandedSelfUpdateReenqueues}, ingest.ts `settleDueRemoval`), then reports them; a fence's cleanup
322
+ * is repeated by every load of the fenced group (`scheduleAwaitingFenceCleanup`). And any drive of such a record
323
+ * in a group already fenced or finally removed fails it here too (`driveReenqueuedSelfUpdate`), so a record a
324
+ * failed or interrupted cleanup left durable is still reported by the next load or trigger.
325
+ */
326
+ export declare function takeStrandedSelfUpdateReenqueues(tx: GroupStoreTx): Promise<PendingIntentRecord[]>;
327
+ /** Reports records {@link takeStrandedSelfUpdateReenqueues} deleted (after their transaction committed). */
328
+ export declare function reportStrandedSelfUpdateReenqueues(rt: GroupRuntime, stranded: readonly PendingIntentRecord[], cause: Error): Promise<void>;
329
+ export declare function failStrandedSelfUpdateReenqueues(rt: GroupRuntime, cause: Error): Promise<void>;
330
+ /** Refuses an own envelope while the gate is closed: `commit-pending`, reason `awaiting-sync` (retryable). */
331
+ export declare function assertSendGateOpen(rt: GroupRuntime, operation: string): void;
332
+ /**
333
+ * The gate just opened (ingest.ts, the first complete post-load history pass): the awaiting records are driven in
334
+ * the background, in `seq` order (the resume path), the rumor queue drains, and a SelfRemove election at rest that
335
+ * the load deferred is re-run. Never throws.
336
+ */
337
+ export declare function releaseAwaitingSync(rt: GroupRuntime): void;
338
+ /**
339
+ * AC-PIPE-15 with AC-HIST-4: the group is fenced (the marker is already durable). Every awaiting-sync intent —
340
+ * never encrypted — is dropped and fails `fenced` via `intentFailed`, and so is every queued rumor (to its waiting
341
+ * `send()` caller when it has one); nothing is published for them. Records are
342
+ * deleted first, then announced, as for every terminal intent; a load of a fenced group repeats this for records
343
+ * a crash left between the fence write and this cleanup. AC-RACE-1: a re-enqueued self-update left envelope-less
344
+ * is ALSO stranded by a fence (every drive path refuses a fenced group) and is failed the same way, under its
345
+ * original intent id — it is not an `awaiting-sync` record, so it would otherwise go unreported.
346
+ */
347
+ export declare function failAwaitingIntents(rt: GroupRuntime): Promise<void>;
348
+ /** {@link failAwaitingIntents} on the group's queue, for a group loaded already fenced. A failure is dropped (the next load retries). */
349
+ export declare function scheduleAwaitingFenceCleanup(rt: GroupRuntime): void;
350
+ export interface InviteCommit {
351
+ /** The commit's intent id — also the key of its `invites` record. */
352
+ readonly inviteId: string;
353
+ readonly invitees: readonly Pick<Invitee, 'inviteeRef' | 'pubkey' | 'keyPackageEventId'>[];
354
+ }
355
+ /**
356
+ * Whether `account` holds a leaf carrying `leafKey` (hex) — or any key of the set `leafKey` (a device chain, AC-RM-3) —
357
+ * in `state`: the per-state half of `group-runtime.ts`'s `leafOnBranches` walk.
358
+ */
359
+ declare function stateHoldsLeaf(state: ClientState, account: string, leafKey: string | readonly string[]): boolean;
360
+ /**
361
+ * AC-RECHK-1 (amended 2026-10-04): whether `account`'s leaf `leafKey`
362
+ * appears, while the exposed TIP does not hold it, on a state of the group's CANONICAL path retained in
363
+ * `rt.window` whose epoch is at or after `approvalEpoch`. Modelled on `group-runtime.ts`'s `leafOnBranches`, but
364
+ * evaluated synchronously here, over `rt.window`/`rt.exposedState`, from inside the invite group op itself rather
365
+ * than a separate queued read: the same TOCTOU gap the S10 settlement-recheck closed for the rewind pass
366
+ * (`DeviceGroupView.recheck`) would reopen here between a standalone check and this commit's own
367
+ * `recordIntent`/`driveIntent`.
368
+ *
369
+ * Two deliberate narrowings versus a literal "any canonical window state" reading:
370
+ *
371
+ * 1. Canonical-path presence only, never a merely abandoned fork (`leafOnBranches`'s `canonical || abandoned`) —
372
+ * a leaf whose ONLY window presence is on an abandoned fork is exactly the leaf a rewind legitimately
373
+ * withdrew (AC-RECHK-2's reopen exists to re-add it) and must not be refused here.
374
+ * 2. Epoch-bound by `approvalEpoch`, the group's tip epoch recorded when the approval was taken
375
+ * (`ApprovalGroupRecord.approvalEpoch`). Without this, a `devices.forget` Remove — itself a CANONICAL
376
+ * state — that settled strictly BEFORE the device re-enrolled would be seen here too (it is retained inside
377
+ * `REWIND_HORIZON`) and would wrongly refuse the legitimate AC-RECHK-2 redrive forever. Only a canonical
378
+ * departure at or after the approval's own epoch — e.g. an ordinary Remove racing the reopen decision itself,
379
+ * between it and this re-drive — is grounds to refuse. `approvalEpoch === undefined` (a pre-remediation
380
+ * approval record with no recorded epoch) falls back to the whole window, unbounded: the original, strictly
381
+ * conservative behaviour, mirroring `approvedAt ?? 0` elsewhere in this file's enrolment counterpart. The bound
382
+ * may have been advanced by `driveApproval` past a departure the approval supersedes (a forget started before
383
+ * the approval whose Remove landed after it), to the tip epoch the approval's Add was first built on.
384
+ */
385
+ declare function leafHeldOnCanonicalPath(rt: GroupRuntime, account: string, leafKey: string | readonly string[], approvalEpoch?: number): boolean;
386
+ /**
387
+ * `MarmotGroup.invite`'s group-queue part: validates the invitees, applies
388
+ * the pending-proposal policy, and drives ONE commit adding all of them
389
+ * through the durable pipeline. Resolves once the commit is published and
390
+ * confirmed (its Welcomes then belong to the invitations service); rejects
391
+ * like `send` for a commit that is refused or not (yet) published.
392
+ *
393
+ * `reopenedLeafKey`/`approvalEpoch` (S4 AC-RECHK-1): threaded only from `DeviceGroupPort.addDevice` when this Add
394
+ * re-drives a group whose approval record was reopened (never set by the public `MarmotGroup.invite`). See
395
+ * {@link leafHeldOnCanonicalPath}. `origin: 'approval'` (S9, DD10) is likewise threaded
396
+ * only from the enrolment approval (`DeviceGroupPort.addDevice`): it stores the Add as an approval's, which keeps it
397
+ * unmarked (its owner is `reopenApprovalsAfterRewind`).
398
+ */
399
+ export declare function inviteIntent(rt: GroupRuntime, keyPackages: unknown, reopenedLeafKey?: string | readonly string[], approvalEpoch?: number, origin?: 'approval'): Promise<InviteCommit>;
400
+ /**
401
+ * `devices.forget`'s group-queue part: ONE durable commit removing every leaf
402
+ * carrying `leafKey` (the same-account seams let a non-admin leaf commit it),
403
+ * through the same pipeline as every own commit — proposal policy first,
404
+ * refused while an own commit is pending. `absent` when the tree holds no
405
+ * such leaf any more (nothing is recorded). Rejects like `send`.
406
+ */
407
+ export declare function removeLeafIntent(rt: GroupRuntime, leafKey: string | readonly string[]): Promise<'committed' | 'absent'>;
408
+ /**
409
+ * `DeviceGroupPort.rekey`'s group-queue part: ONE durable self-update replacing the local leaf's signature key with
410
+ * `target`. `satisfied` (no commit) when the leaf already carries it, `not-member` when the local leaf was removed;
411
+ * otherwise gated and recorded like every own commit (send gate, one own commit at a time, proposal policy) and driven
412
+ * as a caller (`driveIntent` with a caller): it resolves `committed` once the commit is published and confirmed, and
413
+ * rejects like `send` (`superseded` / `already-rekeyed` / `proof-invalid` as `send-rejected` `details.reason`).
414
+ */
415
+ export declare function rekeyIntent(rt: GroupRuntime, target: string): Promise<'committed' | 'satisfied' | 'not-member'>;
416
+ /** {@link rekeyFollowUp} as its own detached group operation (queued only when the leaf is on a retired key, decided OFF the queue so the ordinary case queues nothing); a failure leaves the durable record (if any) to the next resume. A lost lease ends the runtime like every background retry. Never throws. */
417
+ export declare function scheduleRekeyFollowUp(rt: GroupRuntime): void;
418
+ /**
419
+ * `setAdmins`' group-queue part (and `departAsAdmin`'s demotion): the list is
420
+ * validated against the current tree (AC-ADMIN-1: `invalid-admin-policy`,
421
+ * nothing recorded), then ONE durable commit sets it — refused
422
+ * `commit-pending` while an own commit is pending, like every own commit.
423
+ * The committer must be an admin (the engine's `authorizeCommit` refuses a
424
+ * non-admin's admin-list change: `send-rejected`).
425
+ */
426
+ export declare function setAdminsIntent(rt: GroupRuntime, accounts: unknown, operation?: string): Promise<void>;
427
+ /** The admin-commit pre-check shared by `rename` and `removeMember`: `invalid-options` / `not-admin` unless `selfPubkey` is an active admin, before anything is recorded. */
428
+ export declare function assertLocalAdmin(rt: GroupRuntime, operation: string, selfPubkey: string): void;
429
+ /**
430
+ * `removeMember`'s group-queue part: ONE durable admin commit removing every leaf `account` holds when it is built. Gate order
431
+ * (Design Decision 6): preflight, member, send gate, malformed (`invalid-options`, `malformed-account`), self (`invalid-options`,
432
+ * `self`: leaving is `departAsAdmin()` / `leave()`), not-admin (`invalid-options`, `not-admin`), absent (no leaf: resolves, nothing
433
+ * recorded), own commit pending (`commit-pending`), proposal policy. The client adds no admin-policy update: the engine's
434
+ * coupling splice drops a removed admin's entry in the same commit.
435
+ */
436
+ export declare function removeMemberIntent(rt: GroupRuntime, account: unknown): Promise<void>;
437
+ /**
438
+ * `rename`'s group-queue part: ONE durable admin commit carrying the `marmot.group.profile.v1` update by value.
439
+ * Gate order (Design Decision 6): preflight, member, send gate, malformed (`invalid-options`), not-admin
440
+ * (`invalid-options`, `details.reason: 'not-admin'`, nothing recorded), own commit pending (`commit-pending`), proposal
441
+ * policy. An omitted description is resolved HERE, right before the record is written, from the group view, and stored by
442
+ * value. A concurrent change is never merged: if another admin's profile commit is applied before this commit is built,
443
+ * the stored record is dropped as stale (`send-rejected`) and that profile stands; in a same-epoch race the fork rule
444
+ * keeps one whole profile.
445
+ */
446
+ export declare function renameIntent(rt: GroupRuntime, name: unknown, options: unknown): Promise<void>;
447
+ /** `leave()`'s proposal: the local leaf's SelfRemove, a durable proposal intent (a peer commits it). */
448
+ export declare function proposeSelfRemoveIntent(rt: GroupRuntime): Promise<void>;
449
+ /** The staged proposal set the engine's SelfRemove auto-commit election decided on (epoch and proposal refs). */
450
+ export interface SelfRemoveElection {
451
+ readonly epoch: bigint;
452
+ readonly refs: string;
453
+ }
454
+ export declare function electionOf(state: ClientState): SelfRemoveElection;
455
+ /**
456
+ * The engine's SelfRemove election re-run over a state at rest (S9 Z2): a group
457
+ * loaded with SelfRemoves already staged — the ingest that staged them was
458
+ * persisted, but the process ended before its commit was recorded — would
459
+ * otherwise wait for unrelated traffic to re-elect. Same inputs and rule as
460
+ * the engine's `#maybeAutoCommitSelfRemoves` (its exported `decideAutoCommit`,
461
+ * the leaver predicate the engine was built with; a throwing predicate is
462
+ * fail-closed); `undefined` unless this client is elected.
463
+ */
464
+ export declare function electionAtRest(state: ClientState, isActiveAdminLeaver: ActiveAdminLeaverPredicate): SelfRemoveElection | undefined;
465
+ /**
466
+ * S5 (AC-RACE-2): while the staged proposals are exactly a SelfRemove batch another member is elected to
467
+ * commit (`stagedSelfRemoveElection`'s `committerLeafIndex` differs from this client's own leaf), an own commit
468
+ * built now — whatever intent drives it — would bundle those SelfRemoves into it, pre-empting the elected
469
+ * committer. Waits up to `ctx.selfRemoveElectionWaitMs` (client-clock) from when this exact election ({epoch,
470
+ * refs}) was first observed; `0` never waits. A genuinely different staged set (the election committed, or
471
+ * changed) is never still "the same wait" — {@link releaseSelfRemoveElectionWait} clears it and this starts a
472
+ * fresh one if one still applies.
473
+ */
474
+ declare function awaitingElectedSelfRemove(rt: GroupRuntime): boolean;
475
+ /**
476
+ * Arms (or re-arms) the release timer for `rt.selfRemoveElectionWait`'s CURRENT hold, for whatever time
477
+ * remains of `waitMs` since it started. If the timer fires before the injected clock agrees `waitMs` has
478
+ * actually elapsed, it re-arms itself for the remainder instead of releasing — `scheduleRemovalSettle`'s own
479
+ * re-arm-on-early-fire pattern (ingest.ts), applied here to the election wait's hold.
480
+ */
481
+ /** The largest delay a platform timer honours (2^31 - 1 ms); `setTimeout` fires a longer one after 1 ms. */
482
+ export declare const MAX_TIMER_DELAY_MS = 2147483647;
483
+ declare function armElectionWaitTimer(rt: GroupRuntime, waitMs: number): void;
484
+ /** Cancels any pending {@link awaitingElectedSelfRemove} timer without blocking a fresh evaluation — a genuine staged-proposal change (ingest.ts). */
485
+ export declare function releaseSelfRemoveElectionWait(rt: GroupRuntime): void;
486
+ /**
487
+ * AC-ADMIN-9: the engine elected this client to commit the staged SelfRemoves
488
+ * (`autoCommit`, with the admin-leaver predicate `marmot` injects). Ingest
489
+ * rolls the engine's own staged commit back — it is not durable — and this
490
+ * schedules, on the group's queue after the ingest, ONE durable commit of the
491
+ * same staged set through the pipeline, provided that set is still exactly
492
+ * what the engine decided on. A failure before anything was recorded is
493
+ * retried on the capped backoff; afterwards the record retries itself.
494
+ */
495
+ export declare function scheduleSelfRemoveCommit(rt: GroupRuntime, election: SelfRemoveElection, failures?: number): void;
496
+ /**
497
+ * S15: evaluates the deferral deadlines of the group's staged proposals
498
+ * without asking `onProposal` (an expired one is rejected, see
499
+ * {@link decideStagedProposals}); when one expired, the queue drains — the
500
+ * admin's commit that releases the queued rumors is no longer refused.
501
+ * Runs inside a group op.
502
+ */
503
+ export declare function expireDeferredProposals(rt: GroupRuntime): Promise<void>;
504
+ /**
505
+ * Schedules {@link expireDeferredProposals} on the group's queue (group load,
506
+ * inbox pass). A failure is dropped: the deadline is durable, and the next
507
+ * evaluation point evaluates it again. Never throws.
508
+ */
509
+ export declare function scheduleProposalDeadlineCheck(rt: GroupRuntime): void;
510
+ /**
511
+ * The policy in front of an own commit: a deferred proposal refuses it (`commit-pending`, reason
512
+ * `proposal-deferred`); S5 (AC-RACE-2): a staged SelfRemove-only batch another member is elected to commit
513
+ * refuses it too (reason `selfremove-election-wait`), checked first — never asking `onProposal` about a
514
+ * foreign proposal while the commit is going to be refused anyway.
515
+ */
516
+ export declare function applyProposalPolicy(rt: GroupRuntime, operation: string): Promise<void>;
517
+ /**
518
+ * Marks `refs` invalid under application policy: removed from the staged set, durably, before any commit is built.
519
+ * `alongside` runs in the same transaction (S15: the deferral records of the drop).
520
+ */
521
+ export declare function dropRejectedProposals(rt: GroupRuntime, refs: readonly string[], alongside?: (tx: GroupStoreTx) => Promise<void>): Promise<void>;
522
+ /**
523
+ * Publishes queued rumors, head first, as long as nothing is staged and the
524
+ * epoch is past the head's barrier; builds the commit that clears the way
525
+ * itself when the local account is an authorised committer and no proposal is
526
+ * deferred. Runs inside a group op. `commitError` is the failure of the
527
+ * commit it tried to make, if any (the queue then stays as it is).
528
+ */
529
+ export declare function advanceQueue(rt: GroupRuntime): Promise<{
530
+ readonly commitError?: unknown;
531
+ }>;
532
+ /**
533
+ * Runs {@link resumePending} on the group's queue in the background (group
534
+ * load). A whole-run failure — a transient store read — is retried on the
535
+ * capped backoff until it succeeds, the runtime or client is disposed, or the
536
+ * stores lose their lease (the next holder resumes the durable records). A
537
+ * throwing relay probe no longer fails the run: it goes to the record's
538
+ * bounded publish retry ({@link settlePublishedRecord}).
539
+ */
540
+ export declare function resumePendingInBackground(rt: GroupRuntime, failures?: number): void;
541
+ /**
542
+ * `unpublishedOnly`: resume only records nothing was published for yet
543
+ * (envelope-less) and blocked confirmations — what a queue drain needs
544
+ * before it may build a commit — and leave records awaiting a publish retry
545
+ * to their own backoff timer (a busy group must not spend their
546
+ * `maxPublishAttempts` faster).
547
+ */
548
+ /**
549
+ * Returns `true` when any record was left behind specifically because `awaitingElectedSelfRemove` (AC-RACE-2),
550
+ * a deferred foreign proposal (AC-INVITE-4) or a revisable removal (a re-enqueued self-update) held it back — never for an ordinary "not open yet" / "waiting
551
+ * on a dependency" skip. `advanceQueue` uses this to keep `queuedHint` from masking that record's own next
552
+ * chance to be picked back up (`queue-drain-queuedHint-gate`; `driveReenqueuedSelfUpdate` reports its own holds).
553
+ */
554
+ export declare function resumePending(rt: GroupRuntime, opts?: {
555
+ readonly unpublishedOnly?: boolean;
556
+ }): Promise<boolean>;
557
+ /**
558
+ * Internal (tests only), a mutation-gate test seam: references to the private pipeline helpers, unchanged, so
559
+ * a test can drive them on a real runtime (see InternalClientOptions.exposeRuntimesForTest). Not re-exported
560
+ * from the package entry points.
561
+ */
562
+ export declare const __internal: Readonly<{
563
+ driveReenqueuedSelfUpdate: typeof driveReenqueuedSelfUpdate;
564
+ driveCommitRedrive: typeof driveCommitRedrive;
565
+ armReenqueueRetry: typeof armReenqueueRetry;
566
+ driveSelfUpdateOverStagedAdds: typeof driveSelfUpdateOverStagedAdds;
567
+ linkStagedAddsCommit: typeof linkStagedAddsCommit;
568
+ terminalFail: typeof terminalFail;
569
+ resolveDependency: typeof resolveDependency;
570
+ followDependents: typeof followDependents;
571
+ retryDeferredSelfUpdateReenqueues: typeof retryDeferredSelfUpdateReenqueues;
572
+ reparentReenqueued: typeof reparentReenqueued;
573
+ remintStaleReenqueue: typeof remintStaleReenqueue;
574
+ resumePending: typeof resumePending;
575
+ awaitingElectedSelfRemove: typeof awaitingElectedSelfRemove;
576
+ armElectionWaitTimer: typeof armElectionWaitTimer;
577
+ leafHeldOnCanonicalPath: typeof leafHeldOnCanonicalPath;
578
+ confirmRecord: typeof confirmRecord;
579
+ removeProposalsFor: typeof removeProposalsFor;
580
+ stateHoldsLeaf: typeof stateHoldsLeaf;
581
+ ownCommitMarkerOf: typeof ownCommitMarkerOf;
582
+ }>;
583
+ export {};