@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
|
@@ -4,13 +4,15 @@
|
|
|
4
4
|
* dependencies_allowed); the public types are re-exported from the package
|
|
5
5
|
* root by `client/index.ts`.
|
|
6
6
|
*/
|
|
7
|
-
export { addProposalsFor, buildWelcomeRumors, createInvitationsService, DEFAULT_INVITE_RETENTION_MS, STAGED_ADD_LOOKUP_TIMEOUT_MS, hasStagedAdds, stagedAddLeafKeys, purgeGroupInvites, recipientsOfWelcome, stagedAddRecipients, decodeStoredWelcomes, encodeStoredWelcomes, toWelcomeOutcome, validateInvitees, WELCOME_COMMIT_TAG, welcomeCommitTagOf, type InvitationsDeps, type InvitationsService, type Invitee, type StoredWelcome, type WelcomeRecipient, type WelcomeOutcome, } from './invite.js';
|
|
7
|
+
export { addProposalsFor, buildWelcomeRumors, cleanupCandidateExists, cleanupCandidateOf, createInvitationsService, declineCandidatePage, DEFAULT_INVITE_RETENTION_MS, STAGED_ADD_LOOKUP_TIMEOUT_MS, hasStagedAdds, stagedAddLeafKeys, purgeGroupInvites, recipientsOfWelcome, stagedAddRecipients, decodeStoredWelcomes, encodeStoredWelcomes, toWelcomeOutcome, validateInvitees, WELCOME_COMMIT_TAG, welcomeCommitTagOf, type InvitationsDeps, type InvitationsService, type Invitee, type StoredWelcome, type WelcomeRecipient, type WelcomeOutcome, } from './invite.js';
|
|
8
8
|
export { decideProposal, defaultDecision, type PendingProposal, type ProposalCallback, type ProposalDecision } from './on-proposal.js';
|
|
9
9
|
export { isAuthorisedCommitter, mustQueue, nextQueueStep, queueBarrier, resolveProposals, stagedProposals, withoutProposals, type ProposalResolution, type QueueStep, type StagedProposals, } from './pending-proposal-policy.js';
|
|
10
10
|
export { DEFAULT_PROPOSAL_DEFERRAL_TIMEOUT_MS, DEFERRED_PROPOSALS_EXTENSION, deferralExpired, deleteDeferral, deleteExclusionEpochs, EXCLUDED_PROPOSALS_EXTENSION, exclusionsAt, planDeferrals, readExclusions, writeExclusion, writeExclusionSnapshot, type ExclusionRecord, type Exclusions, readDeferrals, writeDeferral, type DeferralPlan, type DeferralRecord, } from './proposal-deadline.js';
|
|
11
11
|
export { resolveInboxRelays, type InboxRelayDeps, type InboxRelayResolution } from './relay-planes.js';
|
|
12
12
|
export { carriesBranch, decideCompetingWelcome, judgeCompetingWelcome, otherLeafSignatureKeysOf, terminalClassOf, type CompetingBranch, type CompetingDecision, type CompetingGate, type CompetingVerdict, type CompetingWelcomePorts, type HeldBranch, type HeldScore, type KeepReason, type MissingEvidence, type RebaseRequest, type SwitchState, } from './competing-welcome.js';
|
|
13
|
-
export { createWelcomeService, decodeWelcomeRumor, purgeGroupInvitations, welcomeIdOf, type InvitationRecord, type InvitationStatus, type JoinEvidenceOfWelcome, type MaintenanceKind, MAX_MAINTENANCE_FAILURES, type PendingInvitation, type WelcomeService, type WelcomeServiceDeps, } from './welcome-processor.js';
|
|
13
|
+
export { createWelcomeService, decodeInvitation, decodeWelcomeRumor, encodeInvitation, purgeGroupInvitations, welcomeIdOf, type InvitationRecord, type InvitationStatus, type JoinEvidenceOfWelcome, type MaintenanceKind, MAX_MAINTENANCE_FAILURES, type PendingInvitation, type WelcomeService, type WelcomeServiceDeps, } from './welcome-processor.js';
|
|
14
|
+
export { classifyInvitationOutcome, groupInvitationRecords, indexEntryView, INVITATION_STATUSES, isMalformedRowError, legacyIndexHolds, outcomeReadsGroupStamps, stampAdoptions, stampsFor, stampsOf, type AdoptionProof, type AdoptionProofs, type AdoptionStamp, type IndexEntryView, type InvitationOutcome, type OutcomeSnapshot, } from './invitation-outcome.js';
|
|
14
15
|
export { manifestKey, manifestRefsOfGroup, matchManifest, purgeGroupManifests, recordManifest, stripWaitingRequestTimes, validateManifest, type ManifestMatch, type ManifestRecord, type ManifestStatus, type WelcomeManifestInput } from './expect-welcome.js';
|
|
16
|
+
export { addAnchorsOf, candidateIdOf, decodeCleanupReference, DECLINE_EVIDENCE_EXTENSION, DECLINE_SCAN_PAGE_MAX, declineScanOptions, DELIVERY_EVIDENCE_EXTENSION, encodeCleanupReference, findDeclineCandidate, matchCandidates, type AddAnchor, type CleanupReference, type DeclineCandidate, type DeclineCandidatePage, type DeclineEvidence, type DeliveryEvidence, } from './delivery-evidence.js';
|
|
15
17
|
export { attemptDeclineDelivery, buildDeclineRumor, type DeclineDeliveryDeps, type DeclineState, type DeclineStatus } from './decline.js';
|
|
16
18
|
export { handleKeyPackageOffer, listKeyPackageOffers, OFFERS_EXTENSION, purgeGroupOffers, sendKeyPackageOffer, validateOfferOptions, type KeyPackageOffer, type OfferDeps, } from './offers.js';
|
|
@@ -4,13 +4,15 @@
|
|
|
4
4
|
* dependencies_allowed); the public types are re-exported from the package
|
|
5
5
|
* root by `client/index.ts`.
|
|
6
6
|
*/
|
|
7
|
-
export { addProposalsFor, buildWelcomeRumors, createInvitationsService, DEFAULT_INVITE_RETENTION_MS, STAGED_ADD_LOOKUP_TIMEOUT_MS, hasStagedAdds, stagedAddLeafKeys, purgeGroupInvites, recipientsOfWelcome, stagedAddRecipients, decodeStoredWelcomes, encodeStoredWelcomes, toWelcomeOutcome, validateInvitees, WELCOME_COMMIT_TAG, welcomeCommitTagOf, } from './invite.js';
|
|
7
|
+
export { addProposalsFor, buildWelcomeRumors, cleanupCandidateExists, cleanupCandidateOf, createInvitationsService, declineCandidatePage, DEFAULT_INVITE_RETENTION_MS, STAGED_ADD_LOOKUP_TIMEOUT_MS, hasStagedAdds, stagedAddLeafKeys, purgeGroupInvites, recipientsOfWelcome, stagedAddRecipients, decodeStoredWelcomes, encodeStoredWelcomes, toWelcomeOutcome, validateInvitees, WELCOME_COMMIT_TAG, welcomeCommitTagOf, } from './invite.js';
|
|
8
8
|
export { decideProposal, defaultDecision } from './on-proposal.js';
|
|
9
9
|
export { isAuthorisedCommitter, mustQueue, nextQueueStep, queueBarrier, resolveProposals, stagedProposals, withoutProposals, } from './pending-proposal-policy.js';
|
|
10
10
|
export { DEFAULT_PROPOSAL_DEFERRAL_TIMEOUT_MS, DEFERRED_PROPOSALS_EXTENSION, deferralExpired, deleteDeferral, deleteExclusionEpochs, EXCLUDED_PROPOSALS_EXTENSION, exclusionsAt, planDeferrals, readExclusions, writeExclusion, writeExclusionSnapshot, readDeferrals, writeDeferral, } from './proposal-deadline.js';
|
|
11
11
|
export { resolveInboxRelays } from './relay-planes.js';
|
|
12
12
|
export { carriesBranch, decideCompetingWelcome, judgeCompetingWelcome, otherLeafSignatureKeysOf, terminalClassOf, } from './competing-welcome.js';
|
|
13
|
-
export { createWelcomeService, decodeWelcomeRumor, purgeGroupInvitations, welcomeIdOf, MAX_MAINTENANCE_FAILURES, } from './welcome-processor.js';
|
|
13
|
+
export { createWelcomeService, decodeInvitation, decodeWelcomeRumor, encodeInvitation, purgeGroupInvitations, welcomeIdOf, MAX_MAINTENANCE_FAILURES, } from './welcome-processor.js';
|
|
14
|
+
export { classifyInvitationOutcome, groupInvitationRecords, indexEntryView, INVITATION_STATUSES, isMalformedRowError, legacyIndexHolds, outcomeReadsGroupStamps, stampAdoptions, stampsFor, stampsOf, } from './invitation-outcome.js';
|
|
14
15
|
export { manifestKey, manifestRefsOfGroup, matchManifest, purgeGroupManifests, recordManifest, stripWaitingRequestTimes, validateManifest } from './expect-welcome.js';
|
|
16
|
+
export { addAnchorsOf, candidateIdOf, decodeCleanupReference, DECLINE_EVIDENCE_EXTENSION, DECLINE_SCAN_PAGE_MAX, declineScanOptions, DELIVERY_EVIDENCE_EXTENSION, encodeCleanupReference, findDeclineCandidate, matchCandidates, } from './delivery-evidence.js';
|
|
15
17
|
export { attemptDeclineDelivery, buildDeclineRumor } from './decline.js';
|
|
16
18
|
export { handleKeyPackageOffer, listKeyPackageOffers, OFFERS_EXTENSION, purgeGroupOffers, sendKeyPackageOffer, validateOfferOptions, } from './offers.js';
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import type { AccountStoreTx } from '../storage/index.js';
|
|
2
|
+
import { type InvitationRecord } from './welcome-processor.js';
|
|
3
|
+
/**
|
|
4
|
+
* The account record's durable stamp that the invitation caused adoption (`InvitationRecord.adoption`). `via`: an
|
|
5
|
+
* ordinary join, or a competing Welcome's branch switch. `source`: the group proof the stamp was taken from (or the
|
|
6
|
+
* normal completion of the adoption itself), or the pre-upgrade index entry's `adoptedBy` (rule 3). `at`: client
|
|
7
|
+
* clock ms.
|
|
8
|
+
*/
|
|
9
|
+
export type AdoptionStamp = {
|
|
10
|
+
readonly via: 'join' | 'switch';
|
|
11
|
+
readonly source: 'group-proof' | 'legacy-index';
|
|
12
|
+
readonly at: number;
|
|
13
|
+
};
|
|
14
|
+
/** What `invitations.outcome(id)` reports (architecture SC-7). */
|
|
15
|
+
export type InvitationOutcome = {
|
|
16
|
+
readonly status: 'pending';
|
|
17
|
+
}
|
|
18
|
+
/** `accept(id)` resumes it. */
|
|
19
|
+
| {
|
|
20
|
+
readonly status: 'joining';
|
|
21
|
+
readonly groupId?: string;
|
|
22
|
+
}
|
|
23
|
+
/** A competing Welcome held open, or a join deferred by a restore of its group. */
|
|
24
|
+
| {
|
|
25
|
+
readonly status: 'unresolved';
|
|
26
|
+
readonly groupId: string;
|
|
27
|
+
} | {
|
|
28
|
+
readonly status: 'joined';
|
|
29
|
+
readonly groupId: string;
|
|
30
|
+
readonly via: 'adoption' | 'switch';
|
|
31
|
+
} | {
|
|
32
|
+
readonly status: 'not-joined';
|
|
33
|
+
readonly reason: 'declined' | 'rejected' | 'kept-out';
|
|
34
|
+
readonly detail?: string;
|
|
35
|
+
readonly groupId?: string;
|
|
36
|
+
} | {
|
|
37
|
+
readonly status: 'unknown';
|
|
38
|
+
} | {
|
|
39
|
+
readonly status: 'indeterminate';
|
|
40
|
+
readonly groupId?: string;
|
|
41
|
+
};
|
|
42
|
+
/** One `marmot.adoption` row: the invitation whose Welcome's group transaction wrote the adopted state. */
|
|
43
|
+
export interface AdoptionProof {
|
|
44
|
+
readonly via: 'join';
|
|
45
|
+
/** Hex confirmation tag of the adopted state. */
|
|
46
|
+
readonly tag: string;
|
|
47
|
+
/** Client clock ms of the adoption (the Welcome's arrival). */
|
|
48
|
+
readonly at: number;
|
|
49
|
+
}
|
|
50
|
+
/** The group's adoption proofs, as `client/adoption-proof.ts` `readAdoptionProofs` reads them. */
|
|
51
|
+
export interface AdoptionProofs {
|
|
52
|
+
readonly adoption: ReadonlyMap<string, AdoptionProof>;
|
|
53
|
+
/** Invitation ids whose switch transaction committed (`marmot.branchSwitch`). */
|
|
54
|
+
readonly branchSwitch: ReadonlySet<string>;
|
|
55
|
+
}
|
|
56
|
+
/** The part of the account group index entry (`marmot.groups`) the classification reads. */
|
|
57
|
+
export interface IndexEntryView {
|
|
58
|
+
readonly createdAt: number;
|
|
59
|
+
readonly adoptedBy?: string;
|
|
60
|
+
}
|
|
61
|
+
/** The durable state one classification reads, at one instant (SC-7, SC-8). */
|
|
62
|
+
export interface OutcomeSnapshot {
|
|
63
|
+
readonly record: InvitationRecord | undefined;
|
|
64
|
+
/** `'no-group'`: the record names no group, or the classification runs after the group store was cleared (A2). */
|
|
65
|
+
readonly groupProofs: AdoptionProofs | 'no-group';
|
|
66
|
+
readonly indexEntry: IndexEntryView | undefined;
|
|
67
|
+
/** The stamps of ALL account records of the record's group (own included). */
|
|
68
|
+
readonly groupStamps: ReadonlyMap<string, AdoptionStamp>;
|
|
69
|
+
}
|
|
70
|
+
/** Every stored invitation status, for the exhaustiveness check of the classification (adding one fails its test). */
|
|
71
|
+
export declare const INVITATION_STATUSES: readonly ["pending", "joining", "joined", "declined", "rejected", "competing"];
|
|
72
|
+
/** The classification's view of a stored index entry; throws `store-failed` (`malformed`) on a corrupt one. */
|
|
73
|
+
export declare function indexEntryView(groupId: string, raw: unknown): IndexEntryView | undefined;
|
|
74
|
+
/**
|
|
75
|
+
* Rule 3 (SC-7), per invitation: the pre-upgrade index entry names `id` as its adopter, the group holds no join
|
|
76
|
+
* adoption proof, and no OTHER record of the group carries a join stamp taken from a group proof. Switch proofs and
|
|
77
|
+
* switch stamps of other invitations never suppress it (ADR-019 D7).
|
|
78
|
+
*/
|
|
79
|
+
export declare function legacyIndexHolds(snapshot: OutcomeSnapshot, id: string): boolean;
|
|
80
|
+
/**
|
|
81
|
+
* Whether classifying `snapshot` reads `groupStamps` — the stamps of the group's OTHER records, which only rule 3's
|
|
82
|
+
* sibling check consults. False when the record is absent, an exact proof (row 1) or its status decides the row before
|
|
83
|
+
* rule 3, or rule 3 already fails without the siblings: `groupStamps` then cannot change the result, so a reader may
|
|
84
|
+
* skip the account-wide scan that collects them.
|
|
85
|
+
*/
|
|
86
|
+
export declare function outcomeReadsGroupStamps(snapshot: Omit<OutcomeSnapshot, 'groupStamps'>): boolean;
|
|
87
|
+
/** First matching row of the SC-7 status table. Total over every `InvitationStatus` and the absent record. */
|
|
88
|
+
export declare function classifyInvitationOutcome(snapshot: OutcomeSnapshot): InvitationOutcome;
|
|
89
|
+
/**
|
|
90
|
+
* The stamps teardown must add for one group (constraint 11): exactly the records the classification reads `joined`
|
|
91
|
+
* through a group proof (row 1, not already stamped) or rule 3 (row 5), each evaluated on its own. `records` are the
|
|
92
|
+
* group's account records; `nowMs` dates a switch stamp (a switch proof carries no time).
|
|
93
|
+
*/
|
|
94
|
+
export declare function stampsFor(records: readonly InvitationRecord[], groupProofs: AdoptionProofs | 'no-group', indexEntry: IndexEntryView | undefined, nowMs: number): Map<string, AdoptionStamp>;
|
|
95
|
+
export { isMalformedRowError } from '../shared/index.js';
|
|
96
|
+
/**
|
|
97
|
+
* Every decodable account invitation record naming `groupId`. A record that does not decode — its payload or its
|
|
98
|
+
* envelope — carries no evidence (no stamp can be trusted from it, nor can it be stamped): it is skipped, so it never blocks a teardown or another
|
|
99
|
+
* invitation's read. The record an outcome read is ABOUT is decoded strictly by the reader itself (row 12).
|
|
100
|
+
*/
|
|
101
|
+
export declare function groupInvitationRecords(tx: Pick<AccountStoreTx, 'artifact'>, groupId: string): Promise<InvitationRecord[]>;
|
|
102
|
+
/** The stamps of every account record of `groupId` (the classification's `groupStamps`). */
|
|
103
|
+
export declare function stampsOf(records: readonly InvitationRecord[]): Map<string, AdoptionStamp>;
|
|
104
|
+
/**
|
|
105
|
+
* Teardown's classifier-preserving stamping (ADR-019 D8; G6a): inside `tx`, stamps every record of `groupId` that
|
|
106
|
+
* the classification reads `joined` at this instant through a group proof or rule 3 and is not stamped yet. A1 (the
|
|
107
|
+
* watermark transaction, before the clear) passes the proofs the purge read; A2 (the purge transaction, before the
|
|
108
|
+
* index delete and the record purge) passes `'no-group'`. Idempotent. Returns the ids it stamped.
|
|
109
|
+
*/
|
|
110
|
+
export declare function stampAdoptions(tx: Pick<AccountStoreTx, 'artifact'>, groupId: string, proofs: AdoptionProofs | 'no-group', indexEntry: IndexEntryView | undefined, nowMs: number): Promise<string[]>;
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Invitation outcomes (epic marmot-invitation-outcomes S2; ADR-019 D7, D8; architecture SC-7).
|
|
3
|
+
*
|
|
4
|
+
* Whether THIS exact Welcome caused the local adoption of its group is answered from durable evidence only:
|
|
5
|
+
*
|
|
6
|
+
* - the group's adoption proofs (`client/adoption-proof.ts`): `marmot.adoption[invitationId]`, written in the
|
|
7
|
+
* adoption's own group transaction, and `marmot.branchSwitch[invitationId]`, written in a competing Welcome's
|
|
8
|
+
* switch transaction;
|
|
9
|
+
* - the invitation record's {@link AdoptionStamp} (`InvitationRecord.adoption`), written when the adoption completes
|
|
10
|
+
* normally and by teardown ({@link stampAdoptions}) before the group store (A1) and the index entry (A2) go;
|
|
11
|
+
* - for a record written before any of these existed: the account group index entry's `adoptedBy` (rule 3,
|
|
12
|
+
* {@link legacyIndexHolds}), evaluated per invitation.
|
|
13
|
+
*
|
|
14
|
+
* The functional core here is pure ({@link classifyInvitationOutcome}, {@link legacyIndexHolds}, {@link stampsFor});
|
|
15
|
+
* {@link stampAdoptions} is the one stamping shell, used by both teardown phases (constraint 11).
|
|
16
|
+
*/
|
|
17
|
+
import { isMalformedRowError, MarmotError } from '../shared/index.js';
|
|
18
|
+
import { decodeInvitation, encodeInvitation } from './welcome-processor.js';
|
|
19
|
+
/** Every stored invitation status, for the exhaustiveness check of the classification (adding one fails its test). */
|
|
20
|
+
export const INVITATION_STATUSES = ['pending', 'joining', 'joined', 'declined', 'rejected', 'competing'];
|
|
21
|
+
// ---------------------------------------------------------------------------
|
|
22
|
+
// Codecs (the stamp itself is part of the record codec: `welcome-processor.ts`)
|
|
23
|
+
// ---------------------------------------------------------------------------
|
|
24
|
+
/** The classification's view of a stored index entry; throws `store-failed` (`malformed`) on a corrupt one. */
|
|
25
|
+
export function indexEntryView(groupId, raw) {
|
|
26
|
+
if (raw === undefined)
|
|
27
|
+
return undefined;
|
|
28
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || typeof raw.createdAt !== 'number') {
|
|
29
|
+
throw new MarmotError('store-failed', `group index: malformed entry for ${groupId}`, { details: { groupId, malformed: true } });
|
|
30
|
+
}
|
|
31
|
+
const adoptedBy = raw.adoptedBy;
|
|
32
|
+
return { createdAt: raw.createdAt, ...(typeof adoptedBy === 'string' ? { adoptedBy } : {}) };
|
|
33
|
+
}
|
|
34
|
+
// ---------------------------------------------------------------------------
|
|
35
|
+
// The functional core
|
|
36
|
+
// ---------------------------------------------------------------------------
|
|
37
|
+
function isGroupJoinStamp(stamp) {
|
|
38
|
+
return stamp.via === 'join' && stamp.source === 'group-proof';
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Rule 3 (SC-7), per invitation: the pre-upgrade index entry names `id` as its adopter, the group holds no join
|
|
42
|
+
* adoption proof, and no OTHER record of the group carries a join stamp taken from a group proof. Switch proofs and
|
|
43
|
+
* switch stamps of other invitations never suppress it (ADR-019 D7).
|
|
44
|
+
*/
|
|
45
|
+
export function legacyIndexHolds(snapshot, id) {
|
|
46
|
+
if (!legacyIndexCandidate(snapshot, id))
|
|
47
|
+
return false;
|
|
48
|
+
for (const [other, stamp] of snapshot.groupStamps)
|
|
49
|
+
if (other !== id && isGroupJoinStamp(stamp))
|
|
50
|
+
return false;
|
|
51
|
+
return true;
|
|
52
|
+
}
|
|
53
|
+
/** Rule 3's part that needs no other record: the index names `id` and the group holds no join adoption proof. */
|
|
54
|
+
function legacyIndexCandidate(snapshot, id) {
|
|
55
|
+
if (snapshot.indexEntry?.adoptedBy !== id)
|
|
56
|
+
return false;
|
|
57
|
+
return snapshot.groupProofs === 'no-group' || snapshot.groupProofs.adoption.size === 0;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Whether classifying `snapshot` reads `groupStamps` — the stamps of the group's OTHER records, which only rule 3's
|
|
61
|
+
* sibling check consults. False when the record is absent, an exact proof (row 1) or its status decides the row before
|
|
62
|
+
* rule 3, or rule 3 already fails without the siblings: `groupStamps` then cannot change the result, so a reader may
|
|
63
|
+
* skip the account-wide scan that collects them.
|
|
64
|
+
*/
|
|
65
|
+
export function outcomeReadsGroupStamps(snapshot) {
|
|
66
|
+
const record = snapshot.record;
|
|
67
|
+
if (record === undefined || exactProof(snapshot, record) !== undefined)
|
|
68
|
+
return false;
|
|
69
|
+
const reachesRule3 = record.status === 'joining' || (record.status === 'joined' && record.reason === undefined);
|
|
70
|
+
return reachesRule3 && legacyIndexCandidate(snapshot, record.id);
|
|
71
|
+
}
|
|
72
|
+
/** The exact proof of `record` (row 1), if any. */
|
|
73
|
+
function exactProof(snapshot, record) {
|
|
74
|
+
if (record.adoption !== undefined)
|
|
75
|
+
return record.adoption.via === 'join' ? 'adoption' : 'switch';
|
|
76
|
+
if (snapshot.groupProofs === 'no-group')
|
|
77
|
+
return undefined;
|
|
78
|
+
if (snapshot.groupProofs.adoption.has(record.id))
|
|
79
|
+
return 'adoption';
|
|
80
|
+
if (snapshot.groupProofs.branchSwitch.has(record.id))
|
|
81
|
+
return 'switch';
|
|
82
|
+
return undefined;
|
|
83
|
+
}
|
|
84
|
+
/** First matching row of the SC-7 status table. Total over every `InvitationStatus` and the absent record. */
|
|
85
|
+
export function classifyInvitationOutcome(snapshot) {
|
|
86
|
+
const record = snapshot.record;
|
|
87
|
+
// Row 11.
|
|
88
|
+
if (record === undefined)
|
|
89
|
+
return { status: 'unknown' };
|
|
90
|
+
const groupId = record.groupId ?? '';
|
|
91
|
+
const withGroup = record.groupId === undefined ? {} : { groupId: record.groupId };
|
|
92
|
+
// Row 1.
|
|
93
|
+
const exact = exactProof(snapshot, record);
|
|
94
|
+
if (exact !== undefined)
|
|
95
|
+
return { status: 'joined', groupId, via: exact };
|
|
96
|
+
switch (record.status) {
|
|
97
|
+
case 'declined':
|
|
98
|
+
return { status: 'not-joined', reason: 'declined' }; // Row 2.
|
|
99
|
+
case 'rejected':
|
|
100
|
+
return { status: 'not-joined', reason: 'rejected', ...(record.reason === undefined ? {} : { detail: record.reason }) }; // Row 3.
|
|
101
|
+
case 'joined':
|
|
102
|
+
if (record.reason !== undefined)
|
|
103
|
+
return { status: 'not-joined', reason: 'kept-out', detail: record.reason, ...withGroup }; // Row 4.
|
|
104
|
+
if (legacyIndexHolds(snapshot, record.id))
|
|
105
|
+
return { status: 'joined', groupId, via: 'adoption' }; // Row 5.
|
|
106
|
+
return { status: 'indeterminate', ...withGroup }; // Row 6.
|
|
107
|
+
case 'joining':
|
|
108
|
+
if (legacyIndexHolds(snapshot, record.id))
|
|
109
|
+
return { status: 'joined', groupId, via: 'adoption' }; // Row 5.
|
|
110
|
+
if (record.deferred === 'restore-in-flight')
|
|
111
|
+
return { status: 'unresolved', groupId }; // Row 7.
|
|
112
|
+
return { status: 'joining', ...withGroup }; // Row 8.
|
|
113
|
+
case 'competing':
|
|
114
|
+
return { status: 'unresolved', groupId }; // Row 9.
|
|
115
|
+
case 'pending':
|
|
116
|
+
return { status: 'pending' }; // Row 10.
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* The stamps teardown must add for one group (constraint 11): exactly the records the classification reads `joined`
|
|
121
|
+
* through a group proof (row 1, not already stamped) or rule 3 (row 5), each evaluated on its own. `records` are the
|
|
122
|
+
* group's account records; `nowMs` dates a switch stamp (a switch proof carries no time).
|
|
123
|
+
*/
|
|
124
|
+
export function stampsFor(records, groupProofs, indexEntry, nowMs) {
|
|
125
|
+
const groupStamps = new Map();
|
|
126
|
+
for (const r of records)
|
|
127
|
+
if (r.adoption !== undefined)
|
|
128
|
+
groupStamps.set(r.id, r.adoption);
|
|
129
|
+
const out = new Map();
|
|
130
|
+
for (const record of records) {
|
|
131
|
+
if (record.adoption !== undefined)
|
|
132
|
+
continue;
|
|
133
|
+
const snapshot = { record, groupProofs, indexEntry, groupStamps };
|
|
134
|
+
if (classifyInvitationOutcome(snapshot).status !== 'joined')
|
|
135
|
+
continue;
|
|
136
|
+
if (groupProofs !== 'no-group' && groupProofs.adoption.has(record.id)) {
|
|
137
|
+
out.set(record.id, { via: 'join', source: 'group-proof', at: groupProofs.adoption.get(record.id).at });
|
|
138
|
+
}
|
|
139
|
+
else if (groupProofs !== 'no-group' && groupProofs.branchSwitch.has(record.id)) {
|
|
140
|
+
out.set(record.id, { via: 'switch', source: 'group-proof', at: nowMs });
|
|
141
|
+
}
|
|
142
|
+
else {
|
|
143
|
+
out.set(record.id, { via: 'join', source: 'legacy-index', at: indexEntry?.createdAt ?? nowMs });
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
return out;
|
|
147
|
+
}
|
|
148
|
+
// ---------------------------------------------------------------------------
|
|
149
|
+
// The stamping shell (teardown A1 and A2)
|
|
150
|
+
// ---------------------------------------------------------------------------
|
|
151
|
+
// `isMalformedRowError` lives in shared/errors.ts (re-exported here for existing importers): it inspects error codes
|
|
152
|
+
// only, and keeping it out of this module avoids a welcome-processor <-> invitation-outcome import cycle.
|
|
153
|
+
export { isMalformedRowError } from '../shared/index.js';
|
|
154
|
+
/**
|
|
155
|
+
* Every decodable account invitation record naming `groupId`. A record that does not decode — its payload or its
|
|
156
|
+
* envelope — carries no evidence (no stamp can be trusted from it, nor can it be stamped): it is skipped, so it never blocks a teardown or another
|
|
157
|
+
* invitation's read. The record an outcome read is ABOUT is decoded strictly by the reader itself (row 12).
|
|
158
|
+
*/
|
|
159
|
+
export async function groupInvitationRecords(tx, groupId) {
|
|
160
|
+
const view = tx.artifact('pendingInvitations');
|
|
161
|
+
const out = [];
|
|
162
|
+
for (const key of await view.keys()) {
|
|
163
|
+
let raw;
|
|
164
|
+
try {
|
|
165
|
+
raw = (await view.get(key));
|
|
166
|
+
}
|
|
167
|
+
catch (error) {
|
|
168
|
+
// A row whose envelope does not open names no group we could trust: skipped like an undecodable record.
|
|
169
|
+
if (isMalformedRowError(error))
|
|
170
|
+
continue;
|
|
171
|
+
throw error;
|
|
172
|
+
}
|
|
173
|
+
if (typeof raw !== 'object' || raw === null || raw.groupId !== groupId)
|
|
174
|
+
continue;
|
|
175
|
+
let record;
|
|
176
|
+
try {
|
|
177
|
+
record = decodeInvitation(key, raw);
|
|
178
|
+
}
|
|
179
|
+
catch {
|
|
180
|
+
continue;
|
|
181
|
+
}
|
|
182
|
+
out.push(record);
|
|
183
|
+
}
|
|
184
|
+
return out;
|
|
185
|
+
}
|
|
186
|
+
/** The stamps of every account record of `groupId` (the classification's `groupStamps`). */
|
|
187
|
+
export function stampsOf(records) {
|
|
188
|
+
const out = new Map();
|
|
189
|
+
for (const r of records)
|
|
190
|
+
if (r.adoption !== undefined)
|
|
191
|
+
out.set(r.id, r.adoption);
|
|
192
|
+
return out;
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* Teardown's classifier-preserving stamping (ADR-019 D8; G6a): inside `tx`, stamps every record of `groupId` that
|
|
196
|
+
* the classification reads `joined` at this instant through a group proof or rule 3 and is not stamped yet. A1 (the
|
|
197
|
+
* watermark transaction, before the clear) passes the proofs the purge read; A2 (the purge transaction, before the
|
|
198
|
+
* index delete and the record purge) passes `'no-group'`. Idempotent. Returns the ids it stamped.
|
|
199
|
+
*/
|
|
200
|
+
export async function stampAdoptions(tx, groupId, proofs, indexEntry, nowMs) {
|
|
201
|
+
const records = await groupInvitationRecords(tx, groupId);
|
|
202
|
+
const stamps = stampsFor(records, proofs, indexEntry, nowMs);
|
|
203
|
+
const view = tx.artifact('pendingInvitations');
|
|
204
|
+
for (const record of records) {
|
|
205
|
+
const stamp = stamps.get(record.id);
|
|
206
|
+
if (stamp !== undefined)
|
|
207
|
+
await view.put(record.id, encodeInvitation({ ...record, adoption: stamp }));
|
|
208
|
+
}
|
|
209
|
+
return [...stamps.keys()];
|
|
210
|
+
}
|
|
@@ -32,6 +32,7 @@ import type { RequestWithDeadlineResult } from '@941design/nostr-events/transpor
|
|
|
32
32
|
import { type ClientState, type Proposal, type Welcome } from '@941design/marmot-engine/mls';
|
|
33
33
|
import { MarmotError } from '../shared/index.js';
|
|
34
34
|
import type { AccountStoreTx, Storable } from '../storage/index.js';
|
|
35
|
+
import { type AddAnchor, type DeclineCandidate, type DeclineCandidatePage, type DeliveryEvidence } from './delivery-evidence.js';
|
|
35
36
|
import { type InboxRelayDeps } from './relay-planes.js';
|
|
36
37
|
export interface Invitee {
|
|
37
38
|
/** The invitee's KeyPackageRef (hex) — `retryWelcome`'s `inviteeRef`. */
|
|
@@ -179,6 +180,41 @@ export declare function decodeInviteRecord(key: string, raw: unknown): InviteRec
|
|
|
179
180
|
* raw `groupId` field.
|
|
180
181
|
*/
|
|
181
182
|
export declare function purgeGroupInvites(tx: AccountStoreTx, groupId: string): Promise<void>;
|
|
183
|
+
/**
|
|
184
|
+
* `invitations.declineCandidates` (epic marmot-invitation-outcomes S3, SC-13): one page of the account's decline
|
|
185
|
+
* candidates, read in the caller's (read-only) account transaction. Writes nothing.
|
|
186
|
+
*/
|
|
187
|
+
export declare function declineCandidatePage(tx: AccountStoreTx, opts: {
|
|
188
|
+
readonly account: string;
|
|
189
|
+
readonly after?: string;
|
|
190
|
+
readonly limit: number;
|
|
191
|
+
}): Promise<DeclineCandidatePage>;
|
|
192
|
+
/**
|
|
193
|
+
* `invitations.cleanupDisposition` (epic marmot-invitation-outcomes S4, SC-3 I9, I9a): the delivery and candidate named
|
|
194
|
+
* by a cleanup reference, read in the caller's (read-only) account transaction — the candidate exactly as the scan
|
|
195
|
+
* returns it — plus the identity of the delivery's invite commit while its `invites` record is retained (what lazy
|
|
196
|
+
* legacy anchor resolution needs). `undefined` when the store holds no such delivery. Writes nothing.
|
|
197
|
+
*/
|
|
198
|
+
export declare function cleanupCandidateOf(tx: AccountStoreTx, opts: {
|
|
199
|
+
readonly account: string;
|
|
200
|
+
readonly groupId: string;
|
|
201
|
+
readonly candidateId: string;
|
|
202
|
+
}): Promise<{
|
|
203
|
+
readonly delivery: DeliveryEvidence;
|
|
204
|
+
readonly candidate?: DeclineCandidate;
|
|
205
|
+
readonly invite?: {
|
|
206
|
+
readonly commitEventId: string;
|
|
207
|
+
readonly commitTag?: string;
|
|
208
|
+
};
|
|
209
|
+
} | undefined>;
|
|
210
|
+
/**
|
|
211
|
+
* Whether {@link cleanupCandidateOf} would name a candidate for that identity — the routing read of
|
|
212
|
+
* `invitations.cleanupDisposition`, which resolves no candidate set. Writes nothing.
|
|
213
|
+
*/
|
|
214
|
+
export declare function cleanupCandidateExists(tx: AccountStoreTx, opts: {
|
|
215
|
+
readonly groupId: string;
|
|
216
|
+
readonly candidateId: string;
|
|
217
|
+
}): Promise<boolean>;
|
|
182
218
|
/** One invitee's Welcome delivery, as `invite()` / `retryWelcome()` report it (AC-INVITE-2). */
|
|
183
219
|
export interface WelcomeOutcome {
|
|
184
220
|
readonly inviteeRef: string;
|
|
@@ -225,11 +261,24 @@ export interface InvitationsDeps extends InboxRelayDeps {
|
|
|
225
261
|
}) => void;
|
|
226
262
|
/** AC-HYG-2: how long (client-clock ms) a record whose every delivery is delivered or declined is kept after it settled. */
|
|
227
263
|
readonly inviteRetentionMs: number;
|
|
228
|
-
/**
|
|
264
|
+
/**
|
|
265
|
+
* AC-HYG-3: called once per delivery that went `declined` (after the write committed). The second argument
|
|
266
|
+
* carries the delivery's stable candidate identity (epic marmot-invitation-outcomes S3, `welcomeDeclined.candidateId`).
|
|
267
|
+
*/
|
|
229
268
|
readonly onDeclined?: (declined: {
|
|
230
269
|
readonly groupId: string;
|
|
231
270
|
readonly inviteeRef: string;
|
|
271
|
+
}, identity: {
|
|
272
|
+
readonly candidateId: string;
|
|
232
273
|
}) => void;
|
|
274
|
+
/**
|
|
275
|
+
* Epic marmot-invitation-outcomes S3: called once per candidate whose decline evidence changed — a new candidate or
|
|
276
|
+
* a higher `rev` (after the write committed). A late match beyond retention, an ambiguity and a refinement are each
|
|
277
|
+
* reported here; `onDeclined` keeps its own timing.
|
|
278
|
+
*/
|
|
279
|
+
readonly onCandidate?: (candidate: DeclineCandidate) => void;
|
|
280
|
+
/** The account pubkey the cleanup references name (`AccountStore.account`); read from the signer when absent. */
|
|
281
|
+
readonly account?: string;
|
|
233
282
|
/** Called once per delivery {@link InvitationsService.restoreCommit} put back to `pending` (after the write committed). */
|
|
234
283
|
readonly onRestored?: (restored: {
|
|
235
284
|
readonly groupId: string;
|
|
@@ -245,6 +294,8 @@ export interface InvitationsService {
|
|
|
245
294
|
/** The confirmation tag of the state the commit produced (see {@link InviteRecord.commitTag}). */
|
|
246
295
|
readonly commitTag?: string;
|
|
247
296
|
readonly welcomes: readonly StoredWelcome[];
|
|
297
|
+
/** Epic marmot-invitation-outcomes S3 (SC-1): the Add anchor of each delivery, by KeyPackageRef (absent: unanchored). */
|
|
298
|
+
readonly anchors?: ReadonlyMap<string, AddAnchor>;
|
|
248
299
|
}): Promise<void>;
|
|
249
300
|
/**
|
|
250
301
|
* The group's invite commits a rewind may have to withdraw or restore: `open` (a delivery still `pending` or
|
|
@@ -291,11 +342,15 @@ export interface InvitationsService {
|
|
|
291
342
|
resumeGroup(groupId: string): void;
|
|
292
343
|
/**
|
|
293
344
|
* AC-HYG-3: native bookkeeping of an inbound DECLINE rumor (additive — the inbox still delivers it to
|
|
294
|
-
* `onApplicationRumor`). `rumor.pubkey` is the seal author (NIP-59 unwrap binds the two).
|
|
295
|
-
* content's group whose invitee is that author and whose Welcome has the content's welcome id
|
|
296
|
-
* SHA-256 of the MLS Welcome bytes)
|
|
297
|
-
*
|
|
298
|
-
*
|
|
345
|
+
* `onApplicationRumor`). `rumor.pubkey` is the seal author (NIP-59 unwrap binds the two). The candidate set is
|
|
346
|
+
* every delivery of the content's group whose invitee is that author and whose Welcome has the content's welcome id
|
|
347
|
+
* (`welcomeIdOf`: SHA-256 of the MLS Welcome bytes) — from the delivery evidence, so it outlives retention (epic
|
|
348
|
+
* marmot-invitation-outcomes S3, spec DD2/DD3). Without a selector every in-retention delivery of the set goes
|
|
349
|
+
* `declined` — terminal, no further publish; with a valid `keyPackageRef` selector only the selected one does;
|
|
350
|
+
* with an invalid one nothing happens. Row flips and the decline evidence are written in ONE transaction;
|
|
351
|
+
* `onDeclined` fires once for each delivery that changed and `onCandidate` once per candidate whose evidence
|
|
352
|
+
* changed. Any other author, an unknown welcome id or a malformed content changes nothing. A delivery already
|
|
353
|
+
* `declined` (a redelivered or repeated decline) is not reported again.
|
|
299
354
|
*/
|
|
300
355
|
recordDecline(rumor: Rumor): Promise<void>;
|
|
301
356
|
dispose(): void;
|