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