@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
|
@@ -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
|
package/dist/client/index.d.ts
CHANGED
|
@@ -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';
|
package/dist/client/ingest.js
CHANGED
|
@@ -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(() =>
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
|
1409
|
-
//
|
|
1410
|
-
//
|
|
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
|
|
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
|
|
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).
|