@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
@@ -27,8 +27,8 @@
27
27
  import { deserializeClientState, getGroupIdHex, serializeClientState } from '@941design/marmot-engine/core';
28
28
  import { authenticatedSenderOf, resolveCandidateParent } from '@941design/marmot-engine/engine';
29
29
  import { acceptAll, nodeTypes, wireformats } from '@941design/marmot-engine/mls';
30
- import { commitOf, linkRestorable, restoreHistory, REWIND_HORIZON, senderOfStored, tagOf } from '../history/index.js';
31
- import { MarmotError } from '../shared/index.js';
30
+ import { commitOf, decodeLineageRecord, encodeLineageRecord, linkRestorable, restoreHistory, REWIND_HORIZON, senderOfStored, tagOf, } from '../history/index.js';
31
+ import { isMalformedRowError, MarmotError } from '../shared/index.js';
32
32
  import { CURRENT_CODEC_VERSIONS, openEnvelope, sealEnvelope } from '../storage/index.js';
33
33
  /** Payload discriminator: an envelope of any other content is not a group snapshot. */
34
34
  const SNAPSHOT_KIND = 'marmot.groupSnapshot';
@@ -116,6 +116,8 @@ export function sealGroupSnapshot(content, versions = CURRENT_CODEC_VERSIONS) {
116
116
  // The tip node carries no snapshot of its own (`clientState` is it), exactly as the stored window's tip.
117
117
  payload['window'] = { tip: window.tipTag, nodes: [...window.nodes.values()].map(encodeNode) };
118
118
  }
119
+ if (content.lineage !== undefined && content.lineage.length > 0)
120
+ payload['lineage'] = content.lineage.map(encodeLineageRecord);
119
121
  return sealEnvelope(payload, versions);
120
122
  }
121
123
  /**
@@ -194,6 +196,7 @@ export function openGroupSnapshot(raw, versions = CURRENT_CODEC_VERSIONS) {
194
196
  throw malformed(`the serialized state is of group ${stateGroupId}, not the payload's ${groupId}`);
195
197
  const window = r['window'] === undefined ? undefined : decodeWindow(r['window'], state, groupId);
196
198
  const pending = decodePending(kind === PENDING_SNAPSHOT_KIND, rawPending, window);
199
+ const lineage = decodeLineage(r['lineage']);
197
200
  return {
198
201
  groupId,
199
202
  state,
@@ -201,8 +204,26 @@ export function openGroupSnapshot(raw, versions = CURRENT_CODEC_VERSIONS) {
201
204
  ...(since === undefined ? {} : { since }),
202
205
  ...(window === undefined ? {} : { window }),
203
206
  ...(pending === undefined ? {} : { pending }),
207
+ ...(lineage === undefined ? {} : { lineage }),
204
208
  };
205
209
  }
210
+ /** The payload's admission lineage: absent, or a list of well-formed records (anything else is a malformed snapshot). */
211
+ function decodeLineage(raw) {
212
+ if (raw === undefined)
213
+ return undefined;
214
+ if (!Array.isArray(raw))
215
+ throw malformed('lineage is not a list');
216
+ return raw.map((entry, i) => {
217
+ try {
218
+ return decodeLineageRecord(`groupSnapshot.lineage[${i}]`, entry);
219
+ }
220
+ catch (error) {
221
+ if (isMalformedRowError(error))
222
+ throw malformed(`lineage record ${i} is malformed`, error);
223
+ throw error;
224
+ }
225
+ });
226
+ }
206
227
  /**
207
228
  * The payload's pending marker. A confirmed-kind payload carries none (a `pending` field on it is malformed: it would
208
229
  * be a pending claim an older build would not see as one); a pending-kind payload carries a well-formed marker whose
@@ -3,7 +3,7 @@
3
3
  * `@941design/marmot`'s surface (docs/client-api.md); `getClientContext` and
4
4
  * the other internals of `create-client.ts` stay module-private.
5
5
  */
6
- export { createMarmotClient, type ClientClock, type ClientOptions, type ClientTimers, type ConfirmContext, type ConfirmHook, type ConfirmKind, type GroupDisbanded, type GroupNotification, type ClientStores, type EncryptedMedia, type EventVerifier, type GroupIntent, type GroupSnapshot, type InboxHandler, type InboxRumorDelivery, type IngestDisposition, type LeafInfo, type MarmotClient, type MarmotClientEventName, type MarmotClientEvents, type MarmotClientOptions, type MarmotGroup, type OrderingKey, type PendingIntent, type RelayOptions, type WelcomeManifest, } from './create-client.js';
6
+ export { createMarmotClient, type AvailabilityEndReason, type AvailabilityObservation, type ClientClock, type ClientOptions, type ClientTimers, type ConfirmContext, type ConfirmHook, type ConfirmKind, type GroupDisbanded, type GroupNotification, type ClientStores, type EncryptedMedia, type EventVerifier, type FenceCause, type GroupAvailability, type GroupIntent, type GroupSnapshot, type InboxHandler, type InboxRumorDelivery, type IngestDisposition, type LeafInfo, type MarmotClient, type MarmotClientEventName, type MarmotClientEvents, type MarmotClientOptions, type MarmotGroup, type OrderingKey, type PendingIntent, type RelayOptions, type WelcomeManifest, } from './create-client.js';
7
7
  export { MarmotError, isMarmotError, MARMOT_ERROR_CODES, type MarmotErrorCode, RUMOR_KINDS, type RumorKind, type RumorKindConstants, } from '../shared/index.js';
8
8
  export { permissions } from './permissions.js';
9
9
  export { groupProfileProposal, type GroupProfile } from './group-profile.js';
@@ -17,5 +17,8 @@ export type { BeforePublishContext, BeforePublishHook, BeforePublishSkipped, Bef
17
17
  export type { MaintenanceKind, PendingInvitation, PendingProposal, ProposalCallback, ProposalDecision, WelcomeOutcome } from '../invitations/index.js';
18
18
  export type { InboxDisposition, InboxRumorHandler, RumorDisposition } from '../inbox/index.js';
19
19
  export type { KeyPackageOffer } from '../invitations/index.js';
20
+ export type { InvitationOutcome } from '../invitations/index.js';
21
+ export type { CleanupReference, DeclineCandidate, DeclineCandidatePage } from '../invitations/index.js';
22
+ export type { CleanupDisposition, CleanupDispositionCause, CleanupDispositionReport } from './admission-cleanup.js';
20
23
  export type { DeviceForgetGroupOutcome, DeviceForgetOutcome, DeviceInfo, DeviceKeyRotationOutcome, DeviceKeyRotationOutcomeStatus, DeviceMaintenanceKind, DeviceTombstone, EnrolmentApprovalOutcome, EnrolmentGroupOutcome, EnrolmentPrompt, EnrolmentRequestHandle, EnrolmentRequestOptions, } from '../account/index.js';
21
24
  export type { DeviceKeyRotationGroupOutcome } from '../key-packages/index.js';
@@ -1,15 +1,15 @@
1
1
  import { deserializeApplicationData, deserializeClientState, getMarmotGroupView, getNostrGroupIdHex, serializeClientState, } from '@941design/marmot-engine/core';
2
2
  import { enforceStagedProposals, enforceStateTransition } from '../account/index.js';
3
- import { canonicalPath, captureWindow, equivocationNotification, fencingErrorIn, orderingKeyOf, restrictWindow, REWIND_HORIZON, sameWindow, tagOf, writeEquivocation, writeFence, writeWindow, EQUIVOCATION_EXTENSION, FENCE_EXTENSION, } from '../history/index.js';
4
- import { announceNotifications, deliverTransition, fenceGroup, noteEquivocations, planTransition, recordEquivocations, recordTransition, retainedLedgerNodes, WITHDRAWN_DISPOSITION } from './group-history.js';
3
+ import { canonicalPath, captureWindow, equivocationNotification, fenceCauseOf, fencingErrorIn, orderingKeyOf, restrictWindow, REWIND_HORIZON, sameWindow, tagOf, writeEquivocation, writeFence, writeWindow, EQUIVOCATION_EXTENSION, FENCE_EXTENSION, } from '../history/index.js';
4
+ import { announceNotifications, deliverTransition, fenceGroup, noteEquivocations, rejectSyncWaitersFenced, planTransition, recordEquivocations, recordTransition, retainedLedgerNodes, WITHDRAWN_DISPOSITION } from './group-history.js';
5
5
  import { recordSelectedDisband } from './group-disband.js';
6
6
  import { listPendingIntentRecords, markRatchetSkipDelivered, OWN_COMMIT_EXTENSION, pruneOwnCommitMarkers, pruneTerminalLedger, RATCHET_SKIP_EXTENSION, readIngestCursor, readTerminalLedgerEntry, writeGroupState, writeIngestCursor, writeTerminalLedgerEntry, } from './group-records.js';
7
7
  import { clearRemoval, nextHeldRemoval, REMOVAL_EXTENSION, settlesAt, writeRemoval } from './group-removal.js';
8
8
  import { clearOpaque, isEmptyOpaque, nextOpaque, OPAQUE_EXTENSION, writeOpaque } from './opaque-candidates.js';
9
9
  import { clearPendingCommit, dropPendingLeaf, ledgerOwnCopies, PENDING_COMMIT_EXTENSION, pendingWatch, reinstatable, reinstatePendingLeaf } from './pending-leaf.js';
10
10
  import { EXCLUDED_PROPOSALS_EXTENSION, exclusionsAt, readExclusions } from '../invitations/index.js';
11
- import { MarmotError } from '../shared/index.js';
12
- import { assertNotDisposed, backoffMs, electionOf, expireDeferredProposals, failAwaitingIntents, MAX_TIMER_DELAY_MS, releaseAwaitingSync, releaseQueueCommitHold, releaseSelfRemoveElectionWait, reportStrandedSelfUpdateReenqueues, resumePending, scheduleDeferredReenqueueRetry, scheduleSelfRemoveCommit, scheduleWithdrawnRedrives, takeStrandedSelfUpdateReenqueues, } from './pipeline.js';
11
+ import { isMarmotError, MarmotError } from '../shared/index.js';
12
+ import { assertNotDisposed, backgroundRetryEnds, backoffMs, electionOf, expireDeferredProposals, failAwaitingIntents, MAX_TIMER_DELAY_MS, releaseAwaitingSync, releaseQueueCommitHold, releaseSelfRemoveElectionWait, reportStrandedSelfUpdateReenqueues, resumePending, scheduleDeferredReenqueueRetry, scheduleSelfRemoveCommit, scheduleWithdrawnRedrives, takeStrandedSelfUpdateReenqueues, } from './pipeline.js';
13
13
  import { HISTORY_LIVE_AFTER_WALK_PASSES, HISTORY_MAX_PAGES, HISTORY_REWALK_SLACK_PAGES, fetchHistoryPages } from './history-pages.js';
14
14
  import { CURSOR_FUTURE_SKEW_S, CURSOR_REDELIVERY_MARGIN_S, GROUP_EVENT_KIND, LEDGER_RETENTION_S, absentPins, groupEventFilter, groupRelayPlane, nextCursor, } from './transport-policy.js';
15
15
  /**
@@ -410,7 +410,7 @@ export async function drainConvergence(rt) {
410
410
  async function fenceFromDrive(rt, fence, reported) {
411
411
  if (rt.fence === undefined) {
412
412
  // A failed marker write still fences this session and marks the runtime for a reload (see fenceGroup).
413
- await fenceGroup(rt, fence).finally(() => stopGroupSync(rt));
413
+ await fenceGroup(rt, fence).finally(() => stopGroupSyncQuietly(rt));
414
414
  }
415
415
  await rt.reloadFromDurable();
416
416
  await recordEquivocations(rt, reported).catch(() => undefined);
@@ -798,7 +798,8 @@ export async function ingestEvents(rt, events, opts) {
798
798
  // previous window's floor.
799
799
  const span = Number(finalState.groupContext.epoch) - (canonicalPath(windowBefore)[0]?.epoch ?? 0);
800
800
  const diffWindow = window !== undefined && span > REWIND_HORIZON ? await captureWindow(rt.engine.history, finalState, span, windowBefore) : undefined;
801
- const fenceRecord = fence === undefined ? undefined : { at: rt.ctx.clock.now(), epoch: String(finalState.groupContext.epoch), message: fence.message };
801
+ // Epic marmot-invitation-outcomes S1: the marker records the fence's coarse cause (additive on v:1).
802
+ const fenceRecord = fence === undefined ? undefined : { at: rt.ctx.clock.now(), epoch: String(finalState.groupContext.epoch), message: fence.message, cause: fenceCauseOf(fence) };
802
803
  // AC-HIST-2/3: what the batch applied, withdrew and delivered — planned now, announced once it is durable.
803
804
  const plan = await planTransition(rt, windowBefore, stateBefore, window ?? windowBefore, finalState, [...messages.values()], retracted, diffWindow ?? window ?? windowBefore);
804
805
  // AC-RATCH-1 (BACKLOG ratchet-skip-undelivered-marker-horizon-rearm, step 1): during the first post-load sync of
@@ -866,8 +867,9 @@ export async function ingestEvents(rt, events, opts) {
866
867
  rt.ratchetSkipPending = true;
867
868
  if (fence !== undefined) {
868
869
  rt.fence = fence;
869
- // Nothing it fetches could ever be processed again.
870
- stopGroupSync(rt);
870
+ // Nothing it fetches could ever be processed again. The batch is committed: a failing transport unsubscribe
871
+ // must not reach the catch below, which would take the committed batch back.
872
+ stopGroupSyncQuietly(rt);
871
873
  }
872
874
  }
873
875
  // Unchanged by content: the mirror re-points at the engine's (equal) record, so the next batch's check is an identity test again.
@@ -892,7 +894,19 @@ export async function ingestEvents(rt, events, opts) {
892
894
  });
893
895
  }
894
896
  }
895
- // Always the batch's own failure, never the rollback's.
897
+ // AC-FENCE-6 (A-7, F7): a batch that reached a fence verdict and then failed to commit still fences this session,
898
+ // as fenceGroup's failed marker write does — the durable state, opaque record and engine stay pre-batch (no marker
899
+ // was written), the session fence is recorded and published, and the next operation reloads first. A reload never
900
+ // reads clear (the fence lives on the runtime and in the session); a new client re-decides from the durable state.
901
+ // Its `synced()` waiters fail `fenced` here (in memory; the durable intent cleanup runs on the next load), and a
902
+ // failing transport unsubscribe never replaces the batch's error.
903
+ if (fence !== undefined && rt.fence === undefined) {
904
+ rt.fence = fence;
905
+ rt.needsReload = true;
906
+ rejectSyncWaitersFenced(rt);
907
+ stopGroupSyncQuietly(rt);
908
+ }
909
+ // Always the batch's own failure, never the rollback's (nor the stop's).
896
910
  throw error;
897
911
  }
898
912
  if (committed !== undefined)
@@ -1139,6 +1153,18 @@ export function stopGroupSync(rt) {
1139
1153
  }
1140
1154
  dropLiveSubscription(rt);
1141
1155
  }
1156
+ /**
1157
+ * {@link stopGroupSync} where the transport's unsubscribe failing must not replace the error or outcome of the work
1158
+ * that stopped the sync: the sync is stopped and the subscription forgotten either way, so the failure is dropped.
1159
+ */
1160
+ function stopGroupSyncQuietly(rt) {
1161
+ try {
1162
+ stopGroupSync(rt);
1163
+ }
1164
+ catch {
1165
+ // the transport's unsubscribe failed: the sync is stopped regardless
1166
+ }
1167
+ }
1142
1168
  /** A connectivity gap: not caught up, and every history pass already under way is too old to say otherwise (GroupRuntime.caughtUp). */
1143
1169
  function markConnectivityGap(rt) {
1144
1170
  rt.caughtUp = false;
@@ -1404,10 +1430,18 @@ async function historyPass(rt, attempt) {
1404
1430
  if (next === null)
1405
1431
  scheduleHistoryRetry(rt, attempt);
1406
1432
  }
1407
- catch {
1408
- // A transport-level rejection (not a `timedOut: true` result), a failed
1409
- // ingest batch, or a store call that lost its lease mid-flight — retried
1410
- // on the same backoff as an ordinary timeout, only while still syncing.
1433
+ catch (error) {
1434
+ // A store call that lost the lease (`no-lease`) is permanent for this client: the client-wide lease end — every
1435
+ // group's availability subscriptions end `no-lease`, the fallback of a store without `onLeaseEnded` — and no retry.
1436
+ // The group's sync stops with it, so no rerun or live-subscription error starts another pass against the lost lease.
1437
+ if (backgroundRetryEnds(rt, error)) {
1438
+ if (isMarmotError(error, 'no-lease'))
1439
+ stopGroupSyncQuietly(rt);
1440
+ return undefined;
1441
+ }
1442
+ // A transport-level rejection (not a `timedOut: true` result) or a
1443
+ // failed ingest batch — retried on the same backoff as an ordinary
1444
+ // timeout, only while still syncing.
1411
1445
  if (stillSyncing(rt))
1412
1446
  scheduleHistoryRetry(rt, attempt);
1413
1447
  }
@@ -0,0 +1,50 @@
1
+ /**
2
+ * `invitations.outcome(id)` (epic marmot-invitation-outcomes S2; ADR-019 D9, D10; architecture SC-8, SC-9).
3
+ *
4
+ * The read classifies ONE instant of durable state:
5
+ *
6
+ * 1. the entry guard ({@link assertRecoveryReadAllowed}) refuses, synchronously and before anything is queued, a call
7
+ * made from a frame whose queue the read would wait on (a hook or a consumer group store call inside the
8
+ * adoption's own group transaction, an inbox handler on the inbox queue, any account-scope consumer surface) — it
9
+ * would deadlock, not read;
10
+ * 2. the read runs on the inbox's serial queue, where every adopting call runs (`accept`, a Welcome's dispatch,
11
+ * `completeStuckJoins`): it never observes the inside of an adoption call. It works with the inbox never started;
12
+ * 3. a read-only GROUP transaction on the record's group holds that group's store queue (no adoption, switch or
13
+ * teardown clear runs meanwhile) while it reads the adoption proofs and awaits a read-only ACCOUNT transaction
14
+ * that reads the record, the index entry and the group's stamps (group → account, the lock order). Both
15
+ * transactions are write-free and re-assert the lease when they settle (`no-lease` once it is lost).
16
+ *
17
+ * A record that names another group inside the account transaction than the routing read saw is read again once;
18
+ * a second move rejects `store-failed`.
19
+ */
20
+ import { type InvitationOutcome } from '../invitations/index.js';
21
+ import type { AccountStore, GroupStore } from '../storage/index.js';
22
+ import { type ConsumerSurface, type ReentrancyGuard } from './reentrancy-guard.js';
23
+ /** The inbox-queue consumer surfaces (any scope). */
24
+ export declare const RECOVERY_READ_INBOX_SURFACES: readonly ConsumerSurface[];
25
+ /**
26
+ * SC-9's entry guard, evaluated synchronously: throws `reentrant` (`details: { scope, operation, surface }`) when the
27
+ * calling code runs inside any live account-scope frame, inside a group-scope frame of one of
28
+ * {@link GROUP_CONSUMER_SURFACES} (when `groupSurfaces`: they run inside the group operation the read would queue
29
+ * behind), inside a group-scope `store` frame (when `groupStores`: a consumer group store servicing an adoption's group
30
+ * transaction runs inside the inbox task the read would queue behind), or inside an inbox handler or
31
+ * `onApplicationRumor` frame of any scope (when `inboxSurfaces`).
32
+ */
33
+ export declare function assertRecoveryReadAllowed(guard: ReentrancyGuard, operation: string, refusals: {
34
+ readonly groupSurfaces: boolean;
35
+ readonly inboxSurfaces: boolean;
36
+ readonly groupStores?: boolean;
37
+ }): void;
38
+ export interface InvitationOutcomeReaderDeps {
39
+ readonly guard: ReentrancyGuard;
40
+ /** The inbox's serial queue (`inbox.serialize`): usable before `inbox.start()`. */
41
+ serialize<T>(task: () => Promise<T>): Promise<T>;
42
+ readonly account: AccountStore;
43
+ /** The group's store (the same object for the same id: `WritableStores.groupFactory`). */
44
+ groupStore(groupId: string): GroupStore;
45
+ }
46
+ /**
47
+ * `invitations.outcome(id)`. The guard and the id check run synchronously: the returned promise is already rejected
48
+ * for a refused or invalid call, before anything was queued.
49
+ */
50
+ export declare function readInvitationOutcome(deps: InvitationOutcomeReaderDeps, id: unknown): Promise<InvitationOutcome>;
@@ -0,0 +1,135 @@
1
+ /**
2
+ * `invitations.outcome(id)` (epic marmot-invitation-outcomes S2; ADR-019 D9, D10; architecture SC-8, SC-9).
3
+ *
4
+ * The read classifies ONE instant of durable state:
5
+ *
6
+ * 1. the entry guard ({@link assertRecoveryReadAllowed}) refuses, synchronously and before anything is queued, a call
7
+ * made from a frame whose queue the read would wait on (a hook or a consumer group store call inside the
8
+ * adoption's own group transaction, an inbox handler on the inbox queue, any account-scope consumer surface) — it
9
+ * would deadlock, not read;
10
+ * 2. the read runs on the inbox's serial queue, where every adopting call runs (`accept`, a Welcome's dispatch,
11
+ * `completeStuckJoins`): it never observes the inside of an adoption call. It works with the inbox never started;
12
+ * 3. a read-only GROUP transaction on the record's group holds that group's store queue (no adoption, switch or
13
+ * teardown clear runs meanwhile) while it reads the adoption proofs and awaits a read-only ACCOUNT transaction
14
+ * that reads the record, the index entry and the group's stamps (group → account, the lock order). Both
15
+ * transactions are write-free and re-assert the lease when they settle (`no-lease` once it is lost).
16
+ *
17
+ * A record that names another group inside the account transaction than the routing read saw is read again once;
18
+ * a second move rejects `store-failed`.
19
+ */
20
+ import { classifyInvitationOutcome, decodeInvitation, groupInvitationRecords, indexEntryView, outcomeReadsGroupStamps, stampsOf, } from '../invitations/index.js';
21
+ import { isMalformedRowError, isMarmotError, MarmotError } from '../shared/index.js';
22
+ import { readAdoptionProofs } from './adoption-proof.js';
23
+ import { GROUP_INDEX_EXTENSION } from './group-records.js';
24
+ import { ACCOUNT_SCOPE, GROUP_CONSUMER_SURFACES } from './reentrancy-guard.js';
25
+ /** The inbox-queue consumer surfaces (any scope). */
26
+ export const RECOVERY_READ_INBOX_SURFACES = ['inboxHandler', 'onApplicationRumor'];
27
+ function refuse(operation, scope, surface) {
28
+ return new MarmotError('reentrant', `${operation}: re-entrant call from inside ${surface} (scope ${JSON.stringify(scope)}); read it from an event listener instead`, {
29
+ details: { scope, operation, surface },
30
+ });
31
+ }
32
+ /**
33
+ * SC-9's entry guard, evaluated synchronously: throws `reentrant` (`details: { scope, operation, surface }`) when the
34
+ * calling code runs inside any live account-scope frame, inside a group-scope frame of one of
35
+ * {@link GROUP_CONSUMER_SURFACES} (when `groupSurfaces`: they run inside the group operation the read would queue
36
+ * behind), inside a group-scope `store` frame (when `groupStores`: a consumer group store servicing an adoption's group
37
+ * transaction runs inside the inbox task the read would queue behind), or inside an inbox handler or
38
+ * `onApplicationRumor` frame of any scope (when `inboxSurfaces`).
39
+ */
40
+ export function assertRecoveryReadAllowed(guard, operation, refusals) {
41
+ guard.assertNotReentrant(ACCOUNT_SCOPE, operation);
42
+ if (refusals.groupSurfaces) {
43
+ for (const surface of GROUP_CONSUMER_SURFACES) {
44
+ const frame = guard.withinGroupScope(surface);
45
+ if (frame !== undefined)
46
+ throw refuse(operation, frame.scope, surface);
47
+ }
48
+ }
49
+ if (refusals.groupStores === true) {
50
+ const frame = guard.withinGroupScope('store');
51
+ if (frame !== undefined)
52
+ throw refuse(operation, frame.scope, 'store');
53
+ }
54
+ if (refusals.inboxSurfaces) {
55
+ for (const surface of RECOVERY_READ_INBOX_SURFACES) {
56
+ const frame = guard.within(undefined, surface);
57
+ if (frame !== undefined)
58
+ throw refuse(operation, frame.scope, surface);
59
+ }
60
+ }
61
+ }
62
+ const OPERATION = 'invitations.outcome';
63
+ const RETRY = Symbol('retry');
64
+ /** The record's group as a store-level read sees it (routing only: the classification re-reads it in its transaction). */
65
+ function routingGroupOf(raw) {
66
+ const groupId = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw.groupId : undefined;
67
+ return typeof groupId === 'string' && groupId.length > 0 ? groupId : undefined;
68
+ }
69
+ /**
70
+ * Reads the target record's stored value strictly (SC-7 row 12). An envelope that does not open is the same fact as a
71
+ * payload `decodeInvitation` refuses — the record is unreadable as data — so it rejects as that one documented error,
72
+ * `store-failed` with `details: { id, malformed: true }`. A version mismatch, a backend failure or a lost lease
73
+ * propagates unchanged.
74
+ */
75
+ async function readTargetRow(view, id) {
76
+ try {
77
+ return await view.get(id);
78
+ }
79
+ catch (error) {
80
+ if (isMarmotError(error, 'envelope-mismatch') && isMalformedRowError(error)) {
81
+ throw new MarmotError('store-failed', `pendingInvitations/${id}: malformed record (envelope)`, { cause: error, details: { id, malformed: true } });
82
+ }
83
+ throw error;
84
+ }
85
+ }
86
+ /**
87
+ * `invitations.outcome(id)`. The guard and the id check run synchronously: the returned promise is already rejected
88
+ * for a refused or invalid call, before anything was queued.
89
+ */
90
+ export function readInvitationOutcome(deps, id) {
91
+ try {
92
+ assertRecoveryReadAllowed(deps.guard, OPERATION, { groupSurfaces: true, inboxSurfaces: true, groupStores: true });
93
+ }
94
+ catch (error) {
95
+ return Promise.reject(error);
96
+ }
97
+ if (typeof id !== 'string' || id.length === 0) {
98
+ return Promise.reject(new MarmotError('invalid-options', `${OPERATION}: id must be a non-empty string`, { details: { reason: 'invalid-id' } }));
99
+ }
100
+ const { guard, account } = deps;
101
+ /** The account half: read-only, one instant; `RETRY` when the record names another group than `groupId`. */
102
+ const classifyIn = (groupId, proofs) => guard.call(ACCOUNT_SCOPE, 'store', () => account.transaction(async (atx) => {
103
+ const raw = await readTargetRow(atx.artifact('pendingInvitations'), id);
104
+ const record = raw === undefined ? undefined : decodeInvitation(id, raw);
105
+ if (record?.groupId !== groupId)
106
+ return RETRY;
107
+ if (groupId === undefined)
108
+ return classifyInvitationOutcome({ record, groupProofs: 'no-group', indexEntry: undefined, groupStamps: new Map() });
109
+ const indexEntry = indexEntryView(groupId, await atx.extension(GROUP_INDEX_EXTENSION).get(groupId));
110
+ // The sibling stamps need a scan of every account invitation, done only when the classification reads them
111
+ // (rule 3): a record its own stamp, an exact proof or its status decides is classified without the scan.
112
+ const known = { record, groupProofs: proofs, indexEntry };
113
+ const groupStamps = outcomeReadsGroupStamps(known) ? stampsOf(await groupInvitationRecords(atx, groupId)) : new Map();
114
+ return classifyInvitationOutcome({ ...known, groupStamps });
115
+ }));
116
+ return deps.serialize(async () => {
117
+ for (let attempt = 0; attempt < 2; attempt++) {
118
+ const routed = routingGroupOf(await guard.call(ACCOUNT_SCOPE, 'store', () => readTargetRow(account.artifact('pendingInvitations'), id)));
119
+ let result;
120
+ if (routed === undefined) {
121
+ result = await classifyIn(undefined, 'no-group');
122
+ }
123
+ else {
124
+ const store = deps.groupStore(routed);
125
+ result = await guard.call(routed, 'store', () => store.transaction(async (gtx) => {
126
+ const proofs = await readAdoptionProofs(gtx);
127
+ return classifyIn(routed, proofs);
128
+ }));
129
+ }
130
+ if (result !== RETRY)
131
+ return result;
132
+ }
133
+ throw new MarmotError('store-failed', `${OPERATION}: invitation record ${id} moved between groups while it was read`, { details: { id } });
134
+ });
135
+ }
@@ -43,6 +43,7 @@
43
43
  import type { HeldOpaqueRecord } from '@941design/marmot-engine/engine';
44
44
  import type { NostrEvent } from '@941design/nostr-events/event';
45
45
  import type { KeyValueView } from '../storage/index.js';
46
+ import { InvalidStoredEvidenceError } from '../history/fencing.js';
46
47
  /** Group extension holding the opaque record (one value). */
47
48
  export declare const OPAQUE_EXTENSION = "marmot.opaque";
48
49
  /** The engine's record, as the client persists it. */
@@ -50,7 +51,7 @@ export type OpaqueRecord = HeldOpaqueRecord<NostrEvent>;
50
51
  /** What an absent extension reads as. */
51
52
  export declare const EMPTY_OPAQUE: OpaqueRecord;
52
53
  /** The stored `marmot.opaque` record is not a valid engine record: the group cannot be known safe (see the module comment). */
53
- export declare class OpaqueRecordCorrupt extends Error {
54
+ export declare class OpaqueRecordCorrupt extends InvalidStoredEvidenceError {
54
55
  readonly reason: string;
55
56
  readonly name = "OpaqueRecordCorrupt";
56
57
  constructor(reason: string);
@@ -1,4 +1,5 @@
1
1
  import { MAX_HELD_OPAQUE_CANDIDATES } from '@941design/marmot-engine/engine';
2
+ import { InvalidStoredEvidenceError } from '../history/fencing.js';
2
3
  /** Group extension holding the opaque record (one value). */
3
4
  export const OPAQUE_EXTENSION = 'marmot.opaque';
4
5
  const KEY = 'opaque';
@@ -7,7 +8,7 @@ const MAX_ID_LENGTH = 128;
7
8
  /** What an absent extension reads as. */
8
9
  export const EMPTY_OPAQUE = Object.freeze({ candidates: Object.freeze([]), undecryptableIds: Object.freeze([]) });
9
10
  /** The stored `marmot.opaque` record is not a valid engine record: the group cannot be known safe (see the module comment). */
10
- export class OpaqueRecordCorrupt extends Error {
11
+ export class OpaqueRecordCorrupt extends InvalidStoredEvidenceError {
11
12
  reason;
12
13
  name = 'OpaqueRecordCorrupt';
13
14
  constructor(reason) {
@@ -44,6 +44,8 @@ function changeKey(c) {
44
44
  return `admin:${c.account}:${String(c.admin)}`;
45
45
  case 'component':
46
46
  return `component:${String(c.componentId)}`;
47
+ case 'admission-removed':
48
+ return `admission-removed:${c.candidateId}`;
47
49
  }
48
50
  }
49
51
  /** The dedup key of a terminal: `(intentId, change, type)` plus `commitDigest` for a reapplied (`groupId` is the store's scope). */
@@ -41,7 +41,7 @@ import type { GroupStoreTx } from '../storage/index.js';
41
41
  import type { GroupIntent } from './create-client.js';
42
42
  import { type MessageNotification } from '../history/index.js';
43
43
  import { type TransitionPlan } from './group-history.js';
44
- import { type OwnCommitMarker, type PendingIntentRecord } from './group-records.js';
44
+ import { type OwnCommitMarker, type PendingIntentRecord, type StorableIntent } from './group-records.js';
45
45
  import type { GroupRuntime } from './group-runtime.js';
46
46
  export declare function assertNotDisposed(rt: GroupRuntime): void;
47
47
  export declare function backoffMs(count: number): number;
@@ -91,6 +91,24 @@ declare function confirmRecord(rt: GroupRuntime, record: PendingIntentRecord, at
91
91
  * resume must publish nothing).
92
92
  */
93
93
  export declare function backgroundRetryEnds(rt: GroupRuntime, error: unknown): boolean;
94
+ /**
95
+ * A signer call made on behalf of a group op: framed on the account scope AND
96
+ * the group's scope, so a signer that awaits a mutating call on this group
97
+ * (which would queue behind the op awaiting the signer) is rejected
98
+ * `reentrant` instead of deadlocking; other groups stay reachable.
99
+ */
100
+ export declare function callSignerForGroup<T>(rt: GroupRuntime, fn: () => T | Promise<T>): Promise<T>;
101
+ /**
102
+ * The shared start of every own-intent operation: resumes durable records,
103
+ * then refuses while a confirmation is blocked. Returns the remaining records.
104
+ */
105
+ export declare function preflight(rt: GroupRuntime, operation: string): Promise<PendingIntentRecord[]>;
106
+ /** AC-INVITE-7: a removed local leaf sends nothing — refused before any record or transport call. */
107
+ export declare function assertMember(rt: GroupRuntime, operation: string): void;
108
+ export declare function assertNoOwnCommitPending(rt: GroupRuntime, remaining: readonly PendingIntentRecord[], operation: string): void;
109
+ export declare function recordIntent(rt: GroupRuntime, kind: GroupIntent['type'], intent: StorableIntent, state?: 'pending-publish' | 'awaiting-sync', parentEpoch?: bigint,
110
+ /** Epic marmot-invitation-outcomes S5 (SC-5 I13): further writes in the SAME transaction as the record (the cleanup ledger entry). */
111
+ alsoWrite?: (tx: GroupStoreTx, record: PendingIntentRecord) => Promise<void>): Promise<PendingIntentRecord>;
94
112
  /** What `sendIntent` hands back to the group handle. */
95
113
  export interface SendOutcome {
96
114
  /**
@@ -309,6 +327,8 @@ export declare function takeStrandedSelfUpdateReenqueues(tx: GroupStoreTx): Prom
309
327
  /** Reports records {@link takeStrandedSelfUpdateReenqueues} deleted (after their transaction committed). */
310
328
  export declare function reportStrandedSelfUpdateReenqueues(rt: GroupRuntime, stranded: readonly PendingIntentRecord[], cause: Error): Promise<void>;
311
329
  export declare function failStrandedSelfUpdateReenqueues(rt: GroupRuntime, cause: Error): Promise<void>;
330
+ /** Refuses an own envelope while the gate is closed: `commit-pending`, reason `awaiting-sync` (retryable). */
331
+ export declare function assertSendGateOpen(rt: GroupRuntime, operation: string): void;
312
332
  /**
313
333
  * The gate just opened (ingest.ts, the first complete post-load history pass): the awaiting records are driven in
314
334
  * the background, in `seq` order (the resume path), the rumor queue drains, and a SelfRemove election at rest that
@@ -404,6 +424,8 @@ export declare function scheduleRekeyFollowUp(rt: GroupRuntime): void;
404
424
  * non-admin's admin-list change: `send-rejected`).
405
425
  */
406
426
  export declare function setAdminsIntent(rt: GroupRuntime, accounts: unknown, operation?: string): Promise<void>;
427
+ /** The admin-commit pre-check shared by `rename` and `removeMember`: `invalid-options` / `not-admin` unless `selfPubkey` is an active admin, before anything is recorded. */
428
+ export declare function assertLocalAdmin(rt: GroupRuntime, operation: string, selfPubkey: string): void;
407
429
  /**
408
430
  * `removeMember`'s group-queue part: ONE durable admin commit removing every leaf `account` holds when it is built. Gate order
409
431
  * (Design Decision 6): preflight, member, send gate, malformed (`invalid-options`, `malformed-account`), self (`invalid-options`,
@@ -485,6 +507,13 @@ export declare function expireDeferredProposals(rt: GroupRuntime): Promise<void>
485
507
  * evaluation point evaluates it again. Never throws.
486
508
  */
487
509
  export declare function scheduleProposalDeadlineCheck(rt: GroupRuntime): void;
510
+ /**
511
+ * The policy in front of an own commit: a deferred proposal refuses it (`commit-pending`, reason
512
+ * `proposal-deferred`); S5 (AC-RACE-2): a staged SelfRemove-only batch another member is elected to commit
513
+ * refuses it too (reason `selfremove-election-wait`), checked first — never asking `onProposal` about a
514
+ * foreign proposal while the commit is going to be refused anyway.
515
+ */
516
+ export declare function applyProposalPolicy(rt: GroupRuntime, operation: string): Promise<void>;
488
517
  /**
489
518
  * Marks `refs` invalid under application policy: removed from the staged set, durably, before any commit is built.
490
519
  * `alongside` runs in the same transaction (S15: the deferral records of the drop).