@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.
Files changed (63) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/dist/account/teardown.d.ts +66 -3
  3. package/dist/account/teardown.js +24 -2
  4. package/dist/client/admission-cleanup.d.ts +197 -0
  5. package/dist/client/admission-cleanup.js +635 -0
  6. package/dist/client/adoption-proof.d.ts +39 -0
  7. package/dist/client/adoption-proof.js +102 -0
  8. package/dist/client/before-publish-hooks.js +3 -1
  9. package/dist/client/commit-redrive.d.ts +28 -4
  10. package/dist/client/commit-redrive.js +54 -1
  11. package/dist/client/confirm-hooks.d.ts +6 -1
  12. package/dist/client/confirm-hooks.js +15 -0
  13. package/dist/client/create-client.d.ts +107 -3
  14. package/dist/client/create-client.js +114 -7
  15. package/dist/client/group-availability.d.ts +182 -0
  16. package/dist/client/group-availability.js +301 -0
  17. package/dist/client/group-history.d.ts +26 -0
  18. package/dist/client/group-history.js +77 -7
  19. package/dist/client/group-records.d.ts +39 -2
  20. package/dist/client/group-records.js +88 -5
  21. package/dist/client/group-runtime.d.ts +30 -3
  22. package/dist/client/group-runtime.js +131 -21
  23. package/dist/client/group-snapshot.d.ts +7 -1
  24. package/dist/client/group-snapshot.js +23 -2
  25. package/dist/client/index.d.ts +4 -1
  26. package/dist/client/ingest.js +47 -13
  27. package/dist/client/invitation-outcomes.d.ts +50 -0
  28. package/dist/client/invitation-outcomes.js +135 -0
  29. package/dist/client/opaque-candidates.d.ts +2 -1
  30. package/dist/client/opaque-candidates.js +2 -1
  31. package/dist/client/own-change-outbox.js +2 -0
  32. package/dist/client/pipeline.d.ts +30 -1
  33. package/dist/client/pipeline.js +142 -21
  34. package/dist/client/reentrancy-guard.d.ts +6 -0
  35. package/dist/client/reentrancy-guard.js +6 -0
  36. package/dist/history/admission-lineage.d.ts +186 -0
  37. package/dist/history/admission-lineage.js +589 -0
  38. package/dist/history/fencing.d.ts +41 -0
  39. package/dist/history/fencing.js +67 -7
  40. package/dist/history/index.d.ts +2 -1
  41. package/dist/history/index.js +2 -1
  42. package/dist/history/own-change.d.ts +13 -1
  43. package/dist/invitations/decline.d.ts +8 -2
  44. package/dist/invitations/decline.js +9 -3
  45. package/dist/invitations/delivery-evidence.d.ts +288 -0
  46. package/dist/invitations/delivery-evidence.js +766 -0
  47. package/dist/invitations/index.d.ts +4 -2
  48. package/dist/invitations/index.js +4 -2
  49. package/dist/invitations/invitation-outcome.d.ts +110 -0
  50. package/dist/invitations/invitation-outcome.js +210 -0
  51. package/dist/invitations/invite.d.ts +61 -6
  52. package/dist/invitations/invite.js +187 -51
  53. package/dist/invitations/welcome-processor.d.ts +20 -1
  54. package/dist/invitations/welcome-processor.js +81 -20
  55. package/dist/shared/errors.d.ts +7 -0
  56. package/dist/shared/errors.js +11 -0
  57. package/dist/shared/index.d.ts +1 -1
  58. package/dist/shared/index.js +1 -1
  59. package/dist/storage/index.d.ts +10 -0
  60. package/dist/storage/index.js +33 -1
  61. package/dist/storage/lease.d.ts +13 -0
  62. package/dist/storage/lease.js +51 -0
  63. package/package.json +2 -2
@@ -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 { announceTerminals, assertNotFenced, deliverTransition, dispatch, fenceGroup, lostMessagePlan, parkWithdrawnWelcomes, planTransition, recordEquivocations, recordTransition, sentOnCanonicalBranch, WITHDRAWN_DISPOSITION } from './group-history.js';
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 || intent.invite !== undefined || intent.admins !== undefined || intent.profile !== undefined || intent.components !== undefined || record.changes !== 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({ inviteId: record.intentId, groupId: rt.groupId, commitEventId: envelope.id, ...(newState === undefined ? {} : { commitTag: tagOf(newState) }), welcomes }));
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) => writePendingIntentRecord(tx.artifact('pendingIntents'), record)));
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
- const base = { state, window: rt.window, windowTip: rt.exposedState, authorIsAdmin, forkEpoch: record.forkEpoch ?? 0 };
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
- for (const waiter of rt.syncWaiters)
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>;