@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,158 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The terminal-notification outbox (epic marmot-rewound-own-commit-no-signal, S11; spec DD7 Delivery, DD11 Durability,
|
|
3
|
+
* AC-COMP-10). `own-change-reapplied` and `own-change-lost` are delivered AT LEAST ONCE: the terminal is written here in
|
|
4
|
+
* the SAME transaction that makes its fact durable (a record update or delete, a mint, a confirm, a restore), dispatched
|
|
5
|
+
* after that transaction commits, and removed in a follow-up transaction. A crash or a client dispose in between leaves
|
|
6
|
+
* the entry; the next load (or the next listener of the group) announces it again with an IDENTICAL payload.
|
|
7
|
+
* `own-change-withdrawn` stays at most once and has no entry here.
|
|
8
|
+
*
|
|
9
|
+
* Why an extension record and not a flag on the re-drive record: the paths that decide a terminal DELETE the re-drive
|
|
10
|
+
* record (no survivor, budget spent, publish refused, stranded, retired by a restore), so nothing durable would remain
|
|
11
|
+
* to carry the verdict. A separate namespace also keeps the verdict out of every reader of `pendingIntents`: it can never
|
|
12
|
+
* be driven, published, counted as an own commit pending, settled as stale, or matched by a restore or by
|
|
13
|
+
* `cancelRestoredReenqueues` (the same reason `proposalExpired`'s marker is an extension, not a flag on the proposal).
|
|
14
|
+
*
|
|
15
|
+
* Dedup key (what an application deduplicates by): `(groupId, intentId, change, type)`, plus `commitDigest` for a
|
|
16
|
+
* `reapplied` (a change reapplied by two different commits is two different facts). It is also the storage key
|
|
17
|
+
* (`groupId` is the store's own scope), so writing the same terminal twice is one entry, and growth is bounded by the
|
|
18
|
+
* number of distinct terminals not yet delivered. The only repeats an application may see are the identical redelivery
|
|
19
|
+
* after an injected crash or dispose, and a `reapplied` of the same change by the DD14 restore (a different commit, or
|
|
20
|
+
* the same one: then the same dedup key).
|
|
21
|
+
*
|
|
22
|
+
* Retention: the namespace is its own, so neither the terminal-ledger prune nor the marker prune touches it. Entries
|
|
23
|
+
* are removed only once delivered to at least one listener, or, for a row that does not decode, when the drain evicts it
|
|
24
|
+
* and reports it once as `groupStateFailed` (`store-failed`, `details.malformed`). As a last bound on a group nobody listens
|
|
25
|
+
* to, the OUTBOX_CAP most recent entries are kept (oldest evicted on write).
|
|
26
|
+
*/
|
|
27
|
+
import { OWN_CHANGE_LOST_REASONS } from '../history/index.js';
|
|
28
|
+
import { MarmotError } from '../shared/index.js';
|
|
29
|
+
import { decodeOwnChange } from './group-records.js';
|
|
30
|
+
/** The group extension holding one entry per undelivered terminal, keyed by {@link terminalKey}. */
|
|
31
|
+
export const OWN_CHANGE_OUTBOX_EXTENSION = 'marmot.own-change-outbox';
|
|
32
|
+
/** The most entries kept; the oldest is evicted when a write would exceed it (a group nobody listens to). */
|
|
33
|
+
export const OUTBOX_CAP = 512;
|
|
34
|
+
export function isTerminalNotification(n) {
|
|
35
|
+
return n.type === 'own-change-reapplied' || n.type === 'own-change-lost';
|
|
36
|
+
}
|
|
37
|
+
function changeKey(c) {
|
|
38
|
+
switch (c.type) {
|
|
39
|
+
case 'member-removed':
|
|
40
|
+
return `member-removed:${c.account}`;
|
|
41
|
+
case 'member-added':
|
|
42
|
+
return `member-added:${c.account}:${c.leafKey}`;
|
|
43
|
+
case 'admin':
|
|
44
|
+
return `admin:${c.account}:${String(c.admin)}`;
|
|
45
|
+
case 'component':
|
|
46
|
+
return `component:${String(c.componentId)}`;
|
|
47
|
+
case 'admission-removed':
|
|
48
|
+
return `admission-removed:${c.candidateId}`;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
/** The dedup key of a terminal: `(intentId, change, type)` plus `commitDigest` for a reapplied (`groupId` is the store's scope). */
|
|
52
|
+
export function terminalKey(n) {
|
|
53
|
+
return n.type === 'own-change-reapplied' ? `${n.type}|${n.intentId}|${changeKey(n.change)}|${n.commitDigest}` : `${n.type}|${n.intentId}|${changeKey(n.change)}`;
|
|
54
|
+
}
|
|
55
|
+
function malformed(key, detail) {
|
|
56
|
+
return new MarmotError('store-failed', `${OWN_CHANGE_OUTBOX_EXTENSION}/${key}: malformed record (${detail})`, { details: { key, malformed: true } });
|
|
57
|
+
}
|
|
58
|
+
function encode(seq, n) {
|
|
59
|
+
return {
|
|
60
|
+
v: 1,
|
|
61
|
+
seq,
|
|
62
|
+
n: n.type === 'own-change-reapplied'
|
|
63
|
+
? { type: n.type, intentId: n.intentId, commitDigest: n.commitDigest, change: { ...n.change } }
|
|
64
|
+
: { type: n.type, intentId: n.intentId, reason: n.reason, change: { ...n.change } },
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
function decode(key, raw) {
|
|
68
|
+
const fail = (detail) => malformed(key, detail);
|
|
69
|
+
const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
|
|
70
|
+
if (!isObj(raw) || raw.v !== 1 || typeof raw.seq !== 'number' || !Number.isSafeInteger(raw.seq) || !isObj(raw.n))
|
|
71
|
+
throw fail('record invalid');
|
|
72
|
+
const n = raw.n;
|
|
73
|
+
if (typeof n.intentId !== 'string')
|
|
74
|
+
throw fail('intentId missing');
|
|
75
|
+
const change = decodeOwnChange(n.change, 'change', fail);
|
|
76
|
+
if (n.type === 'own-change-reapplied') {
|
|
77
|
+
if (typeof n.commitDigest !== 'string')
|
|
78
|
+
throw fail('commitDigest missing');
|
|
79
|
+
return { seq: raw.seq, notification: { type: 'own-change-reapplied', intentId: n.intentId, commitDigest: n.commitDigest, change } };
|
|
80
|
+
}
|
|
81
|
+
if (n.type === 'own-change-lost') {
|
|
82
|
+
if (!OWN_CHANGE_LOST_REASONS.includes(n.reason))
|
|
83
|
+
throw fail('reason invalid');
|
|
84
|
+
return { seq: raw.seq, notification: { type: 'own-change-lost', intentId: n.intentId, change, reason: n.reason } };
|
|
85
|
+
}
|
|
86
|
+
throw fail('type unknown');
|
|
87
|
+
}
|
|
88
|
+
/** Every entry, in delivery order. `view` is the group's {@link OWN_CHANGE_OUTBOX_EXTENSION} namespace. */
|
|
89
|
+
export async function readOutbox(view) {
|
|
90
|
+
const entries = [];
|
|
91
|
+
for (const key of await view.keys()) {
|
|
92
|
+
const raw = await view.get(key);
|
|
93
|
+
if (raw !== undefined)
|
|
94
|
+
entries.push({ key, ...decode(key, raw) });
|
|
95
|
+
}
|
|
96
|
+
return entries.sort((a, b) => a.seq - b.seq || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Like {@link readOutbox}, row by row: the rows that decode, in delivery order, and the ones that do not (a poisoned row, a future
|
|
100
|
+
* version) with their `store-failed` error, so one bad row neither blocks the good ones nor goes unnoticed.
|
|
101
|
+
*/
|
|
102
|
+
export async function readOutboxLenient(view) {
|
|
103
|
+
const entries = [];
|
|
104
|
+
const bad = [];
|
|
105
|
+
for (const key of await view.keys()) {
|
|
106
|
+
const raw = await view.get(key);
|
|
107
|
+
if (raw === undefined)
|
|
108
|
+
continue;
|
|
109
|
+
try {
|
|
110
|
+
entries.push({ key, ...decode(key, raw) });
|
|
111
|
+
}
|
|
112
|
+
catch (error) {
|
|
113
|
+
bad.push({ key, error: error });
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
entries.sort((a, b) => a.seq - b.seq || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
|
|
117
|
+
return { entries, bad };
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Writes `notifications` (in order) into the outbox, in the caller's transaction. A terminal already stored under its
|
|
121
|
+
* dedup key is rewritten at the end of the order (same payload by construction for a repeat of the same fact).
|
|
122
|
+
* Evicts the oldest entries beyond {@link OUTBOX_CAP}.
|
|
123
|
+
*/
|
|
124
|
+
export async function enqueueTerminals(view, notifications) {
|
|
125
|
+
if (notifications.length === 0)
|
|
126
|
+
return;
|
|
127
|
+
// Lenient on the write path: an entry that does not decode (a poisoned row, a future version) must not fail the deciding
|
|
128
|
+
// transaction -- and with it every transition of the group. Its `seq` is read if present; the strict read stays on announce.
|
|
129
|
+
const existing = [];
|
|
130
|
+
for (const key of await view.keys()) {
|
|
131
|
+
const raw = await view.get(key);
|
|
132
|
+
const seq = typeof raw === 'object' && raw !== null && !Array.isArray(raw) && typeof raw.seq === 'number' ? raw.seq : 0;
|
|
133
|
+
existing.push({ key, seq });
|
|
134
|
+
}
|
|
135
|
+
existing.sort((a, b) => a.seq - b.seq);
|
|
136
|
+
let seq = existing.reduce((max, e) => Math.max(max, e.seq), 0);
|
|
137
|
+
const written = new Set();
|
|
138
|
+
for (const n of notifications) {
|
|
139
|
+
seq += 1;
|
|
140
|
+
const key = terminalKey(n);
|
|
141
|
+
await view.put(key, encode(seq, n));
|
|
142
|
+
written.add(key);
|
|
143
|
+
}
|
|
144
|
+
const overflow = existing.filter((e) => !written.has(e.key)).length + written.size - OUTBOX_CAP;
|
|
145
|
+
if (overflow > 0)
|
|
146
|
+
for (const e of existing.filter((x) => !written.has(x.key)).slice(0, overflow))
|
|
147
|
+
await view.delete(e.key);
|
|
148
|
+
}
|
|
149
|
+
/** Removes the entries just delivered; one rewritten since (a different `seq`) is a newer fact and stays. */
|
|
150
|
+
export async function dropDelivered(view, delivered) {
|
|
151
|
+
for (const e of delivered) {
|
|
152
|
+
const raw = await view.get(e.key);
|
|
153
|
+
if (raw === undefined)
|
|
154
|
+
continue;
|
|
155
|
+
if (decode(e.key, raw).seq === e.seq)
|
|
156
|
+
await view.delete(e.key);
|
|
157
|
+
}
|
|
158
|
+
}
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
import type { NostrEvent } from '@941design/nostr-events/event';
|
|
2
|
+
import { type RetainedWindow } from '../history/index.js';
|
|
3
|
+
import type { GroupStore, KeyValueView } from '../storage/index.js';
|
|
4
|
+
import type { GroupRuntime } from './group-runtime.js';
|
|
5
|
+
export declare const PENDING_COMMIT_EXTENSION = "marmot.restorePendingCommit";
|
|
6
|
+
/** What the adoption of a pending-tagged snapshot leaves until C is seen or the first sync's resolution ran. */
|
|
7
|
+
export interface PendingCommitMarker {
|
|
8
|
+
/** `commitDigest` (hex) of C. */
|
|
9
|
+
readonly digest: string;
|
|
10
|
+
/** Confirmation tag (hex) of P, the state C was made from. */
|
|
11
|
+
readonly parentTag: string;
|
|
12
|
+
/** Confirmation tag (hex) of S_C, the adopted tip: the resolution step is gated on the persisted tip being this. */
|
|
13
|
+
readonly tipTag: string;
|
|
14
|
+
}
|
|
15
|
+
export declare function writePendingCommit(view: KeyValueView, marker: PendingCommitMarker): Promise<void>;
|
|
16
|
+
export declare function clearPendingCommit(view: KeyValueView): Promise<void>;
|
|
17
|
+
/**
|
|
18
|
+
* The stored marker, `undefined` when absent. A value of the wrong shape is NOT read as absent: "absent" would keep
|
|
19
|
+
* the adopted tip, the very dead-branch outcome the marker exists to rule out. It fails the read (the group does not
|
|
20
|
+
* load) like any other malformed record of this store.
|
|
21
|
+
*/
|
|
22
|
+
export declare function readPendingCommit(view: KeyValueView): Promise<PendingCommitMarker | undefined>;
|
|
23
|
+
export declare const PENDING_LEAF_EXTENSION = "marmot.pendingLeaf";
|
|
24
|
+
/** The parked node S_C: what {@link reinstatePendingLeaf} adds back to the window as an ordinary fork node. */
|
|
25
|
+
export interface PendingLeaf {
|
|
26
|
+
/** `commitDigest` (hex) of C. */
|
|
27
|
+
readonly digest: string;
|
|
28
|
+
/** Confirmation tag (hex) of P. */
|
|
29
|
+
readonly parentTag: string;
|
|
30
|
+
/** Confirmation tag (hex) of S_C. */
|
|
31
|
+
readonly tag: string;
|
|
32
|
+
readonly epoch: number;
|
|
33
|
+
/** Serialized S_C. */
|
|
34
|
+
readonly state: Uint8Array;
|
|
35
|
+
/** C as the window stores it (an own-commit record: the MLS wire bytes and the convergence stamp). */
|
|
36
|
+
readonly commit: Uint8Array;
|
|
37
|
+
}
|
|
38
|
+
export declare function writePendingLeaf(view: KeyValueView, leaf: PendingLeaf): Promise<void>;
|
|
39
|
+
export declare function clearPendingLeaf(view: KeyValueView): Promise<void>;
|
|
40
|
+
/**
|
|
41
|
+
* The stored side record. A value of the wrong shape reads as absent: the worst outcome is today's rules for C (an
|
|
42
|
+
* opaque candidate, fenced only if it could win), which is the documented fallback when the node cannot be reinstated.
|
|
43
|
+
*/
|
|
44
|
+
export declare function readPendingLeaf(view: KeyValueView): Promise<PendingLeaf | undefined>;
|
|
45
|
+
/** The two records of a group, as a load reads them (each independently absent). */
|
|
46
|
+
export declare function readPendingRestore(store: GroupStore): Promise<{
|
|
47
|
+
readonly pendingCommit?: PendingCommitMarker;
|
|
48
|
+
readonly pendingLeaf?: PendingLeaf;
|
|
49
|
+
}>;
|
|
50
|
+
/** What an envelope turned out to be to a group that waits for C. */
|
|
51
|
+
export type Sighting =
|
|
52
|
+
/** It carries C (its commit digest is C's). */
|
|
53
|
+
'commit'
|
|
54
|
+
/** It opens under S_C's epoch key: some member holds S_C and wrote at its epoch, which proves C is public. */
|
|
55
|
+
| 'public'
|
|
56
|
+
/** It carries the commit of an own-leaf fork node of the window under another event id (a re-encrypted copy). */
|
|
57
|
+
| 'copy';
|
|
58
|
+
export interface PendingWatch {
|
|
59
|
+
/** Opens `event` under every state worth trying; `undefined` when it is none of the above. Never throws. */
|
|
60
|
+
sight(event: NostrEvent): Promise<Sighting | undefined>;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* What the runtime watches incoming envelopes for, or `undefined` when nothing (the common case: no decryption, no cost):
|
|
64
|
+
* - the awaited commit C, opened under P's epoch key (marker and parked node alike): bytes only, never an event id;
|
|
65
|
+
* - while the adoption's marker is present and the tip is still S_C, ANY envelope that opens under S_C's epoch key:
|
|
66
|
+
* only a holder of S_C can wrap at that epoch, so C is public (a peer's message, proposal or commit built on it);
|
|
67
|
+
* - an own-leaf fork node's commit under another event id (a re-encrypted copy), which the engine would read as an
|
|
68
|
+
* unopenable own commit; the id-keyed ledger cannot see it.
|
|
69
|
+
*/
|
|
70
|
+
export declare function pendingWatch(rt: GroupRuntime): PendingWatch | undefined;
|
|
71
|
+
/** Ledgers `events` (re-encrypted copies of an own commit the window holds as a fork node) `own`: a redelivery is then a duplicate. */
|
|
72
|
+
export declare function ledgerOwnCopies(rt: GroupRuntime, events: readonly NostrEvent[]): Promise<void>;
|
|
73
|
+
/**
|
|
74
|
+
* The resolution step of Design Decision 7. Runs once the restore's first sync is over, inside the group's queue, on
|
|
75
|
+
* the PERSISTED tip (the stored `clientState`), and handles only a marker that is still present:
|
|
76
|
+
*
|
|
77
|
+
* 1. no marker: nothing (a second run, or an ingest transaction recognised C and cleared it);
|
|
78
|
+
* 2. tip is not S_C (a commit was applied on top of S_C, which counts as C present, or the sync rewound onto a
|
|
79
|
+
* competing branch, or advanced): the marker is cleared; when S_C is left in the window as a childless fork leaf
|
|
80
|
+
* (C unseen: no peer holds it) it is parked in the side record instead ({@link parkForkLeaf});
|
|
81
|
+
* 3. tip is S_C and the marker survived the sync, so no envelope with C's digest was delivered and none opened under
|
|
82
|
+
* S_C's epoch: in ONE transaction the rewound `clientState` (P), the rewound `rewindTree` (S_C and anything hanging
|
|
83
|
+
* off it removed, every other node kept — the structural replay), the side record, the marker's clearing AND the
|
|
84
|
+
* transition's own bookkeeping ({@link recordTransition}: whatever was delivered under S_C is withdrawn, the
|
|
85
|
+
* settlement recheck is marked) are written; the engine is then rebuilt over P with the window and the held opaque
|
|
86
|
+
* record handed back, and the transition is announced. No ingest cursor is touched. It never rewinds under an
|
|
87
|
+
* intent record that is not `awaiting-sync`: a commit minted on S_C would be orphaned (fail closed).
|
|
88
|
+
*
|
|
89
|
+
* Returns whether the group was rewound (the caller then runs the tree-fed pass over the rebuilt tree, which weighs a
|
|
90
|
+
* competitor of S_C that the sync already ledgered, from P).
|
|
91
|
+
*/
|
|
92
|
+
export declare function resolvePendingCommit(rt: GroupRuntime): Promise<boolean>;
|
|
93
|
+
/** Whether `leaf`'s node can still be added to `window`: its parent is the tip, or a node with its serialized state. */
|
|
94
|
+
export declare function reinstatable(window: RetainedWindow, leaf: PendingLeaf): boolean;
|
|
95
|
+
/**
|
|
96
|
+
* Forgets the parked node (reinstatement is impossible: P fell below the horizon or out of the window). C is then
|
|
97
|
+
* processed under today's rules, as an opaque candidate that fences only when it could win.
|
|
98
|
+
*/
|
|
99
|
+
export declare function dropPendingLeaf(rt: GroupRuntime): Promise<void>;
|
|
100
|
+
/**
|
|
101
|
+
* C was delivered after the group landed at P: S_C becomes an ordinary own-leaf fork node. `withForkNode` returns
|
|
102
|
+
* `undefined` for a parent without a snapshot, and the stored window's tip never carries one, so while P is the tip it
|
|
103
|
+
* first receives its snapshot from the stored `clientState` (the way `extendWindow` snapshots a tip it extends); for a
|
|
104
|
+
* non-tip P (the restored self-update advanced the tip) `withForkNode` is called directly. The node is added to the
|
|
105
|
+
* window and the parked record cleared in ONE transaction, then the engine is rebuilt over the stored state with the new
|
|
106
|
+
* window, and a history resync is requested so an undecryptable descendant of S_C that the lost pool held is re-offered.
|
|
107
|
+
* A fork node, not an adopted tip: the credited selection decides it against a competing F or the restored self-update.
|
|
108
|
+
*
|
|
109
|
+
* `carriers` are the delivered envelopes that carry C: each is ledgered `own` in the same transaction, exactly as a stale own
|
|
110
|
+
* commit retained as a fork node is (pipeline.ts `settlePublishedRecord`). The engine cannot process its own commit — it
|
|
111
|
+
* holds no path secrets for it — and recognises C only as the tip's edge, not as a fork node's; a redelivery of the envelope
|
|
112
|
+
* must therefore be a ledger duplicate, never an engine feed (which would read as an unopenable own-leaf commit and fence).
|
|
113
|
+
*
|
|
114
|
+
* Returns whether the node was reinstated; `false` when it could not be (the record is then dropped).
|
|
115
|
+
*/
|
|
116
|
+
export declare function reinstatePendingLeaf(rt: GroupRuntime, carriers: readonly NostrEvent[]): Promise<boolean>;
|
|
@@ -0,0 +1,378 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Restore resolution of a pending-tagged snapshot (epic `marmot-leaf-backup-pre-publish` S2; spec Design Decisions 7
|
|
3
|
+
* and 7a; ADR-016 D6 "Pending-backup fence rule").
|
|
4
|
+
*
|
|
5
|
+
* A pending-tagged `GroupSnapshot` (client/group-snapshot.ts) holds the result S_C of an own commit C that no relay is
|
|
6
|
+
* known to hold yet, with C's parent P as the window node under the tip. `groups.restore` adopts it at S_C exactly as
|
|
7
|
+
* it adopts any snapshot, and this module keeps the adoption honest about what it does not know:
|
|
8
|
+
*
|
|
9
|
+
* - {@link PendingCommitMarker} (`marmot.restorePendingCommit`): written in the adoption transaction. It is the
|
|
10
|
+
* "C has not been seen" fact. The ingest transaction that recognises C by its digest clears it beside its cursor
|
|
11
|
+
* and ledger write (client/ingest.ts); so does the resolution step ({@link resolvePendingCommit}) when the tip is
|
|
12
|
+
* no longer S_C. What is left of it once the first sync is over means no relay delivered C: the group is rewound to
|
|
13
|
+
* P in ONE transaction and the node is parked in {@link PendingLeaf} instead.
|
|
14
|
+
* - {@link PendingLeaf} (`marmot.pendingLeaf`): the rewound-away S_C, kept OUTSIDE `rewindTree` and the engine's
|
|
15
|
+
* history tree. The engine's tree-fed passes take every tree tip as a candidate, so a node left in the tree as a fork
|
|
16
|
+
* leaf would compete at depth one over the restored tip and could win a tie no peer holds (Decision 7a). Until a
|
|
17
|
+
* relay delivers C the node therefore carries no credit, no depth, no undecryptable-set member and no equivocation
|
|
18
|
+
* evidence, because the engine has never heard of it. Ingest checks every incoming envelope's digest against the
|
|
19
|
+
* record BEFORE the engine is fed ({@link pendingWatch}); on a match {@link reinstatePendingLeaf} makes
|
|
20
|
+
* the node an ordinary own-leaf fork node and rebuilds the engine, and C then goes through the engine as any commit.
|
|
21
|
+
*
|
|
22
|
+
* Everything here depends on bytes only: the digest of the commit an envelope carries, never an event id, a
|
|
23
|
+
* `created_at` or an arrival order (ADR-016 determinism).
|
|
24
|
+
*/
|
|
25
|
+
import { commitDigest, decryptGroupMessages, deserializeClientState, serializeClientState } from '@941design/marmot-engine/core';
|
|
26
|
+
import { decodeOwnCommitRecord } from '@941design/marmot-engine/engine';
|
|
27
|
+
import { encode, mlsMessageEncoder } from '@941design/marmot-engine/mls';
|
|
28
|
+
import { hexOf } from '../history/hex.js';
|
|
29
|
+
import { canonicalPath, readWindow, rewoundToParent, tagOf, withForkNode, writeWindow } from '../history/index.js';
|
|
30
|
+
import { MarmotError } from '../shared/index.js';
|
|
31
|
+
import { deliverTransition, planTransition, recordTransition } from './group-history.js';
|
|
32
|
+
import { listPendingIntentRecords, readGroupState, writeGroupState, writeTerminalLedgerEntry } from './group-records.js';
|
|
33
|
+
// ---------------------------------------------------------------------------
|
|
34
|
+
// The marker: "the adopted tip's commit has not been seen" (group extension `marmot.restorePendingCommit`)
|
|
35
|
+
// ---------------------------------------------------------------------------
|
|
36
|
+
export const PENDING_COMMIT_EXTENSION = 'marmot.restorePendingCommit';
|
|
37
|
+
const MARKER_KEY = 'current';
|
|
38
|
+
export async function writePendingCommit(view, marker) {
|
|
39
|
+
await view.put(MARKER_KEY, { v: 1, digest: marker.digest, parentTag: marker.parentTag, tipTag: marker.tipTag });
|
|
40
|
+
}
|
|
41
|
+
export async function clearPendingCommit(view) {
|
|
42
|
+
await view.delete(MARKER_KEY);
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* The stored marker, `undefined` when absent. A value of the wrong shape is NOT read as absent: "absent" would keep
|
|
46
|
+
* the adopted tip, the very dead-branch outcome the marker exists to rule out. It fails the read (the group does not
|
|
47
|
+
* load) like any other malformed record of this store.
|
|
48
|
+
*/
|
|
49
|
+
export async function readPendingCommit(view) {
|
|
50
|
+
const raw = await view.get(MARKER_KEY);
|
|
51
|
+
if (raw === undefined)
|
|
52
|
+
return undefined;
|
|
53
|
+
const r = typeof raw === 'object' && raw !== null && !Array.isArray(raw) && !(raw instanceof Uint8Array) ? raw : undefined;
|
|
54
|
+
if (r === undefined || typeof r['digest'] !== 'string' || typeof r['parentTag'] !== 'string' || typeof r['tipTag'] !== 'string') {
|
|
55
|
+
throw new MarmotError('store-failed', 'restorePendingCommit: stored marker is malformed', { details: { key: MARKER_KEY, malformed: true } });
|
|
56
|
+
}
|
|
57
|
+
return { digest: r['digest'], parentTag: r['parentTag'], tipTag: r['tipTag'] };
|
|
58
|
+
}
|
|
59
|
+
// ---------------------------------------------------------------------------
|
|
60
|
+
// The side record: the rewound-away pending node (group extension `marmot.pendingLeaf`)
|
|
61
|
+
// ---------------------------------------------------------------------------
|
|
62
|
+
export const PENDING_LEAF_EXTENSION = 'marmot.pendingLeaf';
|
|
63
|
+
const LEAF_KEY = 'current';
|
|
64
|
+
export async function writePendingLeaf(view, leaf) {
|
|
65
|
+
await view.put(LEAF_KEY, { v: 1, d: leaf.digest, p: leaf.parentTag, t: leaf.tag, e: leaf.epoch, s: leaf.state, c: leaf.commit });
|
|
66
|
+
}
|
|
67
|
+
export async function clearPendingLeaf(view) {
|
|
68
|
+
await view.delete(LEAF_KEY);
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* The stored side record. A value of the wrong shape reads as absent: the worst outcome is today's rules for C (an
|
|
72
|
+
* opaque candidate, fenced only if it could win), which is the documented fallback when the node cannot be reinstated.
|
|
73
|
+
*/
|
|
74
|
+
export async function readPendingLeaf(view) {
|
|
75
|
+
const raw = await view.get(LEAF_KEY);
|
|
76
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || raw instanceof Uint8Array)
|
|
77
|
+
return undefined;
|
|
78
|
+
const r = raw;
|
|
79
|
+
const { d, p, t, e, s, c } = r;
|
|
80
|
+
if (typeof d !== 'string' || typeof p !== 'string' || typeof t !== 'string' || typeof e !== 'number' || !(s instanceof Uint8Array) || !(c instanceof Uint8Array))
|
|
81
|
+
return undefined;
|
|
82
|
+
return { digest: d, parentTag: p, tag: t, epoch: e, state: s, commit: c };
|
|
83
|
+
}
|
|
84
|
+
/** The two records of a group, as a load reads them (each independently absent). */
|
|
85
|
+
export async function readPendingRestore(store) {
|
|
86
|
+
const pendingCommit = await readPendingCommit(store.extension(PENDING_COMMIT_EXTENSION));
|
|
87
|
+
const pendingLeaf = await readPendingLeaf(store.extension(PENDING_LEAF_EXTENSION));
|
|
88
|
+
return { ...(pendingCommit === undefined ? {} : { pendingCommit }), ...(pendingLeaf === undefined ? {} : { pendingLeaf }) };
|
|
89
|
+
}
|
|
90
|
+
// ---------------------------------------------------------------------------
|
|
91
|
+
// Recognising C
|
|
92
|
+
// ---------------------------------------------------------------------------
|
|
93
|
+
/** Decoded parent states, by the snapshot bytes they came from (the window keeps those bytes between writes). */
|
|
94
|
+
const parentStates = new WeakMap();
|
|
95
|
+
/**
|
|
96
|
+
* P as a decryption key source: the engine's state while P is the tip, else P's node in the window. Only the state's
|
|
97
|
+
* exporter secret is read (the epoch key every kind-445 envelope of epoch(P) is wrapped under), never mutated.
|
|
98
|
+
*/
|
|
99
|
+
function parentStateOf(rt, parentTag) {
|
|
100
|
+
if (tagOf(rt.engine.state) === parentTag)
|
|
101
|
+
return rt.engine.state;
|
|
102
|
+
const snapshot = rt.window.nodes.get(parentTag)?.snapshot;
|
|
103
|
+
if (snapshot === undefined)
|
|
104
|
+
return undefined;
|
|
105
|
+
let state = parentStates.get(snapshot);
|
|
106
|
+
if (state === undefined)
|
|
107
|
+
parentStates.set(snapshot, (state = deserializeClientState(snapshot)));
|
|
108
|
+
return state;
|
|
109
|
+
}
|
|
110
|
+
/** Fork nodes of `rt.window` that hold an own-leaf commit off the canonical path (not the tip's ancestors). */
|
|
111
|
+
function ownForkEdges(rt) {
|
|
112
|
+
const window = rt.window;
|
|
113
|
+
if (window.nodes.size < 2)
|
|
114
|
+
return [];
|
|
115
|
+
const canonical = new Set(canonicalPath(window).map((n) => n.tag));
|
|
116
|
+
const own = Number(rt.engine.state.privatePath.leafIndex);
|
|
117
|
+
const out = [];
|
|
118
|
+
for (const node of window.nodes.values()) {
|
|
119
|
+
if (canonical.has(node.tag) || node.parentTag === undefined || node.digest === undefined || node.sender !== own)
|
|
120
|
+
continue;
|
|
121
|
+
out.push({ parentTag: node.parentTag, digest: node.digest });
|
|
122
|
+
}
|
|
123
|
+
return out;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* What the runtime watches incoming envelopes for, or `undefined` when nothing (the common case: no decryption, no cost):
|
|
127
|
+
* - the awaited commit C, opened under P's epoch key (marker and parked node alike): bytes only, never an event id;
|
|
128
|
+
* - while the adoption's marker is present and the tip is still S_C, ANY envelope that opens under S_C's epoch key:
|
|
129
|
+
* only a holder of S_C can wrap at that epoch, so C is public (a peer's message, proposal or commit built on it);
|
|
130
|
+
* - an own-leaf fork node's commit under another event id (a re-encrypted copy), which the engine would read as an
|
|
131
|
+
* unopenable own commit; the id-keyed ledger cannot see it.
|
|
132
|
+
*/
|
|
133
|
+
export function pendingWatch(rt) {
|
|
134
|
+
const byParent = new Map();
|
|
135
|
+
const want = (parentTag, digest, sighting) => {
|
|
136
|
+
let digests = byParent.get(parentTag);
|
|
137
|
+
if (digests === undefined)
|
|
138
|
+
byParent.set(parentTag, (digests = new Map()));
|
|
139
|
+
if (!digests.has(digest))
|
|
140
|
+
digests.set(digest, sighting);
|
|
141
|
+
};
|
|
142
|
+
const awaitedCommit = rt.pendingCommit ?? rt.pendingLeaf;
|
|
143
|
+
if (awaitedCommit !== undefined)
|
|
144
|
+
want(awaitedCommit.parentTag, awaitedCommit.digest, 'commit');
|
|
145
|
+
for (const edge of ownForkEdges(rt))
|
|
146
|
+
want(edge.parentTag, edge.digest, 'copy');
|
|
147
|
+
const publicAt = rt.pendingCommit !== undefined && tagOf(rt.engine.state) === rt.pendingCommit.tipTag ? rt.engine.state : undefined;
|
|
148
|
+
if (byParent.size === 0 && publicAt === undefined)
|
|
149
|
+
return undefined;
|
|
150
|
+
return {
|
|
151
|
+
async sight(event) {
|
|
152
|
+
try {
|
|
153
|
+
if (publicAt !== undefined && (await decryptGroupMessages([event], publicAt, rt.engine.ciphersuite)).read.length > 0)
|
|
154
|
+
return 'public';
|
|
155
|
+
for (const [parentTag, digests] of byParent) {
|
|
156
|
+
const parent = parentStateOf(rt, parentTag);
|
|
157
|
+
if (parent === undefined)
|
|
158
|
+
continue;
|
|
159
|
+
const message = (await decryptGroupMessages([event], parent, rt.engine.ciphersuite)).read[0]?.message;
|
|
160
|
+
if (message === undefined)
|
|
161
|
+
continue;
|
|
162
|
+
const seen = digests.get(hexOf(commitDigest(encode(mlsMessageEncoder, message))));
|
|
163
|
+
if (seen !== undefined)
|
|
164
|
+
return seen;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
catch {
|
|
168
|
+
// an envelope no tried key opens is none of them
|
|
169
|
+
}
|
|
170
|
+
return undefined;
|
|
171
|
+
},
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
/** Ledgers `events` (re-encrypted copies of an own commit the window holds as a fork node) `own`: a redelivery is then a duplicate. */
|
|
175
|
+
export async function ledgerOwnCopies(rt, events) {
|
|
176
|
+
if (events.length === 0)
|
|
177
|
+
return;
|
|
178
|
+
await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction(async (tx) => {
|
|
179
|
+
for (const event of events)
|
|
180
|
+
await writeTerminalLedgerEntry(tx.artifact('terminalLedger'), event.id, { disposition: 'own', at: rt.ctx.clock.now(), createdAt: event.created_at });
|
|
181
|
+
}));
|
|
182
|
+
}
|
|
183
|
+
// ---------------------------------------------------------------------------
|
|
184
|
+
// Resolution of the marker (after the first sync)
|
|
185
|
+
// ---------------------------------------------------------------------------
|
|
186
|
+
/**
|
|
187
|
+
* The resolution step of Design Decision 7. Runs once the restore's first sync is over, inside the group's queue, on
|
|
188
|
+
* the PERSISTED tip (the stored `clientState`), and handles only a marker that is still present:
|
|
189
|
+
*
|
|
190
|
+
* 1. no marker: nothing (a second run, or an ingest transaction recognised C and cleared it);
|
|
191
|
+
* 2. tip is not S_C (a commit was applied on top of S_C, which counts as C present, or the sync rewound onto a
|
|
192
|
+
* competing branch, or advanced): the marker is cleared; when S_C is left in the window as a childless fork leaf
|
|
193
|
+
* (C unseen: no peer holds it) it is parked in the side record instead ({@link parkForkLeaf});
|
|
194
|
+
* 3. tip is S_C and the marker survived the sync, so no envelope with C's digest was delivered and none opened under
|
|
195
|
+
* S_C's epoch: in ONE transaction the rewound `clientState` (P), the rewound `rewindTree` (S_C and anything hanging
|
|
196
|
+
* off it removed, every other node kept — the structural replay), the side record, the marker's clearing AND the
|
|
197
|
+
* transition's own bookkeeping ({@link recordTransition}: whatever was delivered under S_C is withdrawn, the
|
|
198
|
+
* settlement recheck is marked) are written; the engine is then rebuilt over P with the window and the held opaque
|
|
199
|
+
* record handed back, and the transition is announced. No ingest cursor is touched. It never rewinds under an
|
|
200
|
+
* intent record that is not `awaiting-sync`: a commit minted on S_C would be orphaned (fail closed).
|
|
201
|
+
*
|
|
202
|
+
* Returns whether the group was rewound (the caller then runs the tree-fed pass over the rebuilt tree, which weighs a
|
|
203
|
+
* competitor of S_C that the sync already ledgered, from P).
|
|
204
|
+
*/
|
|
205
|
+
export async function resolvePendingCommit(rt) {
|
|
206
|
+
const store = rt.groupStore;
|
|
207
|
+
const marker = await rt.guard.call(rt.groupId, 'store', () => readPendingCommit(store.extension(PENDING_COMMIT_EXTENSION)));
|
|
208
|
+
if (marker === undefined) {
|
|
209
|
+
rt.pendingCommit = undefined;
|
|
210
|
+
return false;
|
|
211
|
+
}
|
|
212
|
+
if (rt.fence !== undefined || rt.disbanded !== undefined)
|
|
213
|
+
return false;
|
|
214
|
+
const tip = await rt.guard.call(rt.groupId, 'store', () => readGroupState(store.artifact('clientState')));
|
|
215
|
+
if (tip === undefined)
|
|
216
|
+
throw new MarmotError('store-failed', `group ${rt.groupId}: persisted clientState is missing`);
|
|
217
|
+
if (tagOf(tip) !== marker.tipTag)
|
|
218
|
+
return parkForkLeaf(rt, marker, tip);
|
|
219
|
+
const intents = await rt.guard.call(rt.groupId, 'store', () => listPendingIntentRecords(store.artifact('pendingIntents')));
|
|
220
|
+
if (intents.some((r) => r.state !== 'awaiting-sync')) {
|
|
221
|
+
throw new MarmotError('commit-pending', `group ${rt.groupId}: an own operation was recorded on the adopted pending tip before the restore resolved it; the restore cannot rewind under it`, {
|
|
222
|
+
details: { groupId: rt.groupId, reason: 'pending-restore-intent' },
|
|
223
|
+
});
|
|
224
|
+
}
|
|
225
|
+
const stored = await rt.guard.call(rt.groupId, 'store', () => readWindow(store.artifact('rewindTree')));
|
|
226
|
+
const rewound = stored === undefined || stored.tipTag !== marker.tipTag ? undefined : rewoundToParent(stored);
|
|
227
|
+
if (stored === undefined || rewound === undefined || rewound.parent.tag !== marker.parentTag || rewound.removed.commit === undefined || rewound.removed.digest !== marker.digest) {
|
|
228
|
+
// The adopted window always carries the parent with its state and the tip edge with C (the snapshot validator refused
|
|
229
|
+
// anything else before the adoption wrote a byte): a store that disagrees is corrupt, and keeping S_C is the one outcome
|
|
230
|
+
// the marker exists to prevent.
|
|
231
|
+
throw new MarmotError('store-failed', `group ${rt.groupId}: the stored rewind window does not hold the pending commit and its parent`, { details: { groupId: rt.groupId, malformed: true } });
|
|
232
|
+
}
|
|
233
|
+
const parentState = deserializeClientState(rewound.parent.snapshot);
|
|
234
|
+
const leaf = {
|
|
235
|
+
digest: marker.digest,
|
|
236
|
+
parentTag: marker.parentTag,
|
|
237
|
+
tag: marker.tipTag,
|
|
238
|
+
epoch: rewound.removed.epoch,
|
|
239
|
+
state: serializeClientState(tip),
|
|
240
|
+
commit: rewound.removed.commit,
|
|
241
|
+
};
|
|
242
|
+
const plan = await planTransition(rt, stored, tip, rewound.window, parentState, []);
|
|
243
|
+
await rt.guard.call(rt.groupId, 'store', () => store.transaction(async (tx) => {
|
|
244
|
+
await writeGroupState(tx.artifact('clientState'), parentState);
|
|
245
|
+
await writeWindow(tx.artifact('rewindTree'), rewound.window);
|
|
246
|
+
await writePendingLeaf(tx.extension(PENDING_LEAF_EXTENSION), leaf);
|
|
247
|
+
await clearPendingCommit(tx.extension(PENDING_COMMIT_EXTENSION));
|
|
248
|
+
await recordTransition(rt, tx, plan, parentState.groupContext.epoch);
|
|
249
|
+
}));
|
|
250
|
+
rt.pendingCommit = undefined;
|
|
251
|
+
rt.pendingLeaf = leaf;
|
|
252
|
+
await rebuiltOver(rt, deserializeClientState(serializeClientState(parentState)), rewound.window);
|
|
253
|
+
await deliverTransition(rt, plan);
|
|
254
|
+
rt.checkSyncRouting();
|
|
255
|
+
return true;
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* The marker is moot (the tip is not S_C). Clears it; and when S_C survives in the window as a fork leaf no peer holds
|
|
259
|
+
* (not on the canonical path, nothing built on it — a node with a child proves C public), parks it in the side record
|
|
260
|
+
* in the same transaction instead of leaving a candidate in the engine's tree that could win a later tie (Decision 7a).
|
|
261
|
+
* The tip does not move. Returns false: nothing changed that wants a tree-fed pass.
|
|
262
|
+
*/
|
|
263
|
+
async function parkForkLeaf(rt, marker, tip) {
|
|
264
|
+
const store = rt.groupStore;
|
|
265
|
+
const clearOnly = async () => {
|
|
266
|
+
await rt.guard.call(rt.groupId, 'store', () => store.transaction((tx) => clearPendingCommit(tx.extension(PENDING_COMMIT_EXTENSION))));
|
|
267
|
+
rt.pendingCommit = undefined;
|
|
268
|
+
return false;
|
|
269
|
+
};
|
|
270
|
+
const window = await rt.guard.call(rt.groupId, 'store', () => readWindow(store.artifact('rewindTree')));
|
|
271
|
+
const node = window?.nodes.get(marker.tipTag);
|
|
272
|
+
if (window === undefined ||
|
|
273
|
+
node === undefined ||
|
|
274
|
+
node.snapshot === undefined ||
|
|
275
|
+
node.commit === undefined ||
|
|
276
|
+
node.digest !== marker.digest ||
|
|
277
|
+
node.parentTag !== marker.parentTag ||
|
|
278
|
+
canonicalPath(window).some((n) => n.tag === node.tag) ||
|
|
279
|
+
[...window.nodes.values()].some((n) => n.parentTag === node.tag)) {
|
|
280
|
+
return clearOnly();
|
|
281
|
+
}
|
|
282
|
+
const nodes = new Map(window.nodes);
|
|
283
|
+
nodes.delete(node.tag);
|
|
284
|
+
const next = { tipTag: window.tipTag, nodes };
|
|
285
|
+
const leaf = { digest: marker.digest, parentTag: marker.parentTag, tag: node.tag, epoch: node.epoch, state: node.snapshot, commit: node.commit };
|
|
286
|
+
if (!reinstatable(next, leaf))
|
|
287
|
+
return clearOnly();
|
|
288
|
+
await rt.guard.call(rt.groupId, 'store', () => store.transaction(async (tx) => {
|
|
289
|
+
await writeWindow(tx.artifact('rewindTree'), next);
|
|
290
|
+
await writePendingLeaf(tx.extension(PENDING_LEAF_EXTENSION), leaf);
|
|
291
|
+
await clearPendingCommit(tx.extension(PENDING_COMMIT_EXTENSION));
|
|
292
|
+
}));
|
|
293
|
+
rt.pendingCommit = undefined;
|
|
294
|
+
rt.pendingLeaf = leaf;
|
|
295
|
+
await rebuiltOver(rt, deserializeClientState(serializeClientState(tip)), next);
|
|
296
|
+
return false;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* The runtime's engine rebuilt over `state` and `window`, both already durable. A rebuild that fails leaves the old engine
|
|
300
|
+
* in place against stored rows that moved on: the next operation reloads from the durable state first.
|
|
301
|
+
*/
|
|
302
|
+
async function rebuiltOver(rt, state, window) {
|
|
303
|
+
try {
|
|
304
|
+
await rt.rebuildEngine(state, window);
|
|
305
|
+
}
|
|
306
|
+
catch (error) {
|
|
307
|
+
rt.needsReload = true;
|
|
308
|
+
throw error;
|
|
309
|
+
}
|
|
310
|
+
rt.exposedState = rt.engine.state;
|
|
311
|
+
}
|
|
312
|
+
// ---------------------------------------------------------------------------
|
|
313
|
+
// The parked node
|
|
314
|
+
// ---------------------------------------------------------------------------
|
|
315
|
+
/** Whether `leaf`'s node can still be added to `window`: its parent is the tip, or a node with its serialized state. */
|
|
316
|
+
export function reinstatable(window, leaf) {
|
|
317
|
+
return window.tipTag === leaf.parentTag || window.nodes.get(leaf.parentTag)?.snapshot !== undefined;
|
|
318
|
+
}
|
|
319
|
+
/**
|
|
320
|
+
* Forgets the parked node (reinstatement is impossible: P fell below the horizon or out of the window). C is then
|
|
321
|
+
* processed under today's rules, as an opaque candidate that fences only when it could win.
|
|
322
|
+
*/
|
|
323
|
+
export async function dropPendingLeaf(rt) {
|
|
324
|
+
if (rt.pendingLeaf === undefined)
|
|
325
|
+
return;
|
|
326
|
+
await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction((tx) => clearPendingLeaf(tx.extension(PENDING_LEAF_EXTENSION))));
|
|
327
|
+
rt.pendingLeaf = undefined;
|
|
328
|
+
}
|
|
329
|
+
/**
|
|
330
|
+
* C was delivered after the group landed at P: S_C becomes an ordinary own-leaf fork node. `withForkNode` returns
|
|
331
|
+
* `undefined` for a parent without a snapshot, and the stored window's tip never carries one, so while P is the tip it
|
|
332
|
+
* first receives its snapshot from the stored `clientState` (the way `extendWindow` snapshots a tip it extends); for a
|
|
333
|
+
* non-tip P (the restored self-update advanced the tip) `withForkNode` is called directly. The node is added to the
|
|
334
|
+
* window and the parked record cleared in ONE transaction, then the engine is rebuilt over the stored state with the new
|
|
335
|
+
* window, and a history resync is requested so an undecryptable descendant of S_C that the lost pool held is re-offered.
|
|
336
|
+
* A fork node, not an adopted tip: the credited selection decides it against a competing F or the restored self-update.
|
|
337
|
+
*
|
|
338
|
+
* `carriers` are the delivered envelopes that carry C: each is ledgered `own` in the same transaction, exactly as a stale own
|
|
339
|
+
* commit retained as a fork node is (pipeline.ts `settlePublishedRecord`). The engine cannot process its own commit — it
|
|
340
|
+
* holds no path secrets for it — and recognises C only as the tip's edge, not as a fork node's; a redelivery of the envelope
|
|
341
|
+
* must therefore be a ledger duplicate, never an engine feed (which would read as an unopenable own-leaf commit and fence).
|
|
342
|
+
*
|
|
343
|
+
* Returns whether the node was reinstated; `false` when it could not be (the record is then dropped).
|
|
344
|
+
*/
|
|
345
|
+
export async function reinstatePendingLeaf(rt, carriers) {
|
|
346
|
+
const leaf = rt.pendingLeaf;
|
|
347
|
+
if (leaf === undefined)
|
|
348
|
+
return false;
|
|
349
|
+
const store = rt.groupStore;
|
|
350
|
+
const durable = await rt.guard.call(rt.groupId, 'store', () => readGroupState(store.artifact('clientState')));
|
|
351
|
+
const window = await rt.guard.call(rt.groupId, 'store', () => readWindow(store.artifact('rewindTree')));
|
|
352
|
+
if (durable === undefined || window === undefined || !reinstatable(window, leaf)) {
|
|
353
|
+
await dropPendingLeaf(rt);
|
|
354
|
+
return false;
|
|
355
|
+
}
|
|
356
|
+
const tip = window.nodes.get(window.tipTag);
|
|
357
|
+
const base = window.tipTag === leaf.parentTag ? { tipTag: window.tipTag, nodes: new Map(window.nodes).set(tip.tag, { ...tip, snapshot: serializeClientState(durable) }) } : window;
|
|
358
|
+
const parentState = deserializeClientState(base.nodes.get(leaf.parentTag).snapshot);
|
|
359
|
+
const record = decodeOwnCommitRecord(leaf.commit);
|
|
360
|
+
const next = withForkNode(base, { parentState, commit: record.wireBytes, newState: deserializeClientState(leaf.state), ...(record.kind === 'stamped' ? { stamp: record.stamp } : {}) });
|
|
361
|
+
if (next === undefined) {
|
|
362
|
+
await dropPendingLeaf(rt);
|
|
363
|
+
return false;
|
|
364
|
+
}
|
|
365
|
+
// The tip never carries a snapshot (the stored `clientState` is it); only the fork node's parent needed one above.
|
|
366
|
+
const persisted = window.tipTag === leaf.parentTag ? { tipTag: next.tipTag, nodes: new Map(next.nodes).set(tip.tag, window.nodes.get(tip.tag)) } : next;
|
|
367
|
+
await rt.guard.call(rt.groupId, 'store', () => store.transaction(async (tx) => {
|
|
368
|
+
await writeWindow(tx.artifact('rewindTree'), persisted);
|
|
369
|
+
for (const event of carriers) {
|
|
370
|
+
await writeTerminalLedgerEntry(tx.artifact('terminalLedger'), event.id, { disposition: 'own', at: rt.ctx.clock.now(), createdAt: event.created_at });
|
|
371
|
+
}
|
|
372
|
+
await clearPendingLeaf(tx.extension(PENDING_LEAF_EXTENSION));
|
|
373
|
+
}));
|
|
374
|
+
rt.pendingLeaf = undefined;
|
|
375
|
+
await rebuiltOver(rt, deserializeClientState(serializeClientState(durable)), persisted);
|
|
376
|
+
rt.resync();
|
|
377
|
+
return true;
|
|
378
|
+
}
|