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