@941design/marmot 0.2.0-alpha.0 → 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 +30 -0
- package/dist/account/teardown.d.ts +66 -3
- package/dist/account/teardown.js +24 -2
- 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-publish-hooks.js +3 -1
- package/dist/client/commit-redrive.d.ts +28 -4
- package/dist/client/commit-redrive.js +54 -1
- package/dist/client/confirm-hooks.d.ts +6 -1
- package/dist/client/confirm-hooks.js +15 -0
- package/dist/client/create-client.d.ts +107 -3
- package/dist/client/create-client.js +114 -7
- package/dist/client/group-availability.d.ts +182 -0
- package/dist/client/group-availability.js +301 -0
- package/dist/client/group-history.d.ts +26 -0
- package/dist/client/group-history.js +77 -7
- package/dist/client/group-records.d.ts +39 -2
- package/dist/client/group-records.js +88 -5
- package/dist/client/group-runtime.d.ts +30 -3
- package/dist/client/group-runtime.js +131 -21
- package/dist/client/group-snapshot.d.ts +7 -1
- package/dist/client/group-snapshot.js +23 -2
- package/dist/client/index.d.ts +4 -1
- package/dist/client/ingest.js +47 -13
- package/dist/client/invitation-outcomes.d.ts +50 -0
- package/dist/client/invitation-outcomes.js +135 -0
- package/dist/client/opaque-candidates.d.ts +2 -1
- package/dist/client/opaque-candidates.js +2 -1
- package/dist/client/own-change-outbox.js +2 -0
- package/dist/client/pipeline.d.ts +30 -1
- package/dist/client/pipeline.js +142 -21
- package/dist/client/reentrancy-guard.d.ts +6 -0
- package/dist/client/reentrancy-guard.js +6 -0
- package/dist/history/admission-lineage.d.ts +186 -0
- package/dist/history/admission-lineage.js +589 -0
- package/dist/history/fencing.d.ts +41 -0
- package/dist/history/fencing.js +67 -7
- package/dist/history/index.d.ts +2 -1
- package/dist/history/index.js +2 -1
- package/dist/history/own-change.d.ts +13 -1
- package/dist/invitations/decline.d.ts +8 -2
- package/dist/invitations/decline.js +9 -3
- package/dist/invitations/delivery-evidence.d.ts +288 -0
- package/dist/invitations/delivery-evidence.js +766 -0
- package/dist/invitations/index.d.ts +4 -2
- package/dist/invitations/index.js +4 -2
- package/dist/invitations/invitation-outcome.d.ts +110 -0
- package/dist/invitations/invitation-outcome.js +210 -0
- package/dist/invitations/invite.d.ts +61 -6
- package/dist/invitations/invite.js +187 -51
- package/dist/invitations/welcome-processor.d.ts +20 -1
- package/dist/invitations/welcome-processor.js +81 -20
- package/dist/shared/errors.d.ts +7 -0
- package/dist/shared/errors.js +11 -0
- package/dist/shared/index.d.ts +1 -1
- package/dist/shared/index.js +1 -1
- package/dist/storage/index.d.ts +10 -0
- package/dist/storage/index.js +33 -1
- package/dist/storage/lease.d.ts +13 -0
- package/dist/storage/lease.js +51 -0
- package/package.json +2 -2
package/dist/client/pipeline.js
CHANGED
|
@@ -2,16 +2,18 @@ import { commitDigest, deserializeClientState, getMarmotGroupView, getKeyPackage
|
|
|
2
2
|
import { decideAutoCommit, decodeOwnCommitRecord, deriveStateNotifications, encodeOwnCommitRecord, nextOwnApplicationGeneration } from '@941design/marmot-engine/engine';
|
|
3
3
|
import { decode, defaultProposalTypes, encode, getCredentialFromLeafIndex, mlsMessageDecoder, mlsMessageEncoder, nodeTypes, selfRemoveProposalType, } from '@941design/marmot-engine/mls';
|
|
4
4
|
import { adminPolicyProposal, directedAncestors, enforceStateTransition, isActiveAdmin, readRegistryEdges, REOPENED_LEAF_STILL_CANONICAL, validateAdminList } from '../account/index.js';
|
|
5
|
-
import { addProposalsFor, buildWelcomeRumors, deleteDeferral, deleteExclusionEpochs, DEFERRED_PROPOSALS_EXTENSION, EXCLUDED_PROPOSALS_EXTENSION, exclusionsAt, hasStagedAdds, isAuthorisedCommitter, mustQueue, nextQueueStep, planDeferrals, queueBarrier, readDeferrals, readExclusions, recipientsOfWelcome, resolveProposals, STAGED_ADD_LOOKUP_TIMEOUT_MS, stagedAddRecipients, stagedProposals, validateInvitees, withoutProposals, writeDeferral, writeExclusion, writeExclusionSnapshot, } from '../invitations/index.js';
|
|
5
|
+
import { addAnchorsOf, addProposalsFor, buildWelcomeRumors, deleteDeferral, deleteExclusionEpochs, DEFERRED_PROPOSALS_EXTENSION, EXCLUDED_PROPOSALS_EXTENSION, exclusionsAt, hasStagedAdds, isAuthorisedCommitter, mustQueue, nextQueueStep, planDeferrals, queueBarrier, readDeferrals, readExclusions, recipientsOfWelcome, resolveProposals, STAGED_ADD_LOOKUP_TIMEOUT_MS, stagedAddRecipients, stagedProposals, validateInvitees, withoutProposals, writeDeferral, writeExclusion, writeExclusionSnapshot, } from '../invitations/index.js';
|
|
6
6
|
import { isHex64, MarmotError, isMarmotError } from '../shared/index.js';
|
|
7
7
|
import { readDeviceKeyLink } from '../key-packages/index.js';
|
|
8
8
|
import { assertNoStagedComponentUpdate, componentUpdateProposal, genericComponentGuard, guardedComponentUpdate } from './component-update.js';
|
|
9
9
|
import { assertGroupProfile, groupProfileAction, profileUpdateGuard } from './group-profile.js';
|
|
10
10
|
import { assertAccountPubkey, holdsLeafOfAny, holdsSnapshotLeaf, leafKeysOfAccount, removeProposalsForAccounts, stagedAddConflict } from './group-remove-member.js';
|
|
11
|
-
import { canonicalPath, commitViewOf, extendWindow, holdsLeafKey as holdsLeafKeyOfView, withForkNode, fencedError, fencingErrorIn, isFencingError, orderingKeyOf, REWIND_HORIZON, tagOf, windowFor, writeWindow, } from '../history/index.js';
|
|
11
|
+
import { ADMISSION_LINEAGE_EXTENSION, canonicalPath, commitViewOf, extendWindow, holdsLeafKey as holdsLeafKeyOfView, withForkNode, fencedError, fencingErrorIn, isFencingError, orderingKeyOf, REWIND_HORIZON, tagOf, windowFor, writeWindow, seedLineageRecords, } from '../history/index.js';
|
|
12
|
+
import { emitCleanupDispositions, lineageSeedsOf, noteCleanupCandidate, readCleanupTargetAdmission, recordCleanupConfirmation, cleanupTargetOf } from './admission-cleanup.js';
|
|
12
13
|
import { assertNotDisbanded } from './group-disband.js';
|
|
13
|
-
import { changesNeedingKeyPackageCheck, decideChanges } from './commit-redrive.js';
|
|
14
|
-
import {
|
|
14
|
+
import { changesNeedingKeyPackageCheck, cleanupTargetRefusal, decideChanges } from './commit-redrive.js';
|
|
15
|
+
import { beginLostLeaseAvailability } from './group-availability.js';
|
|
16
|
+
import { announceTerminals, assertNotFenced, deliverTransition, dispatch, fenceGroup, lostMessagePlan, rejectSyncWaiters, rejectSyncWaitersFenced, parkWithdrawnWelcomes, planTransition, recordEquivocations, recordTransition, sentOnCanonicalBranch, syncedLeaseLostError, WITHDRAWN_DISPOSITION } from './group-history.js';
|
|
15
17
|
import { clearRestorePending, deletePendingIntentRecord, listPendingIntentRecords, listQueuedRumorRecords, markRatchetSkipDelivered, nextSeq, OWN_COMMIT_EXTENSION, RATCHET_SKIP_EXTENSION, randomIntentId, RESTORE_PENDING_EXTENSION, readPendingIntentRecord, readQueuedRumorRecord, writeGroupState, raiseRootSpend, writeOwnCommitMarker, writePendingIntentRecord, writeQueuedRumorRecord, writeRatchetSkipMarker, writeTerminalLedgerEntry, isCommitRedrive, } from './group-records.js';
|
|
16
18
|
import { enqueueTerminals, OWN_CHANGE_OUTBOX_EXTENSION, terminalKey } from './own-change-outbox.js';
|
|
17
19
|
import { runConfirmHooks } from './confirm-hooks.js';
|
|
@@ -67,7 +69,14 @@ function declaresOwnChange(record) {
|
|
|
67
69
|
return false;
|
|
68
70
|
if (intent.removeLeafKeys !== undefined || intent.origin !== undefined)
|
|
69
71
|
return false;
|
|
70
|
-
return intent.removeAccounts !== undefined ||
|
|
72
|
+
return (intent.removeAccounts !== undefined ||
|
|
73
|
+
intent.invite !== undefined ||
|
|
74
|
+
intent.admins !== undefined ||
|
|
75
|
+
intent.profile !== undefined ||
|
|
76
|
+
intent.components !== undefined ||
|
|
77
|
+
// Epic marmot-invitation-outcomes S5 (SC-6 I16): a scoped cleanup declares its `admission-removed` change.
|
|
78
|
+
intent.removeAdmission !== undefined ||
|
|
79
|
+
record.changes !== undefined);
|
|
71
80
|
}
|
|
72
81
|
/** The changes an intent declares besides an invite (DD2): what the withdrawal-time breakdown keeps of the state diff. */
|
|
73
82
|
function declaredOf(intent) {
|
|
@@ -76,6 +85,8 @@ function declaredOf(intent) {
|
|
|
76
85
|
...(intent.removeAccounts === undefined ? {} : { removed: [...intent.removeAccounts] }),
|
|
77
86
|
...(intent.admins === undefined ? {} : { admins: true }),
|
|
78
87
|
...(components.length === 0 ? {} : { components }),
|
|
88
|
+
// S5 (SC-6 I16): declared from the intent, never matched against the diff (whose `member-removed` a cleanup never declares).
|
|
89
|
+
...(intent.removeAdmission === undefined ? {} : { admissions: [intent.removeAdmission] }),
|
|
79
90
|
};
|
|
80
91
|
return Object.keys(declared).length === 0 ? undefined : declared;
|
|
81
92
|
}
|
|
@@ -137,6 +148,9 @@ async function terminalFail(rt, record, hasCaller, cause, extraDetails = {}) {
|
|
|
137
148
|
// transaction that deleted the record (`deleteEndingRecord`, with `lostReasonOf(extraDetails)`); this hands them over.
|
|
138
149
|
if (isCommitRedrive(record))
|
|
139
150
|
await announceTerminals(rt);
|
|
151
|
+
// Epic marmot-invitation-outcomes S5 (SC-12): a cleanup that ended without a commit changes its disposition (best effort).
|
|
152
|
+
if (cleanupTargetOf(record) !== undefined)
|
|
153
|
+
emitCleanupDispositions(rt);
|
|
140
154
|
if (hasCaller) {
|
|
141
155
|
notifySettled(rt, record, err);
|
|
142
156
|
throw err;
|
|
@@ -299,6 +313,9 @@ function toEngineIntent(intent, selfPubkey, state, groupId) {
|
|
|
299
313
|
...(intent.profile === undefined ? [] : [groupProfileAction(intent.profile, groupId)]),
|
|
300
314
|
// The internal `components` field (DD2): applied when driven, first time as much as a re-drive -- each component's update, or its deletion.
|
|
301
315
|
...(intent.components ?? []).map((c) => guardedComponentUpdate(genericComponentGuard(c.id, groupId), () => componentUpdateProposal(c.id, c.data))),
|
|
316
|
+
// Epic marmot-invitation-outcomes S5 (SC-5 I13/I14): a scoped cleanup removes ONE position, inline (never by reference), after
|
|
317
|
+
// the build re-checked on this very state that the target's original admission occupies it (`driveIntent`).
|
|
318
|
+
...(intent.removeAdmission === undefined ? [] : [{ proposalType: defaultProposalTypes.remove, remove: { removed: intent.removeAdmission.anchor.leafIndex } }]),
|
|
302
319
|
];
|
|
303
320
|
return extraProposals.length === 0 ? { kind: 'commit', actorPubkey: selfPubkey } : { kind: 'commit', actorPubkey: selfPubkey, extraProposals };
|
|
304
321
|
}
|
|
@@ -442,6 +459,20 @@ function windowAfterOwnCommit(rt, link) {
|
|
|
442
459
|
const base = windowFor(rt.window, link.parentState);
|
|
443
460
|
return extendWindow(base, { parentState: link.parentState, commit: link.commit, newState: link.newState, ...(link.stamp === undefined ? {} : { stamp: link.stamp }) });
|
|
444
461
|
}
|
|
462
|
+
/** The KeyPackages an invite intent adds (its stored invitee events); one that does not decode is left out (it anchors nothing). */
|
|
463
|
+
function inviteKeyPackagesOf(record) {
|
|
464
|
+
const invitees = record.intent.type === 'commit' ? (record.intent.invite?.invitees ?? []) : [];
|
|
465
|
+
const out = [];
|
|
466
|
+
for (const invitee of invitees) {
|
|
467
|
+
try {
|
|
468
|
+
out.push(getKeyPackage(invitee.event));
|
|
469
|
+
}
|
|
470
|
+
catch {
|
|
471
|
+
// not a KeyPackage event: no anchor for it
|
|
472
|
+
}
|
|
473
|
+
}
|
|
474
|
+
return out;
|
|
475
|
+
}
|
|
445
476
|
async function confirmRecord(rt, record, attempt, live, hasCaller = false) {
|
|
446
477
|
if (isCommitRedrive(record)) {
|
|
447
478
|
// A restoring transition retires a commit re-drive in every state (group-history.ts cancelRestoredReenqueues, AC-REC-7): a
|
|
@@ -471,6 +502,8 @@ async function confirmRecord(rt, record, attempt, live, hasCaller = false) {
|
|
|
471
502
|
let notifications = [];
|
|
472
503
|
/** S10: the rewind window the confirmed commit is persisted with — its own link and stamp on top of the parent's. */
|
|
473
504
|
let window;
|
|
505
|
+
/** Epic marmot-invitation-outcomes S3 (SC-1): the confirmed own commit's parent state, for the deliveries' Add anchors. */
|
|
506
|
+
let confirmedParent;
|
|
474
507
|
if (record.pending !== undefined && record.kind === 'proposal') {
|
|
475
508
|
newState = withOwnProposal(rt.engine.state, deserializeClientState(record.pending.newState));
|
|
476
509
|
if (newState === undefined) {
|
|
@@ -487,6 +520,7 @@ async function confirmRecord(rt, record, attempt, live, hasCaller = false) {
|
|
|
487
520
|
newState = deserializeClientState(record.pending.newState);
|
|
488
521
|
if (record.pending.parentState !== undefined && record.pending.commitMessage !== undefined) {
|
|
489
522
|
const parentState = deserializeClientState(record.pending.parentState);
|
|
523
|
+
confirmedParent = parentState;
|
|
490
524
|
const decodedCommit = decode(mlsMessageDecoder, record.pending.commitMessage);
|
|
491
525
|
if (decodedCommit !== undefined) {
|
|
492
526
|
const digestBytes = commitDigest(record.pending.commitMessage);
|
|
@@ -546,11 +580,35 @@ async function confirmRecord(rt, record, attempt, live, hasCaller = false) {
|
|
|
546
580
|
// this record (a crash in between only repeats the upsert, which keeps any
|
|
547
581
|
// delivery progress). A failed handoff blocks and retries like a hook.
|
|
548
582
|
const welcomes = record.welcomes;
|
|
583
|
+
// S4 (SC-1 → SC-4): the lineage seeds of this confirmation's anchors, written in the group transaction below.
|
|
584
|
+
let lineageSeeds;
|
|
549
585
|
if (welcomes !== undefined && welcomes.length > 0) {
|
|
586
|
+
// Epic marmot-invitation-outcomes S3 (SC-1 I1/I2): each delivery's Add anchor, from the confirmed parent → new
|
|
587
|
+
// state pair and the KeyPackages this commit added; written with the delivery evidence in the hand-off's
|
|
588
|
+
// account transaction, before the group transaction below.
|
|
589
|
+
const anchors = newState !== undefined && confirmedParent !== undefined && record.pending?.commitMessage !== undefined
|
|
590
|
+
? await addAnchorsOf({
|
|
591
|
+
parentState: confirmedParent,
|
|
592
|
+
newState,
|
|
593
|
+
addDigest: toHex(commitDigest(record.pending.commitMessage)),
|
|
594
|
+
addTag: tagOf(newState),
|
|
595
|
+
commitEventId: envelope.id,
|
|
596
|
+
keyPackages: inviteKeyPackagesOf(record),
|
|
597
|
+
})
|
|
598
|
+
: undefined;
|
|
550
599
|
// Framed on the group scope too (InvitationsDeps already frames the account scope): this runs
|
|
551
600
|
// while the confirmation holds the group's queue, so a consumer account store that awaits a
|
|
552
601
|
// mutating call on this group from inside it is rejected `reentrant` rather than deadlocking.
|
|
553
|
-
await rt.guard.call(rt.groupId, 'store', () => rt.invitations.recordCommitted({
|
|
602
|
+
await rt.guard.call(rt.groupId, 'store', () => rt.invitations.recordCommitted({
|
|
603
|
+
inviteId: record.intentId,
|
|
604
|
+
groupId: rt.groupId,
|
|
605
|
+
commitEventId: envelope.id,
|
|
606
|
+
...(newState === undefined ? {} : { commitTag: tagOf(newState) }),
|
|
607
|
+
welcomes,
|
|
608
|
+
...(anchors === undefined ? {} : { anchors }),
|
|
609
|
+
}));
|
|
610
|
+
if (anchors !== undefined && anchors.size > 0)
|
|
611
|
+
lineageSeeds = lineageSeedsOf(rt.groupId, record.intentId, anchors);
|
|
554
612
|
}
|
|
555
613
|
await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction(async (tx) => {
|
|
556
614
|
if (newState !== undefined)
|
|
@@ -585,6 +643,15 @@ async function confirmRecord(rt, record, attempt, live, hasCaller = false) {
|
|
|
585
643
|
await writeOwnCommitMarker(tx.extension(OWN_COMMIT_EXTENSION), envelope.id, ownCommitMarker);
|
|
586
644
|
if (announced !== undefined)
|
|
587
645
|
restoredReenqueues = await recordTransition(rt, tx, announced, newState?.groupContext.epoch ?? rt.engine.state.groupContext.epoch);
|
|
646
|
+
// S4 (SC-4): each anchored delivery's admission lineage starts here — the Add node (the new tip) is its
|
|
647
|
+
// checkpoint — in the transaction that persists that node, after the transition advanced the older records.
|
|
648
|
+
if (lineageSeeds !== undefined && newState !== undefined)
|
|
649
|
+
await seedLineageRecords(tx.extension(ADMISSION_LINEAGE_EXTENSION), lineageSeeds, Number(newState.groupContext.epoch));
|
|
650
|
+
// Epic marmot-invitation-outcomes S5 (SC-5 I13): a confirmed scoped cleanup whose built commit carried an INLINE Remove of the
|
|
651
|
+
// target's position appends this commit to the candidate's ledger entry — the only source of positive attribution (I14).
|
|
652
|
+
if (newState !== undefined && record.pending?.commitMessage !== undefined) {
|
|
653
|
+
await recordCleanupConfirmation(tx, { record, rootIntentId: reportedIntentIdOf(record), commitMessage: record.pending.commitMessage, digest: toHex(commitDigest(record.pending.commitMessage)), tag: tagOf(newState) });
|
|
654
|
+
}
|
|
588
655
|
await enqueueTerminals(tx.extension(OWN_CHANGE_OUTBOX_EXTENSION), reapplied);
|
|
589
656
|
// AC-MX-2: an own self-update confirmed — a restored group's adoption is complete (atomically with it).
|
|
590
657
|
if (record.kind === 'self-update')
|
|
@@ -647,6 +714,10 @@ async function confirmRecord(rt, record, attempt, live, hasCaller = false) {
|
|
|
647
714
|
applied = { failed: true, error };
|
|
648
715
|
}
|
|
649
716
|
notifySettled(rt, record, undefined);
|
|
717
|
+
// Epic marmot-invitation-outcomes S5 (SC-12): the confirmed cleanup's candidate is one this session reports dispositions for.
|
|
718
|
+
const cleanupTarget = cleanupTargetOf(record);
|
|
719
|
+
if (cleanupTarget !== undefined)
|
|
720
|
+
noteCleanupCandidate(rt, cleanupTarget.candidateId);
|
|
650
721
|
// S10: announced once the confirmation is applied.
|
|
651
722
|
if (plan !== undefined)
|
|
652
723
|
await deliverTransition(rt, plan, deferred);
|
|
@@ -700,6 +771,10 @@ export function backgroundRetryEnds(rt, error) {
|
|
|
700
771
|
if (!isMarmotError(error, 'no-lease'))
|
|
701
772
|
return false;
|
|
702
773
|
rt.leaseLost ??= error;
|
|
774
|
+
// Epic marmot-invitation-outcomes S1 (A-4/A-5): the account lease ended — every group's availability subscriptions
|
|
775
|
+
// end `no-lease` (idempotent), the lazy fallback of a store without `onLeaseEnded`. Recorded now, delivered last: a
|
|
776
|
+
// listener reacting to its `ended` (a `dispose()`) must find every lease-end consequence below already settled.
|
|
777
|
+
const deliverAvailabilityEnds = beginLostLeaseAvailability(rt);
|
|
703
778
|
const watchers = [...rt.terminalWatchers];
|
|
704
779
|
rt.terminalWatchers.clear();
|
|
705
780
|
for (const watcher of watchers) {
|
|
@@ -710,6 +785,17 @@ export function backgroundRetryEnds(rt, error) {
|
|
|
710
785
|
// A watcher never breaks the retry that observed the lost lease.
|
|
711
786
|
}
|
|
712
787
|
}
|
|
788
|
+
// The send gate never opens without the lease (history ingest writes the stores): a `synced()` wait for the first
|
|
789
|
+
// catch-up fails `no-lease` instead of hanging until teardown. After the terminal watchers, so a wait raced against
|
|
790
|
+
// one of them (a restore's) settles with the watcher's error. The lease is the client's, so every other live group's
|
|
791
|
+
// pending wait fails too (in memory only, as for the store's explicit lease-end signal): a later `synced()` already
|
|
792
|
+
// rejects through the client-wide flag, and one made earlier must not hang.
|
|
793
|
+
rejectSyncWaiters(rt, () => syncedLeaseLostError(rt, error));
|
|
794
|
+
for (const other of [...rt.availabilityClient.runtimes()]) {
|
|
795
|
+
if (other !== rt)
|
|
796
|
+
rejectSyncWaiters(other, () => syncedLeaseLostError(other, error));
|
|
797
|
+
}
|
|
798
|
+
deliverAvailabilityEnds();
|
|
713
799
|
return true;
|
|
714
800
|
}
|
|
715
801
|
/**
|
|
@@ -1176,7 +1262,7 @@ async function settlePublishedRecord(rt, record, opts) {
|
|
|
1176
1262
|
* (which would queue behind the op awaiting the signer) is rejected
|
|
1177
1263
|
* `reentrant` instead of deadlocking; other groups stay reachable.
|
|
1178
1264
|
*/
|
|
1179
|
-
function callSignerForGroup(rt, fn) {
|
|
1265
|
+
export function callSignerForGroup(rt, fn) {
|
|
1180
1266
|
return rt.guard.call(rt.groupId, 'signer', () => rt.guard.call(ACCOUNT_SCOPE, 'signer', fn));
|
|
1181
1267
|
}
|
|
1182
1268
|
/**
|
|
@@ -1254,6 +1340,18 @@ async function driveIntent(rt, given, hasCaller, redrive) {
|
|
|
1254
1340
|
await failBuild(new Error('a foreign commit at this epoch has already been confirmed'));
|
|
1255
1341
|
return;
|
|
1256
1342
|
}
|
|
1343
|
+
// Epic marmot-invitation-outcomes S5 (SC-5 I15, AC-REMOVE-10): a scoped cleanup is built only while the proven original admission
|
|
1344
|
+
// occupies its position on the ACTUAL parent (this state), under the key its lineage derives, and nothing staged interferes. A
|
|
1345
|
+
// replaced or ended occupancy, a lineage gap or a changed leaf drops the intent: a replacement on a new parent is never removed.
|
|
1346
|
+
if (build.type === 'commit' && build.removeAdmission !== undefined) {
|
|
1347
|
+
const admission = await readCleanupTargetAdmission(rt, build.removeAdmission);
|
|
1348
|
+
assertNotDisposed(rt);
|
|
1349
|
+
const refusal = cleanupTargetRefusal(build.removeAdmission, admission, rt.engine.state);
|
|
1350
|
+
if (refusal !== undefined) {
|
|
1351
|
+
await failBuild(new MarmotError('send-rejected', `removeAdmission: the target admission of candidate ${build.removeAdmission.candidateId} cannot be removed on group ${rt.groupId} (${refusal.reason})`, { details: { groupId: rt.groupId, reason: refusal.reason } }));
|
|
1352
|
+
return;
|
|
1353
|
+
}
|
|
1354
|
+
}
|
|
1257
1355
|
// AC-REKEY-6: a rekey that has nothing left to do (the leaf already carries the target, or the device key moved on)
|
|
1258
1356
|
// is dropped before anything is staged — also before the staged-Adds commit it would otherwise cause.
|
|
1259
1357
|
if (record.intent.type === 'self-update' && record.intent.rekey !== undefined) {
|
|
@@ -1340,7 +1438,7 @@ async function driveIntent(rt, given, hasCaller, redrive) {
|
|
|
1340
1438
|
}
|
|
1341
1439
|
// A removal that fails the admin-leaf coupling check: a staged admin-policy update (committed together with the removal)
|
|
1342
1440
|
// still names a removed admin.
|
|
1343
|
-
const couplingFailure = isAccountRemovalOnly(build) && error?.violation?.reason === 'admin-leaf-coupling';
|
|
1441
|
+
const couplingFailure = (isAccountRemovalOnly(build) || (build.type === 'commit' && build.removeAdmission !== undefined)) && error?.violation?.reason === 'admin-leaf-coupling';
|
|
1344
1442
|
await failBuild(error, couplingFailure ? { reason: 'staged-admin-policy-update' } : {});
|
|
1345
1443
|
return;
|
|
1346
1444
|
}
|
|
@@ -1462,7 +1560,7 @@ async function restoreDurableEngine(rt, pending) {
|
|
|
1462
1560
|
* The shared start of every own-intent operation: resumes durable records,
|
|
1463
1561
|
* then refuses while a confirmation is blocked. Returns the remaining records.
|
|
1464
1562
|
*/
|
|
1465
|
-
async function preflight(rt, operation) {
|
|
1563
|
+
export async function preflight(rt, operation) {
|
|
1466
1564
|
// AC-HIST-4: a fenced group accepts no further sends (and resumes nothing it recorded before).
|
|
1467
1565
|
assertNotFenced(rt, operation);
|
|
1468
1566
|
// Nor does a disbanded one (client/group-disband.ts).
|
|
@@ -1480,12 +1578,12 @@ async function preflight(rt, operation) {
|
|
|
1480
1578
|
return remaining;
|
|
1481
1579
|
}
|
|
1482
1580
|
/** AC-INVITE-7: a removed local leaf sends nothing — refused before any record or transport call. */
|
|
1483
|
-
function assertMember(rt, operation) {
|
|
1581
|
+
export function assertMember(rt, operation) {
|
|
1484
1582
|
if (rt.engine.state.groupActiveState.kind === 'removedFromGroup') {
|
|
1485
1583
|
throw new MarmotError('not-a-member', `${operation}: the local leaf has been removed from group ${rt.groupId}`, { details: { groupId: rt.groupId } });
|
|
1486
1584
|
}
|
|
1487
1585
|
}
|
|
1488
|
-
function assertNoOwnCommitPending(rt, remaining, operation) {
|
|
1586
|
+
export function assertNoOwnCommitPending(rt, remaining, operation) {
|
|
1489
1587
|
// An own commit still pending-publish may already sit on a relay (the
|
|
1490
1588
|
// OK was lost, or the resume probe timed out): a second own commit
|
|
1491
1589
|
// built now would be a sibling at the same epoch — a fork of our own
|
|
@@ -1497,9 +1595,11 @@ function assertNoOwnCommitPending(rt, remaining, operation) {
|
|
|
1497
1595
|
});
|
|
1498
1596
|
}
|
|
1499
1597
|
}
|
|
1500
|
-
async function recordIntent(rt, kind, intent, state = 'pending-publish',
|
|
1598
|
+
export async function recordIntent(rt, kind, intent, state = 'pending-publish',
|
|
1501
1599
|
// Evaluated when the call is made, before the seq lookup below awaits: a caller that decided on a state snapshot passes that snapshot's epoch.
|
|
1502
|
-
parentEpoch = rt.engine.state.groupContext.epoch
|
|
1600
|
+
parentEpoch = rt.engine.state.groupContext.epoch,
|
|
1601
|
+
/** Epic marmot-invitation-outcomes S5 (SC-5 I13): further writes in the SAME transaction as the record (the cleanup ledger entry). */
|
|
1602
|
+
alsoWrite) {
|
|
1503
1603
|
const view = rt.groupStore.artifact('pendingIntents');
|
|
1504
1604
|
const seq = await rt.guard.call(rt.groupId, 'store', () => nextSeq(view));
|
|
1505
1605
|
const record = {
|
|
@@ -1512,7 +1612,10 @@ parentEpoch = rt.engine.state.groupContext.epoch) {
|
|
|
1512
1612
|
intent,
|
|
1513
1613
|
attempts: 0,
|
|
1514
1614
|
};
|
|
1515
|
-
await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction((tx) =>
|
|
1615
|
+
await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction(async (tx) => {
|
|
1616
|
+
await writePendingIntentRecord(tx.artifact('pendingIntents'), record);
|
|
1617
|
+
await alsoWrite?.(tx, record);
|
|
1618
|
+
}));
|
|
1516
1619
|
assertNotDisposed(rt);
|
|
1517
1620
|
return record;
|
|
1518
1621
|
}
|
|
@@ -2154,7 +2257,24 @@ async function decideRedrive(rt, record) {
|
|
|
2154
2257
|
const adminView = getMarmotGroupView(state);
|
|
2155
2258
|
const authorIsAdmin = adminView !== null && isActiveAdmin(state.ratchetTree, adminView.adminPubkeys, author);
|
|
2156
2259
|
const changes = record.changes ?? [];
|
|
2157
|
-
|
|
2260
|
+
// Epic marmot-invitation-outcomes S5 (SC-5 I15): what the selected path proves about each cleanup target, read before the pure ladder.
|
|
2261
|
+
const admissions = new Map();
|
|
2262
|
+
for (const c of changes) {
|
|
2263
|
+
if (c.verdict !== undefined || c.change.type !== 'admission-removed')
|
|
2264
|
+
continue;
|
|
2265
|
+
const target = c.target;
|
|
2266
|
+
admissions.set(target.candidateId, await readCleanupTargetAdmission(rt, target));
|
|
2267
|
+
assertNotDisposed(rt);
|
|
2268
|
+
noteCleanupCandidate(rt, target.candidateId);
|
|
2269
|
+
}
|
|
2270
|
+
const base = {
|
|
2271
|
+
state,
|
|
2272
|
+
window: rt.window,
|
|
2273
|
+
windowTip: rt.exposedState,
|
|
2274
|
+
authorIsAdmin,
|
|
2275
|
+
forkEpoch: record.forkEpoch ?? 0,
|
|
2276
|
+
admissionOf: (target) => admissions.get(target.candidateId),
|
|
2277
|
+
};
|
|
2158
2278
|
// Only the invites the ladder would reach the validity rung for are checked (a consumer verifier is never called for a change lost anyway).
|
|
2159
2279
|
const checks = changesNeedingKeyPackageCheck(changes, base);
|
|
2160
2280
|
let invalidKeyPackages = await invalidRetainedKeyPackages(rt, checks, state);
|
|
@@ -2183,6 +2303,8 @@ async function decideRedrive(rt, record) {
|
|
|
2183
2303
|
await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction((tx) => deleteEndingRecord(tx, { ...record, changes: outcome.changes }, 'concurrent-change', outcome.newlyLost)));
|
|
2184
2304
|
assertNotDisposed(rt);
|
|
2185
2305
|
await announceTerminals(rt);
|
|
2306
|
+
// S5 (SC-12, AC-REMOVE-24/29): a re-drive that ended in own-change loss changes the cleanup's disposition (pending → eligible / absent).
|
|
2307
|
+
emitCleanupDispositions(rt);
|
|
2186
2308
|
scheduleDeferredReenqueueRetry(rt, record.intentId);
|
|
2187
2309
|
return undefined;
|
|
2188
2310
|
}
|
|
@@ -2226,6 +2348,7 @@ async function driveCommitRedrive(rt, rootIntentId) {
|
|
|
2226
2348
|
await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction((tx) => deleteEndingRecord(tx, decision.record, 'attempts-exhausted', decision.newlyLost)));
|
|
2227
2349
|
assertNotDisposed(rt);
|
|
2228
2350
|
await endRedriveExhausted(rt, decision.record);
|
|
2351
|
+
emitCleanupDispositions(rt);
|
|
2229
2352
|
return 'driven';
|
|
2230
2353
|
}
|
|
2231
2354
|
// `newlyLost` are written with the staging transaction (or, a terminal refusal before it, with the one that ends the record); `staged` hands the
|
|
@@ -2295,7 +2418,7 @@ export async function failStrandedSelfUpdateReenqueues(rt, cause) {
|
|
|
2295
2418
|
// On opening, `releaseAwaitingSync` drives the awaiting records in `seq` order through the ordinary resume path.
|
|
2296
2419
|
// When the group is fenced instead, `failAwaitingIntents` fails each one `fenced` (`intentFailed`), unpublished.
|
|
2297
2420
|
/** Refuses an own envelope while the gate is closed: `commit-pending`, reason `awaiting-sync` (retryable). */
|
|
2298
|
-
function assertSendGateOpen(rt, operation) {
|
|
2421
|
+
export function assertSendGateOpen(rt, operation) {
|
|
2299
2422
|
if (rt.sendGateOpen)
|
|
2300
2423
|
return;
|
|
2301
2424
|
throw new MarmotError('commit-pending', `${operation}: group ${rt.groupId} has not completed its first sync since it was loaded; nothing is encrypted before it`, {
|
|
@@ -2387,9 +2510,7 @@ export async function failAwaitingIntents(rt) {
|
|
|
2387
2510
|
const fence = rt.fence;
|
|
2388
2511
|
if (fence === undefined)
|
|
2389
2512
|
return;
|
|
2390
|
-
|
|
2391
|
-
waiter.reject(fencedError(rt.groupId, 'synced', fence));
|
|
2392
|
-
rt.syncWaiters.clear();
|
|
2513
|
+
rejectSyncWaitersFenced(rt);
|
|
2393
2514
|
const failed = await rt.guard.call(rt.groupId, 'store', () => rt.groupStore.transaction(async (tx) => {
|
|
2394
2515
|
const view = tx.artifact('pendingIntents');
|
|
2395
2516
|
const awaiting = (await listPendingIntentRecords(view)).filter((r) => r.state === 'awaiting-sync');
|
|
@@ -2714,7 +2835,7 @@ export async function setAdminsIntent(rt, accounts, operation = 'setAdmins') {
|
|
|
2714
2835
|
await driveIntent(rt, record, true);
|
|
2715
2836
|
}
|
|
2716
2837
|
/** The admin-commit pre-check shared by `rename` and `removeMember`: `invalid-options` / `not-admin` unless `selfPubkey` is an active admin, before anything is recorded. */
|
|
2717
|
-
function assertLocalAdmin(rt, operation, selfPubkey) {
|
|
2838
|
+
export function assertLocalAdmin(rt, operation, selfPubkey) {
|
|
2718
2839
|
const adminView = getMarmotGroupView(rt.engine.state);
|
|
2719
2840
|
if (adminView === null || !isActiveAdmin(rt.engine.state.ratchetTree, adminView.adminPubkeys, selfPubkey)) {
|
|
2720
2841
|
throw new MarmotError('invalid-options', `${operation}: the local account is not an admin of group ${rt.groupId}`, { details: { groupId: rt.groupId, reason: 'not-admin' } });
|
|
@@ -3124,7 +3245,7 @@ export function scheduleProposalDeadlineCheck(rt) {
|
|
|
3124
3245
|
* refuses it too (reason `selfremove-election-wait`), checked first — never asking `onProposal` about a
|
|
3125
3246
|
* foreign proposal while the commit is going to be refused anyway.
|
|
3126
3247
|
*/
|
|
3127
|
-
async function applyProposalPolicy(rt, operation) {
|
|
3248
|
+
export async function applyProposalPolicy(rt, operation) {
|
|
3128
3249
|
if (awaitingElectedSelfRemove(rt)) {
|
|
3129
3250
|
throw new MarmotError('commit-pending', `${operation}: group ${rt.groupId}'s staged proposals are a SelfRemove batch another member is elected to commit; waiting up to ${String(rt.ctx.selfRemoveElectionWaitMs)}ms`, {
|
|
3130
3251
|
details: { groupId: rt.groupId, reason: 'selfremove-election-wait', retryable: true },
|
|
@@ -14,6 +14,12 @@ export type ConsumerSurface = 'store' | 'signer' | 'verifier' | 'onConfirm'
|
|
|
14
14
|
* waits for it.
|
|
15
15
|
*/
|
|
16
16
|
| 'deviceOperation';
|
|
17
|
+
/**
|
|
18
|
+
* The consumer-supplied surfaces that run inside a group operation, on that group's queue: their live frame (on ANY
|
|
19
|
+
* group) blocks an operation that would queue behind it — a `devices.*` op (S3, AC-RE-2) or a recovery read
|
|
20
|
+
* (epic marmot-invitation-outcomes SC-9). The one list both refusals read.
|
|
21
|
+
*/
|
|
22
|
+
export declare const GROUP_CONSUMER_SURFACES: readonly ConsumerSurface[];
|
|
17
23
|
/** Scope key of account-level operations (group operations use their group id). */
|
|
18
24
|
export declare const ACCOUNT_SCOPE = "\0account";
|
|
19
25
|
/** Scope key of the device service's serial queue (`devices.*` operations and their background passes, S8). */
|
|
@@ -47,6 +47,12 @@
|
|
|
47
47
|
* Per-instance state only (INV-NO-SINGLETONS): one guard per client.
|
|
48
48
|
*/
|
|
49
49
|
import { MarmotError } from '../shared/index.js';
|
|
50
|
+
/**
|
|
51
|
+
* The consumer-supplied surfaces that run inside a group operation, on that group's queue: their live frame (on ANY
|
|
52
|
+
* group) blocks an operation that would queue behind it — a `devices.*` op (S3, AC-RE-2) or a recovery read
|
|
53
|
+
* (epic marmot-invitation-outcomes SC-9). The one list both refusals read.
|
|
54
|
+
*/
|
|
55
|
+
export const GROUP_CONSUMER_SURFACES = Object.freeze(['onConfirm', 'onBeforePublish', 'verifier', 'onProposal']);
|
|
50
56
|
/** Scope key of account-level operations (group operations use their group id). */
|
|
51
57
|
export const ACCOUNT_SCOPE = '\u0000account';
|
|
52
58
|
/** Scope key of the device service's serial queue (`devices.*` operations and their background passes, S8). */
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
import { type ClientState } from '@941design/marmot-engine/mls';
|
|
2
|
+
import type { KeyValueView, Storable } from '../storage/index.js';
|
|
3
|
+
import { type RetainedWindow, type WindowNode } from './retained-window.js';
|
|
4
|
+
/** Group extension holding one {@link AdmissionLineageRecord} per anchor, keyed `<addDigest>:<leafIndex>`. */
|
|
5
|
+
export declare const ADMISSION_LINEAGE_EXTENSION = "marmot.admission-lineage";
|
|
6
|
+
/** Where one Add put its leaf (structurally the invitations module's `AddAnchor`, SC-1 I3). */
|
|
7
|
+
export interface LineageAnchor {
|
|
8
|
+
/** Hex SHA-256 of the Add commit's MLS wire bytes. */
|
|
9
|
+
readonly addDigest: string;
|
|
10
|
+
/** Hex confirmation tag of the state the Add produced (its node in the rewind window). */
|
|
11
|
+
readonly addTag: string;
|
|
12
|
+
readonly commitEventId: string;
|
|
13
|
+
/** Leaf position in `addTag`'s state. */
|
|
14
|
+
readonly leafIndex: number;
|
|
15
|
+
/** Hex signature key of the added leaf. */
|
|
16
|
+
readonly leafKey: string;
|
|
17
|
+
}
|
|
18
|
+
/** Why an admission's occupancy cannot be proven. */
|
|
19
|
+
export type LineageGapReason = 'unprovable-root' | 'undecodable-commit' | 'restore' | 'switch';
|
|
20
|
+
/** How the occupancy that ended an admission ended. */
|
|
21
|
+
export type LineageEndedBy = 'inline-remove' | 'replaced' | 'by-reference';
|
|
22
|
+
/** The occupancy of one admission at one node of the selected path. */
|
|
23
|
+
export type LineageOccupancy = {
|
|
24
|
+
readonly kind: 'occupying';
|
|
25
|
+
readonly leafKey: string;
|
|
26
|
+
} | {
|
|
27
|
+
readonly kind: 'ended';
|
|
28
|
+
readonly digest: string;
|
|
29
|
+
readonly by: LineageEndedBy;
|
|
30
|
+
readonly committerOwn: boolean;
|
|
31
|
+
} | {
|
|
32
|
+
readonly kind: 'add-off-path';
|
|
33
|
+
} | {
|
|
34
|
+
readonly kind: 'gap';
|
|
35
|
+
readonly reason: LineageGapReason;
|
|
36
|
+
};
|
|
37
|
+
/** Where a checkpoint's occupancy came from: authenticated transitions of this store, or an imported snapshot. */
|
|
38
|
+
export type LineageProvenance = 'transition' | 'snapshot';
|
|
39
|
+
export interface LineageCheckpoint {
|
|
40
|
+
readonly at: {
|
|
41
|
+
readonly tag: string;
|
|
42
|
+
readonly epoch: number;
|
|
43
|
+
};
|
|
44
|
+
readonly occupancy: LineageOccupancy;
|
|
45
|
+
readonly provenance: LineageProvenance;
|
|
46
|
+
}
|
|
47
|
+
/** SC-4: one admission's durable lineage (group extension `marmot.admission-lineage`). */
|
|
48
|
+
export interface AdmissionLineageRecord {
|
|
49
|
+
readonly v: 1;
|
|
50
|
+
readonly anchor: LineageAnchor;
|
|
51
|
+
/** The decline candidates (deliveries) this Add admitted — each delivery of the Add with this anchor. */
|
|
52
|
+
readonly candidateIds: readonly string[];
|
|
53
|
+
/**
|
|
54
|
+
* The occupancy at a node of the selected path. Seeded at the Add node itself (occupying, `transition`); moved only
|
|
55
|
+
* to a new window root, inside `recordTransition`'s transaction. Absent: the Add node is the only evidence.
|
|
56
|
+
*/
|
|
57
|
+
readonly checkpoint?: LineageCheckpoint;
|
|
58
|
+
}
|
|
59
|
+
/** The record key of `anchor`. */
|
|
60
|
+
export declare function lineageKey(anchor: Pick<LineageAnchor, 'addDigest' | 'leafIndex'>): string;
|
|
61
|
+
/** The record an own Add confirmation seeds: the Add node (at `addEpoch`) is its checkpoint, occupying. */
|
|
62
|
+
export declare function seedLineage(anchor: LineageAnchor, candidateIds: readonly string[], addEpoch: number): AdmissionLineageRecord;
|
|
63
|
+
/**
|
|
64
|
+
* `stored` with `seed`'s candidates merged in, or `seed` when nothing is stored. A stored record keeps its checkpoint
|
|
65
|
+
* (idempotent: a re-run confirmation never moves an advanced checkpoint back to the Add). `undefined` when `stored`
|
|
66
|
+
* already holds every candidate (nothing to write).
|
|
67
|
+
*/
|
|
68
|
+
export declare function mergeSeed(stored: AdmissionLineageRecord | undefined, seed: AdmissionLineageRecord): AdmissionLineageRecord | undefined;
|
|
69
|
+
/** One link of the selected path: the commit from `parent` to `child`, as the window holds it. */
|
|
70
|
+
export interface LineageLink {
|
|
71
|
+
/** The child node (its `commit`, `digest`). */
|
|
72
|
+
readonly node: WindowNode;
|
|
73
|
+
/** The parent's state (the commit was built from it: its staged proposals, its own leaf). */
|
|
74
|
+
parentState(): ClientState | undefined;
|
|
75
|
+
/** The child's state (the commit's result). */
|
|
76
|
+
childState(): ClientState | undefined;
|
|
77
|
+
}
|
|
78
|
+
/** Hex signature key of the leaf at `leafIndex` of `state`, or `undefined` when the leaf is blank (or out of range). */
|
|
79
|
+
export declare function leafKeyAt(state: ClientState, leafIndex: number): string | undefined;
|
|
80
|
+
/**
|
|
81
|
+
* I10: the occupancy after one commit of the selected path. Only an `occupying` admission moves; every other
|
|
82
|
+
* occupancy is final for the walk. The commit must be a framed PublicMessage commit whose digest matches its stored
|
|
83
|
+
* one, every proposal reference must resolve against the parent's staged proposals, and both states must be at hand
|
|
84
|
+
* — otherwise `gap` (`undecodable-commit`). A Remove of the position (inline, by reference, or the leaf's own
|
|
85
|
+
* `self_remove`) ends it: `by-reference` when any such Remove came by reference, `replaced` when the same commit put
|
|
86
|
+
* a leaf back at the position, else `inline-remove`; `committerOwn` when this device committed it. Otherwise the leaf
|
|
87
|
+
* must still be there, and a changed signature key needs an Update by the leaf or the leaf's own commit (a path
|
|
88
|
+
* succession) — a leaf that changes or vanishes any other way is a `gap`. Never throws.
|
|
89
|
+
*/
|
|
90
|
+
export declare function admissionStep(occupancy: LineageOccupancy, link: LineageLink, leafIndex: number): LineageOccupancy;
|
|
91
|
+
/** What the selected path of a window proves about one admission. */
|
|
92
|
+
export interface AdmissionDerivation {
|
|
93
|
+
readonly occupancy: LineageOccupancy;
|
|
94
|
+
/** `snapshot` when the proof starts at a checkpoint an imported snapshot supplied (never settled until re-proven). */
|
|
95
|
+
readonly provenance: LineageProvenance;
|
|
96
|
+
/** The node the derivation reached (the window's tip, or `upTo`). */
|
|
97
|
+
readonly at: {
|
|
98
|
+
readonly tag: string;
|
|
99
|
+
readonly epoch: number;
|
|
100
|
+
};
|
|
101
|
+
/**
|
|
102
|
+
* For an `ended` occupancy whose ending commit is still on the derived path: how many commits follow it there.
|
|
103
|
+
* Absent when the end was carried by a checkpoint (its commit already left the window).
|
|
104
|
+
*/
|
|
105
|
+
readonly endedDepth?: number;
|
|
106
|
+
}
|
|
107
|
+
/** A cache of the window's deserialized states (the tip is `tipState`), shared by every derivation over that window. */
|
|
108
|
+
export type StateResolver = (node: WindowNode) => ClientState | undefined;
|
|
109
|
+
export declare function stateResolver(window: RetainedWindow, tipState: ClientState | undefined): StateResolver;
|
|
110
|
+
/**
|
|
111
|
+
* The occupancy of `record`'s admission at the tip of `window`'s selected path (`tipState` is the tip's state, the
|
|
112
|
+
* stored `clientState`), or at the path node `upTo`. The proof starts at the Add node when it is on the path, else at
|
|
113
|
+
* the checkpoint when its node is on the path (same epoch), and walks every later commit with {@link admissionStep}.
|
|
114
|
+
*
|
|
115
|
+
* - The Add node is in the window but off the path, or the record only holds its seed (the Add node itself) and the
|
|
116
|
+
* path covers the Add's epoch with another node or ends below it: `add-off-path` (the Add may return to the path).
|
|
117
|
+
* - Neither the Add nor the checkpoint is on the path otherwise: `gap` (`unprovable-root`) — fail closed (I12).
|
|
118
|
+
* - The start state must hold the admission's leaf at its position under the recorded key, and a derivation ending
|
|
119
|
+
* `occupying` must find that leaf on the end state; otherwise `gap`.
|
|
120
|
+
* - A proof that starts at an `occupying` checkpoint of `snapshot` provenance is re-checked against the window as a
|
|
121
|
+
* restore validates it (`snapshotCheckpointHolds`); one the window refutes is a `gap` (`restore`).
|
|
122
|
+
*/
|
|
123
|
+
export declare function deriveAdmission(record: Pick<AdmissionLineageRecord, 'anchor' | 'checkpoint'>, window: RetainedWindow, tipState: ClientState | undefined, upTo?: string): AdmissionDerivation;
|
|
124
|
+
/**
|
|
125
|
+
* One window holding every node of `windows`, tip `tipTag`. A node several windows hold keeps the version with a
|
|
126
|
+
* parent link (a window's root is stored without one) and with a snapshot when one has it.
|
|
127
|
+
*/
|
|
128
|
+
export declare function mergeWindows(tipTag: string, windows: readonly RetainedWindow[]): RetainedWindow;
|
|
129
|
+
/** The root of `window`'s selected path. */
|
|
130
|
+
export declare function windowRootOf(window: RetainedWindow): WindowNode | undefined;
|
|
131
|
+
/**
|
|
132
|
+
* I11: `record` with its checkpoint moved to the root of `after` (the window a transition persists, whose tip state is
|
|
133
|
+
* `afterTip`), or `undefined` when it needs no move. A move is needed only when `after` alone no longer proves what
|
|
134
|
+
* the record proved — neither its Add nor its checkpoint is left on `after`'s path, and `after`'s root is not already
|
|
135
|
+
* the checkpoint. The occupancy at the new root is derived over every node the transition saw (`before`, the window
|
|
136
|
+
* it diffed against, and `after`), starting where the record's proof starts. What cannot be bridged becomes a `gap`
|
|
137
|
+
* checkpoint at the new root: `switch` when the new path shares no node with `before` (a branch switch), else
|
|
138
|
+
* `unprovable-root`. A checkpoint derived from a snapshot-supplied checkpoint keeps `snapshot` provenance.
|
|
139
|
+
*/
|
|
140
|
+
export declare function advanceLineage(record: AdmissionLineageRecord, windows: {
|
|
141
|
+
readonly before: RetainedWindow;
|
|
142
|
+
readonly diff?: RetainedWindow;
|
|
143
|
+
readonly after: RetainedWindow;
|
|
144
|
+
}, afterTip: ClientState | undefined): AdmissionLineageRecord | undefined;
|
|
145
|
+
/**
|
|
146
|
+
* The lineage a restore adopts from a snapshot's `records`, validated against the snapshot's own selected path
|
|
147
|
+
* (`window`, tip state `tipState`). A record whose Add is on that path is kept (the window proves it). A record whose
|
|
148
|
+
* checkpoint names a node of that path at its epoch is kept with `snapshot` provenance when the window cannot refute
|
|
149
|
+
* it — for an `occupying` checkpoint: the Add is nowhere in the window, and the position's occupant is carried from
|
|
150
|
+
* the window's root to that node, without a Remove or an unprovable link, under the claimed key
|
|
151
|
+
* ({@link snapshotCheckpointHolds}). Every other record gets a `gap` (`restore`) checkpoint at the window's root:
|
|
152
|
+
* insufficient evidence until a transition re-proves it from the Add. A record of a duplicate key keeps its first
|
|
153
|
+
* occurrence.
|
|
154
|
+
*/
|
|
155
|
+
export declare function validateRestoredLineage(records: readonly AdmissionLineageRecord[], window: RetainedWindow, tipState: ClientState): AdmissionLineageRecord[];
|
|
156
|
+
/** Decodes one stored (or snapshot-carried) record strictly: anything else throws a malformed-row error. */
|
|
157
|
+
export declare function decodeLineageRecord(where: string, raw: unknown): AdmissionLineageRecord;
|
|
158
|
+
export declare function encodeLineageRecord(record: AdmissionLineageRecord): Storable;
|
|
159
|
+
/**
|
|
160
|
+
* Every decodable record of the extension view. A row that does not open or decode is skipped — no record is no
|
|
161
|
+
* evidence, so the admission it described reads as a gap (fail closed); any other read error propagates.
|
|
162
|
+
*/
|
|
163
|
+
export declare function readLineageRecords(view: KeyValueView): Promise<AdmissionLineageRecord[]>;
|
|
164
|
+
/** The record at `key`, `undefined` when absent or malformed (envelope or payload); other read errors propagate. */
|
|
165
|
+
export declare function readLineageRecord(view: KeyValueView, key: string): Promise<AdmissionLineageRecord | undefined>;
|
|
166
|
+
export declare function writeLineageRecord(view: KeyValueView, record: AdmissionLineageRecord): Promise<void>;
|
|
167
|
+
/**
|
|
168
|
+
* Seeds the lineage of the anchors an own Add commit confirmed (in the confirmation's group transaction):
|
|
169
|
+
* `anchors` maps each anchor to the candidates it admitted; `addEpoch` is the epoch of the Add's state.
|
|
170
|
+
* Idempotent: a re-run confirmation only merges candidates into a stored record and never moves its checkpoint.
|
|
171
|
+
*/
|
|
172
|
+
export declare function seedLineageRecords(view: KeyValueView, anchors: ReadonlyMap<string, {
|
|
173
|
+
readonly anchor: LineageAnchor;
|
|
174
|
+
readonly candidateIds: readonly string[];
|
|
175
|
+
}>, addEpoch: number): Promise<void>;
|
|
176
|
+
/**
|
|
177
|
+
* I11, the shell: moves every stored record's checkpoint the transition needs moved ({@link advanceLineage}), in the
|
|
178
|
+
* transition's own transaction. Records that need no move are not rewritten.
|
|
179
|
+
*/
|
|
180
|
+
export declare function advanceLineageRecords(view: KeyValueView, windows: {
|
|
181
|
+
readonly before: RetainedWindow;
|
|
182
|
+
readonly diff?: RetainedWindow;
|
|
183
|
+
readonly after: RetainedWindow;
|
|
184
|
+
}, afterTip: ClientState | undefined): Promise<void>;
|
|
185
|
+
/** Replaces the extension's records with `records` (a restore's adoption, inside its transaction). */
|
|
186
|
+
export declare function replaceLineageRecords(view: KeyValueView, records: readonly AdmissionLineageRecord[]): Promise<void>;
|