@941design/marmot 0.0.0-stage → 0.2.0-alpha.0
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 +709 -0
- package/LICENSE +21 -0
- package/README.md +33 -2
- package/dist/account/admin.d.ts +72 -0
- package/dist/account/admin.js +209 -0
- package/dist/account/device-deps.d.ts +379 -0
- package/dist/account/device-deps.js +36 -0
- package/dist/account/device-lineage.d.ts +199 -0
- package/dist/account/device-lineage.js +390 -0
- package/dist/account/device-registry.d.ts +93 -0
- package/dist/account/device-registry.js +1290 -0
- package/dist/account/device-rotation.d.ts +61 -0
- package/dist/account/device-rotation.js +827 -0
- package/dist/account/enrolment.d.ts +339 -0
- package/dist/account/enrolment.js +1247 -0
- package/dist/account/identity-proof.d.ts +79 -0
- package/dist/account/identity-proof.js +264 -0
- package/dist/account/index.d.ts +17 -0
- package/dist/account/index.js +16 -0
- package/dist/account/restore-rotation.d.ts +21 -0
- package/dist/account/restore-rotation.js +22 -0
- package/dist/account/same-account-authorization.d.ts +86 -0
- package/dist/account/same-account-authorization.js +180 -0
- package/dist/account/teardown.d.ts +127 -0
- package/dist/account/teardown.js +856 -0
- package/dist/client/before-create-group.d.ts +18 -0
- package/dist/client/before-create-group.js +65 -0
- package/dist/client/before-publish-hooks.d.ts +121 -0
- package/dist/client/before-publish-hooks.js +180 -0
- package/dist/client/client-config.d.ts +42 -0
- package/dist/client/client-config.js +13 -0
- package/dist/client/commit-redrive.d.ts +68 -0
- package/dist/client/commit-redrive.js +221 -0
- package/dist/client/component-update.d.ts +43 -0
- package/dist/client/component-update.js +53 -0
- package/dist/client/confirm-hooks.d.ts +50 -0
- package/dist/client/confirm-hooks.js +59 -0
- package/dist/client/create-client.d.ts +1022 -0
- package/dist/client/create-client.js +1125 -0
- package/dist/client/group-disband.d.ts +28 -0
- package/dist/client/group-disband.js +64 -0
- package/dist/client/group-history.d.ts +435 -0
- package/dist/client/group-history.js +1295 -0
- package/dist/client/group-profile.d.ts +31 -0
- package/dist/client/group-profile.js +62 -0
- package/dist/client/group-records.d.ts +485 -0
- package/dist/client/group-records.js +1034 -0
- package/dist/client/group-removal.d.ts +36 -0
- package/dist/client/group-removal.js +127 -0
- package/dist/client/group-remove-member.d.ts +49 -0
- package/dist/client/group-remove-member.js +163 -0
- package/dist/client/group-runtime.d.ts +388 -0
- package/dist/client/group-runtime.js +2701 -0
- package/dist/client/group-snapshot.d.ts +98 -0
- package/dist/client/group-snapshot.js +453 -0
- package/dist/client/history-pages.d.ts +107 -0
- package/dist/client/history-pages.js +194 -0
- package/dist/client/inbox-send.d.ts +19 -0
- package/dist/client/inbox-send.js +71 -0
- package/dist/client/index.d.ts +21 -0
- package/dist/client/index.js +13 -0
- package/dist/client/ingest.d.ts +82 -0
- package/dist/client/ingest.js +1550 -0
- package/dist/client/lifecycle-events.d.ts +63 -0
- package/dist/client/lifecycle-events.js +35 -0
- package/dist/client/opaque-candidates.d.ts +81 -0
- package/dist/client/opaque-candidates.js +169 -0
- package/dist/client/own-change-outbox.d.ts +66 -0
- package/dist/client/own-change-outbox.js +156 -0
- package/dist/client/pending-leaf.d.ts +116 -0
- package/dist/client/pending-leaf.js +378 -0
- package/dist/client/permissions.d.ts +9 -0
- package/dist/client/permissions.js +12 -0
- package/dist/client/pipeline.d.ts +554 -0
- package/dist/client/pipeline.js +3545 -0
- package/dist/client/reentrancy-guard.d.ts +96 -0
- package/dist/client/reentrancy-guard.js +153 -0
- package/dist/client/rekey.d.ts +58 -0
- package/dist/client/rekey.js +149 -0
- package/dist/client/transport-policy.d.ts +181 -0
- package/dist/client/transport-policy.js +214 -0
- package/dist/history/equivocation.d.ts +55 -0
- package/dist/history/equivocation.js +113 -0
- package/dist/history/fencing.d.ts +25 -0
- package/dist/history/fencing.js +61 -0
- package/dist/history/hex.d.ts +3 -0
- package/dist/history/hex.js +10 -0
- package/dist/history/index.d.ts +73 -0
- package/dist/history/index.js +31 -0
- package/dist/history/notifications.d.ts +270 -0
- package/dist/history/notifications.js +264 -0
- package/dist/history/ordering-key.d.ts +24 -0
- package/dist/history/ordering-key.js +101 -0
- package/dist/history/own-change-fork.d.ts +112 -0
- package/dist/history/own-change-fork.js +196 -0
- package/dist/history/own-change.d.ts +106 -0
- package/dist/history/own-change.js +146 -0
- package/dist/history/policy.d.ts +48 -0
- package/dist/history/policy.js +52 -0
- package/dist/history/retained-window.d.ts +215 -0
- package/dist/history/retained-window.js +565 -0
- package/dist/inbox/demux.d.ts +90 -0
- package/dist/inbox/demux.js +78 -0
- package/dist/inbox/handler-registry.d.ts +42 -0
- package/dist/inbox/handler-registry.js +37 -0
- package/dist/inbox/index.d.ts +11 -0
- package/dist/inbox/index.js +10 -0
- package/dist/inbox/seen-set.d.ts +82 -0
- package/dist/inbox/seen-set.js +202 -0
- package/dist/inbox/subscription.d.ts +236 -0
- package/dist/inbox/subscription.js +644 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +9 -0
- package/dist/invitations/competing-welcome.d.ts +223 -0
- package/dist/invitations/competing-welcome.js +128 -0
- package/dist/invitations/decline.d.ts +61 -0
- package/dist/invitations/decline.js +143 -0
- package/dist/invitations/expect-welcome.d.ts +66 -0
- package/dist/invitations/expect-welcome.js +138 -0
- package/dist/invitations/index.d.ts +16 -0
- package/dist/invitations/index.js +16 -0
- package/dist/invitations/invite.d.ts +303 -0
- package/dist/invitations/invite.js +966 -0
- package/dist/invitations/offers.d.ts +79 -0
- package/dist/invitations/offers.js +115 -0
- package/dist/invitations/on-proposal.d.ts +47 -0
- package/dist/invitations/on-proposal.js +40 -0
- package/dist/invitations/pending-proposal-policy.d.ts +52 -0
- package/dist/invitations/pending-proposal-policy.js +139 -0
- package/dist/invitations/proposal-deadline.d.ts +133 -0
- package/dist/invitations/proposal-deadline.js +164 -0
- package/dist/invitations/relay-planes.d.ts +43 -0
- package/dist/invitations/relay-planes.js +70 -0
- package/dist/invitations/welcome-processor.d.ts +253 -0
- package/dist/invitations/welcome-processor.js +1180 -0
- package/dist/key-packages/device-key.d.ts +131 -0
- package/dist/key-packages/device-key.js +272 -0
- package/dist/key-packages/device-rotation-records.d.ts +83 -0
- package/dist/key-packages/device-rotation-records.js +173 -0
- package/dist/key-packages/group-refs.d.ts +40 -0
- package/dist/key-packages/group-refs.js +79 -0
- package/dist/key-packages/index.d.ts +18 -0
- package/dist/key-packages/index.js +18 -0
- package/dist/key-packages/key-package-ref.d.ts +16 -0
- package/dist/key-packages/key-package-ref.js +21 -0
- package/dist/key-packages/observation-stream.d.ts +4 -0
- package/dist/key-packages/observation-stream.js +120 -0
- package/dist/key-packages/offer-rumor.d.ts +26 -0
- package/dist/key-packages/offer-rumor.js +69 -0
- package/dist/key-packages/publisher.d.ts +174 -0
- package/dist/key-packages/publisher.js +1247 -0
- package/dist/key-packages/select-key-package.d.ts +24 -0
- package/dist/key-packages/select-key-package.js +90 -0
- package/dist/key-packages/slot-manager.d.ts +167 -0
- package/dist/key-packages/slot-manager.js +327 -0
- package/dist/key-packages/validate-key-package-event.d.ts +3 -0
- package/dist/key-packages/validate-key-package-event.js +49 -0
- package/dist/media/cache.d.ts +14 -0
- package/dist/media/cache.js +10 -0
- package/dist/media/index.d.ts +52 -0
- package/dist/media/index.js +71 -0
- package/dist/mls.d.ts +15 -0
- package/dist/mls.js +15 -0
- package/dist/shared/account-pubkey.d.ts +4 -0
- package/dist/shared/account-pubkey.js +10 -0
- package/dist/shared/errors.d.ts +21 -0
- package/dist/shared/errors.js +85 -0
- package/dist/shared/hex.d.ts +4 -0
- package/dist/shared/hex.js +13 -0
- package/dist/shared/index.d.ts +14 -0
- package/dist/shared/index.js +14 -0
- package/dist/shared/kinds.d.ts +8 -0
- package/dist/shared/kinds.js +28 -0
- package/dist/shared/publish-classification.d.ts +26 -0
- package/dist/shared/publish-classification.js +31 -0
- package/dist/storage/envelope.d.ts +39 -0
- package/dist/storage/envelope.js +201 -0
- package/dist/storage/index.d.ts +227 -0
- package/dist/storage/index.js +459 -0
- package/dist/storage/indexeddb/idb-types.d.ts +68 -0
- package/dist/storage/indexeddb/idb-types.js +1 -0
- package/dist/storage/indexeddb/index.d.ts +17 -0
- package/dist/storage/indexeddb/index.js +141 -0
- package/dist/storage/lease.d.ts +41 -0
- package/dist/storage/lease.js +117 -0
- package/dist/storage/memory/deterministic-signer.d.ts +27 -0
- package/dist/storage/memory/deterministic-signer.js +65 -0
- package/dist/storage/memory/index.d.ts +32 -0
- package/dist/storage/memory/index.js +87 -0
- package/dist/storage/memory/lock-manager.d.ts +8 -0
- package/dist/storage/memory/lock-manager.js +71 -0
- package/package.json +66 -3
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { type Proposal } from '@941design/marmot-engine/mls';
|
|
2
|
+
import { type ComponentUpdateGuard } from './component-update.js';
|
|
3
|
+
/** A group's display profile: both fields are replaced together by one `0x8001` update. */
|
|
4
|
+
export interface GroupProfile {
|
|
5
|
+
/** Non-empty, at most 256 UTF-8 bytes. */
|
|
6
|
+
readonly name: string;
|
|
7
|
+
/** At most 4096 UTF-8 bytes; `''` clears it. */
|
|
8
|
+
readonly description: string;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Throws `MarmotError('invalid-options')` unless `name` is a non-empty string of at most 256 UTF-8 bytes and
|
|
12
|
+
* (when given) `description` is a string of at most 4096 UTF-8 bytes. The limits are BYTE limits (the component's
|
|
13
|
+
* own), not character counts. `operation` prefixes the message.
|
|
14
|
+
*/
|
|
15
|
+
export declare function assertGroupProfile(operation: string, name: unknown, description: unknown): void;
|
|
16
|
+
/**
|
|
17
|
+
* The ts-mls `Proposal` (type `appDataUpdate`, component `0x8001`) that replaces the group's name AND description.
|
|
18
|
+
* Send it as `{ type: 'proposal', proposal }` when the caller is not an admin (an admin then sends
|
|
19
|
+
* `{ type: 'commit' }`); an admin renames in one commit with `MarmotGroup.rename`, which builds its update from
|
|
20
|
+
* this same function.
|
|
21
|
+
*
|
|
22
|
+
* Throws `MarmotError('invalid-options')` (nothing built) for a `name` that is not a non-empty string of at most
|
|
23
|
+
* 256 UTF-8 bytes, and for a `description` that is not a string of at most 4096 UTF-8 bytes.
|
|
24
|
+
*/
|
|
25
|
+
export declare function groupProfileProposal(profile: GroupProfile): Proposal;
|
|
26
|
+
/** The guard of a `rename` commit: a staged group-profile proposal (anyone's, the local account's own included) would make a second `0x8001` update. */
|
|
27
|
+
export declare function profileUpdateGuard(groupId: string, operation?: string): ComponentUpdateGuard;
|
|
28
|
+
/** {@link groupProfileProposal} as a build-time engine action, refused while a group-profile proposal is staged on the state it is built on. */
|
|
29
|
+
export declare function groupProfileAction(profile: GroupProfile, groupId: string): (context: {
|
|
30
|
+
readonly state: import("@941design/marmot-engine/mls").ClientState;
|
|
31
|
+
}) => Promise<Proposal>;
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `marmot.group.profile.v1` (`0x8001`) AppDataUpdate as a typed builder: the one place `@941design/marmot`
|
|
3
|
+
* reaches the engine's `encodeGroupProfileV1`, so a consumer never hand-encodes the QUIC-varint wire bytes and
|
|
4
|
+
* `group.rename()` and the `{ type: 'proposal' }` route (a non-admin proposes, an admin commits) share ONE encoder.
|
|
5
|
+
*/
|
|
6
|
+
import { encodeGroupProfileV1, GROUP_DESCRIPTION_MAX_BYTES, GROUP_NAME_MAX_BYTES, GROUP_PROFILE_COMPONENT_ID } from '@941design/marmot-engine/core';
|
|
7
|
+
import { appDataUpdateProposalType } from '@941design/marmot-engine/mls';
|
|
8
|
+
import { MarmotError } from '../shared/index.js';
|
|
9
|
+
import { guardedComponentUpdate } from './component-update.js';
|
|
10
|
+
function utf8Length(text) {
|
|
11
|
+
return new TextEncoder().encode(text).length;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Throws `MarmotError('invalid-options')` unless `name` is a non-empty string of at most 256 UTF-8 bytes and
|
|
15
|
+
* (when given) `description` is a string of at most 4096 UTF-8 bytes. The limits are BYTE limits (the component's
|
|
16
|
+
* own), not character counts. `operation` prefixes the message.
|
|
17
|
+
*/
|
|
18
|
+
export function assertGroupProfile(operation, name, description) {
|
|
19
|
+
if (typeof name !== 'string' || name.length === 0) {
|
|
20
|
+
throw new MarmotError('invalid-options', `${operation}: name must be a non-empty string`, { details: { reason: 'malformed-name' } });
|
|
21
|
+
}
|
|
22
|
+
if (utf8Length(name) > GROUP_NAME_MAX_BYTES) {
|
|
23
|
+
throw new MarmotError('invalid-options', `${operation}: name exceeds ${String(GROUP_NAME_MAX_BYTES)} UTF-8 bytes`, { details: { reason: 'name-too-long', limit: GROUP_NAME_MAX_BYTES } });
|
|
24
|
+
}
|
|
25
|
+
if (description === undefined)
|
|
26
|
+
return;
|
|
27
|
+
if (typeof description !== 'string') {
|
|
28
|
+
throw new MarmotError('invalid-options', `${operation}: description must be a string`, { details: { reason: 'malformed-description' } });
|
|
29
|
+
}
|
|
30
|
+
if (utf8Length(description) > GROUP_DESCRIPTION_MAX_BYTES) {
|
|
31
|
+
throw new MarmotError('invalid-options', `${operation}: description exceeds ${String(GROUP_DESCRIPTION_MAX_BYTES)} UTF-8 bytes`, {
|
|
32
|
+
details: { reason: 'description-too-long', limit: GROUP_DESCRIPTION_MAX_BYTES },
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* The ts-mls `Proposal` (type `appDataUpdate`, component `0x8001`) that replaces the group's name AND description.
|
|
38
|
+
* Send it as `{ type: 'proposal', proposal }` when the caller is not an admin (an admin then sends
|
|
39
|
+
* `{ type: 'commit' }`); an admin renames in one commit with `MarmotGroup.rename`, which builds its update from
|
|
40
|
+
* this same function.
|
|
41
|
+
*
|
|
42
|
+
* Throws `MarmotError('invalid-options')` (nothing built) for a `name` that is not a non-empty string of at most
|
|
43
|
+
* 256 UTF-8 bytes, and for a `description` that is not a string of at most 4096 UTF-8 bytes.
|
|
44
|
+
*/
|
|
45
|
+
export function groupProfileProposal(profile) {
|
|
46
|
+
if (typeof profile !== 'object' || profile === null)
|
|
47
|
+
throw new MarmotError('invalid-options', 'groupProfileProposal: profile must be an object', { details: { reason: 'malformed-profile' } });
|
|
48
|
+
// The builder's description is required (a full replacement): an absent one is reported as the non-string it is.
|
|
49
|
+
assertGroupProfile('groupProfileProposal', profile.name, profile.description ?? null);
|
|
50
|
+
return {
|
|
51
|
+
proposalType: appDataUpdateProposalType,
|
|
52
|
+
appDataUpdate: { componentId: GROUP_PROFILE_COMPONENT_ID, operation: 'update', update: encodeGroupProfileV1({ name: profile.name, description: profile.description }) },
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
/** The guard of a `rename` commit: a staged group-profile proposal (anyone's, the local account's own included) would make a second `0x8001` update. */
|
|
56
|
+
export function profileUpdateGuard(groupId, operation = 'rename') {
|
|
57
|
+
return { componentId: GROUP_PROFILE_COMPONENT_ID, groupId, operation, what: 'group-profile', reason: 'staged-profile-update' };
|
|
58
|
+
}
|
|
59
|
+
/** {@link groupProfileProposal} as a build-time engine action, refused while a group-profile proposal is staged on the state it is built on. */
|
|
60
|
+
export function groupProfileAction(profile, groupId) {
|
|
61
|
+
return guardedComponentUpdate(profileUpdateGuard(groupId), () => groupProfileProposal(profile));
|
|
62
|
+
}
|
|
@@ -0,0 +1,485 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Persisted record codecs for the group runtime (S3): the `clientState`
|
|
3
|
+
* codec, the account-level group index, pending-intent records, the
|
|
4
|
+
* terminal ledger and the kind-445 ingest cursor. Pure `KeyValueView` codec
|
|
5
|
+
* helpers — no engine calls, no transport, no re-entrancy guard
|
|
6
|
+
* (`group-runtime.ts` / `pipeline.ts` / `ingest.ts` own those). Every helper
|
|
7
|
+
* accepts a `KeyValueView`, so it works identically against a store's own
|
|
8
|
+
* scope-level view or a transaction's `tx` view.
|
|
9
|
+
*/
|
|
10
|
+
import { type DeclaredChanges, type OrderingKey, type OwnChange, type OwnChangeLostReason } from '../history/index.js';
|
|
11
|
+
import type { ClientState } from '@941design/marmot-engine/mls';
|
|
12
|
+
import { type StoredWelcome } from '../invitations/index.js';
|
|
13
|
+
import { MarmotError } from '../shared/index.js';
|
|
14
|
+
import type { KeyValueView, Storable } from '../storage/index.js';
|
|
15
|
+
import type { GroupIntent } from './create-client.js';
|
|
16
|
+
import { type IngestCursor } from './transport-policy.js';
|
|
17
|
+
/** A fresh random pending-intent id (hex). Shared by every writer of `pendingIntents` — pipeline.ts's own
|
|
18
|
+
* intents and group-history.ts's atomic self-update re-enqueue (AC-RACE-1) alike. */
|
|
19
|
+
export declare function randomIntentId(): string;
|
|
20
|
+
/** Whether the group has a persisted `ClientState` (nothing is decoded: a presence check for listings). */
|
|
21
|
+
export declare function hasGroupState(view: KeyValueView): Promise<boolean>;
|
|
22
|
+
/** Reads the group's persisted `ClientState`, or `undefined` when the group has never been created/joined locally. */
|
|
23
|
+
export declare function readGroupState(view: KeyValueView): Promise<ClientState | undefined>;
|
|
24
|
+
/** Persists `state` as the group's current `ClientState`. */
|
|
25
|
+
export declare function writeGroupState(view: KeyValueView, state: ClientState): Promise<void>;
|
|
26
|
+
/**
|
|
27
|
+
* The group extension marking a `groups.restore` adoption whose self-update has not confirmed yet: written in the
|
|
28
|
+
* adoption transaction (with the snapshot's `clientState`), deleted in the confirmation transaction of an own
|
|
29
|
+
* self-update (pipeline.ts `confirmRecord`) — so a crash, or a dispose that could not wait for the group's queue,
|
|
30
|
+
* never leaves a half-restored group that a later client over the same stores would hold as if restored. A later
|
|
31
|
+
* client resumes such a group (group-runtime.ts `resumeRestore`: started by its startup scan and by every entry point
|
|
32
|
+
* that would read the group as held) — never discards it outright: the restore's self-update may already be on the
|
|
33
|
+
* relays, and only its record in these stores can confirm it.
|
|
34
|
+
*/
|
|
35
|
+
export declare const RESTORE_PENDING_EXTENSION = "marmot.restorePending";
|
|
36
|
+
/** Marks the group as adopted by a restore whose self-update has not confirmed. */
|
|
37
|
+
export declare function writeRestorePending(view: KeyValueView, at: number): Promise<void>;
|
|
38
|
+
/** Whether the group is marked as an unfinished restore (any stored value counts: the safe side is to resume). */
|
|
39
|
+
export declare function readRestorePending(view: KeyValueView): Promise<boolean>;
|
|
40
|
+
/** Clears the unfinished-restore mark (a no-op when absent). */
|
|
41
|
+
export declare function clearRestorePending(view: KeyValueView): Promise<void>;
|
|
42
|
+
/**
|
|
43
|
+
* The account extension naming every `groups.restore` adoption that has not got its account group-index entry yet.
|
|
44
|
+
* The startup scan otherwise walks the group index only, and the adoption writes the group store (snapshot state,
|
|
45
|
+
* key material, the {@link RESTORE_PENDING_EXTENSION} mark) BEFORE that entry: a crash in between would leave a
|
|
46
|
+
* group store no later client ever finds. So the adoption runs as three transactions, each a separate one (never
|
|
47
|
+
* nested — the cross-scope lock order is group → account, and this order starts on the account):
|
|
48
|
+
* 1. account: this record (nothing of the group written yet);
|
|
49
|
+
* 2. group: the snapshot's state, rewind window, cursor and the unfinished-restore mark;
|
|
50
|
+
* 3. account: the group-index entry, and this record deleted — atomically.
|
|
51
|
+
* Every crash point leaves a state the scan finds and settles (group-runtime.ts `settleRestoringRecord`): after 1, a
|
|
52
|
+
* record without a mark (dropped); after 2, a marked group without an index entry (discarded — nothing was ever
|
|
53
|
+
* recorded for it — its group store wiped, then this record); after 3, an indexed marked group (resumed).
|
|
54
|
+
*
|
|
55
|
+
* A failed restore's take-back (group-runtime.ts `clearAdoptedGroup`) runs the reverse, with this record as its
|
|
56
|
+
* durable cleanup marker: 1. account: this record (re-)written; 2. group: the store cleared; 3. account: the
|
|
57
|
+
* group-index entry and this record deleted — atomically. After 1 the group is still marked (resumed); after 2 the
|
|
58
|
+
* record names an empty group store (no state, no mark) whose index entry the scan deletes with the record — never
|
|
59
|
+
* an index entry left naming a group nothing holds and no scan revisits.
|
|
60
|
+
*/
|
|
61
|
+
export declare const RESTORING_EXTENSION = "marmot.restoring";
|
|
62
|
+
/** Records that `groupId` is being adopted by a restore (step 1 above). */
|
|
63
|
+
export declare function writeRestoringRecord(view: KeyValueView, groupId: string, at: number): Promise<void>;
|
|
64
|
+
/** Deletes `groupId`'s restore record (a no-op when absent). */
|
|
65
|
+
export declare function clearRestoringRecord(view: KeyValueView, groupId: string): Promise<void>;
|
|
66
|
+
/** Every group id with a restore record (any stored value counts: the safe side is to settle it). */
|
|
67
|
+
export declare function listRestoringRecords(view: KeyValueView): Promise<string[]>;
|
|
68
|
+
/**
|
|
69
|
+
* The group extension holding the last post-load ratchet skip: written in the staging transaction of the skipped
|
|
70
|
+
* application message (next to the advanced `clientState`), marked `delivered` once a relay accepted an own
|
|
71
|
+
* application message at or after the skipped generation on the same epoch state. A load re-arms the skip unless
|
|
72
|
+
* the marker names the loaded epoch state, is undelivered, and the loaded ratchet already holds the skipped
|
|
73
|
+
* generation — so skips never pile up while nothing reaches a relay (every receiver's gap stays within one margin
|
|
74
|
+
* plus the undelivered messages), while a restore of a state without that marker (an older backup) still skips.
|
|
75
|
+
*/
|
|
76
|
+
export declare const RATCHET_SKIP_EXTENSION = "marmot.ratchetSkip";
|
|
77
|
+
export interface RatchetSkipMarker {
|
|
78
|
+
/** Epoch and hex confirmation tag of the epoch state the skipped message was encrypted under. */
|
|
79
|
+
readonly epoch: bigint;
|
|
80
|
+
readonly tag: string;
|
|
81
|
+
/** The application-ratchet generation the skipped message used. */
|
|
82
|
+
readonly generation: number;
|
|
83
|
+
/** Whether a relay accepted an own application message at or after `generation` on that epoch state. */
|
|
84
|
+
readonly delivered: boolean;
|
|
85
|
+
}
|
|
86
|
+
/** The stored marker; `undefined` when absent or unreadable (an unreadable marker re-arms the skip, the safe side for reuse). */
|
|
87
|
+
export declare function readRatchetSkipMarker(view: KeyValueView): Promise<RatchetSkipMarker | undefined>;
|
|
88
|
+
export declare function writeRatchetSkipMarker(view: KeyValueView, marker: RatchetSkipMarker): Promise<void>;
|
|
89
|
+
/**
|
|
90
|
+
* Marks the stored marker delivered when `ordering` (an own application message a relay just accepted) was sent on
|
|
91
|
+
* the marker's epoch state at or after its skipped generation. A message whose generation could not be read
|
|
92
|
+
* (`-1`) or with no ordering key never marks it. Returns whether it marked it.
|
|
93
|
+
*/
|
|
94
|
+
export declare function markRatchetSkipDelivered(view: KeyValueView, ordering: OrderingKey | undefined): Promise<boolean>;
|
|
95
|
+
/**
|
|
96
|
+
* Whether a load of a state at (`epoch`, `tag`) whose own ratchet's next generation is `nextGeneration` re-arms the
|
|
97
|
+
* post-load skip, given the stored `marker`.
|
|
98
|
+
*/
|
|
99
|
+
export declare function ratchetSkipArmed(marker: RatchetSkipMarker | undefined, epoch: bigint, tag: string, nextGeneration: number): boolean;
|
|
100
|
+
/** Removes the group's persisted `ClientState` (undoes a `groups.create` that could not be indexed). */
|
|
101
|
+
export declare function deleteGroupState(view: KeyValueView): Promise<void>;
|
|
102
|
+
export declare const GROUP_INDEX_EXTENSION = "marmot.groups";
|
|
103
|
+
export interface GroupIndexEntry {
|
|
104
|
+
readonly createdAt: number;
|
|
105
|
+
/** The id of the invitation whose Welcome adopted the group (absent: created here, or adopted by an older build). */
|
|
106
|
+
readonly adoptedBy?: string;
|
|
107
|
+
}
|
|
108
|
+
export declare function readGroupIndexEntry(view: KeyValueView, groupId: string): Promise<GroupIndexEntry | undefined>;
|
|
109
|
+
export declare function writeGroupIndexEntry(view: KeyValueView, groupId: string, entry: GroupIndexEntry): Promise<void>;
|
|
110
|
+
/** Every indexed group id. */
|
|
111
|
+
export declare function listGroupIndex(view: KeyValueView): Promise<string[]>;
|
|
112
|
+
export type PendingIntentKind = GroupIntent['type'];
|
|
113
|
+
/**
|
|
114
|
+
* `awaiting-sync` (S18, AC-PIPE-15): accepted by `send()` after a load, before the group's first post-load sync;
|
|
115
|
+
* envelope-less — nothing ratchet-derived is minted until the sync completes (pipeline.ts, the send gate).
|
|
116
|
+
*/
|
|
117
|
+
export type PendingRecordState = 'pending-publish' | 'pending-confirm' | 'awaiting-sync';
|
|
118
|
+
/**
|
|
119
|
+
* A `GroupIntent` re-encoded for storage. `proposal` is stored structurally
|
|
120
|
+
* (the envelope's own `Storable` tagged-JSON codec) rather than through a
|
|
121
|
+
* dedicated ts-mls wire encoder: this vendored ts-mls build's package
|
|
122
|
+
* `exports` map exposes only its top-level barrel, which does not re-export
|
|
123
|
+
* `proposalEncoder`/`proposalDecoder` (unlike `mlsMessageEncoder` — a plain
|
|
124
|
+
* TLS-wire `Proposal` codec is simply not reachable from outside the
|
|
125
|
+
* package). A ts-mls `Proposal` is itself plain data (nested
|
|
126
|
+
* numbers/strings/`Uint8Array`, no methods), so it round-trips through
|
|
127
|
+
* `Storable` unchanged.
|
|
128
|
+
*/
|
|
129
|
+
export type StorableIntent = {
|
|
130
|
+
readonly type: 'application';
|
|
131
|
+
readonly rumor: Storable;
|
|
132
|
+
} | {
|
|
133
|
+
readonly type: 'proposal';
|
|
134
|
+
readonly proposal: Storable;
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* `removeLeafKeys` (S8, `devices.forget`): the commit also Removes the leaves carrying these signature keys (hex), resolved to leaf indexes when it is built.
|
|
138
|
+
* `admins` (S9, `setAdmins` / the demotion of `departAsAdmin`): the commit also sets the group's admin list (admin-policy AppDataUpdate).
|
|
139
|
+
* `profile` (`rename`): the commit also replaces the group's name AND description (the `0x8001` AppDataUpdate), stored by value — an
|
|
140
|
+
* omitted description was already resolved from the group view when the call was made.
|
|
141
|
+
* `removeAccounts` (`removeMember`): the commit Removes every leaf these accounts hold WHEN IT IS BUILT (the accounts are stored, never leaf
|
|
142
|
+
* indexes), skipping leaves a staged Remove / SelfRemove already targets.
|
|
143
|
+
*/
|
|
144
|
+
| {
|
|
145
|
+
readonly type: 'commit';
|
|
146
|
+
readonly invite?: StoredInviteIntent;
|
|
147
|
+
readonly removeLeafKeys?: readonly string[];
|
|
148
|
+
readonly admins?: readonly string[];
|
|
149
|
+
readonly profile?: {
|
|
150
|
+
readonly name: string;
|
|
151
|
+
readonly description: string;
|
|
152
|
+
};
|
|
153
|
+
readonly removeAccounts?: readonly string[];
|
|
154
|
+
/** With `removeAccounts`: the signature keys (hex) of the leaves those accounts held when the call was recorded. */
|
|
155
|
+
readonly removeAccountLeafKeys?: readonly string[];
|
|
156
|
+
/**
|
|
157
|
+
* Epic marmot-rewound-own-commit-no-signal (S8, DD10): `'approval'` marks a commit that applies a join request's
|
|
158
|
+
* approval (the only accepted value). Absent on every record written before this field existed.
|
|
159
|
+
*/
|
|
160
|
+
readonly origin?: 'approval';
|
|
161
|
+
/**
|
|
162
|
+
* S8 (DD2): app-data components (id -> new bytes; `null` deletes the entry) the commit also sets. Absent on
|
|
163
|
+
* records written before this field existed.
|
|
164
|
+
*/
|
|
165
|
+
readonly components?: readonly {
|
|
166
|
+
readonly id: number;
|
|
167
|
+
readonly data: Uint8Array | null;
|
|
168
|
+
}[];
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* `after` (S13): the intentId of the own commit of staged Adds this self-update must follow (a self-update over
|
|
172
|
+
* staged Adds is two commits). It is driven only once that record is gone: if the epoch moved on — the commit
|
|
173
|
+
* confirmed, or it went terminal because a foreign commit confirmed at its epoch (`stale-parent`) — the
|
|
174
|
+
* self-update is re-parented to the current epoch and rotates the leaf; if the epoch is unchanged the commit
|
|
175
|
+
* went terminal without moving it, and the self-update is dropped with it (`intentFailed`, reason
|
|
176
|
+
* `dependency-terminal`, when no caller is waiting).
|
|
177
|
+
*/
|
|
178
|
+
| {
|
|
179
|
+
readonly type: 'self-update';
|
|
180
|
+
readonly after?: string;
|
|
181
|
+
readonly rekey?: RekeyTarget;
|
|
182
|
+
};
|
|
183
|
+
/**
|
|
184
|
+
* Epic marmot-device-key-rotation (S6, AC-REKEY-1): a self-update that also replaces the local leaf's signature key
|
|
185
|
+
* with `target` (hex of the public key `deviceRegistry/self` holds). Only the PUBLIC key is stored: the private half
|
|
186
|
+
* and the proof are read from the account store when the commit is built, so no private key bytes sit in the group
|
|
187
|
+
* store's pending record (AC-REKEY-3).
|
|
188
|
+
*/
|
|
189
|
+
export interface RekeyTarget {
|
|
190
|
+
readonly target: string;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* The invitees of an invite commit (S5): each one's KeyPackage event (the Add
|
|
194
|
+
* is rebuilt from it if the record resumes before staging) and KeyPackageRef.
|
|
195
|
+
*/
|
|
196
|
+
export interface StoredInviteIntent {
|
|
197
|
+
readonly invitees: readonly {
|
|
198
|
+
readonly event: Storable;
|
|
199
|
+
readonly inviteeRef: string;
|
|
200
|
+
}[];
|
|
201
|
+
}
|
|
202
|
+
/** A ts-mls `PendingState` re-encoded for storage: every `ClientState`/`MlsMessage` becomes bytes. */
|
|
203
|
+
export interface StoredPending {
|
|
204
|
+
readonly kind: 'proposal' | 'commit' | 'selfUpdate';
|
|
205
|
+
readonly newState: Uint8Array;
|
|
206
|
+
readonly parentState?: Uint8Array;
|
|
207
|
+
readonly commitMessage?: Uint8Array;
|
|
208
|
+
/**
|
|
209
|
+
* S10: the engine's own-commit convergence stamp, as `encodeOwnCommitRecord` bytes (wire + stamp): an own
|
|
210
|
+
* commit confirmed after a reload or retry carries it into the rewind window like a live confirmation does —
|
|
211
|
+
* without it the commit is no fork-recovery candidate here (its committer cannot replay it).
|
|
212
|
+
*/
|
|
213
|
+
readonly ownCommit?: Uint8Array;
|
|
214
|
+
}
|
|
215
|
+
export interface PendingIntentRecord {
|
|
216
|
+
readonly v: 1;
|
|
217
|
+
readonly intentId: string;
|
|
218
|
+
/** Monotonic per group: max existing `seq` + 1. */
|
|
219
|
+
readonly seq: number;
|
|
220
|
+
readonly kind: PendingIntentKind;
|
|
221
|
+
readonly state: PendingRecordState;
|
|
222
|
+
readonly parentEpoch: bigint;
|
|
223
|
+
readonly intent: StorableIntent;
|
|
224
|
+
readonly envelope?: Storable;
|
|
225
|
+
readonly pending?: StoredPending;
|
|
226
|
+
/** An invite commit's Welcome rumors, stored at staging together with `envelope` (S5). */
|
|
227
|
+
readonly welcomes?: readonly StoredWelcome[];
|
|
228
|
+
/**
|
|
229
|
+
* S10: an application message's ordering key, read at staging under the
|
|
230
|
+
* state it was sent in — its confirmation may come after the group moved on
|
|
231
|
+
* (a retried publish), when that state's keys no longer read the envelope.
|
|
232
|
+
*/
|
|
233
|
+
readonly ordering?: OrderingKey;
|
|
234
|
+
readonly attempts: number;
|
|
235
|
+
/**
|
|
236
|
+
* S5 (AC-RACE-1): set when this record is the re-enqueue of an own self-update commit a rewind withdrew — the
|
|
237
|
+
* withdrawn commit's own `intentId` (its terminal-ledger entry's `selfUpdateIntentId`). Dedup key: a second
|
|
238
|
+
* detection of the same withdrawal must not create a second re-enqueue.
|
|
239
|
+
*/
|
|
240
|
+
readonly reenqueuedFrom?: string;
|
|
241
|
+
/**
|
|
242
|
+
* S5 (AC-RACE-1): a re-enqueue kept for another attempt (its stale envelope discarded, or the Add commit it
|
|
243
|
+
* followed refused) is not driven before this client-clock time (ms) — the capped publish backoff for the attempts
|
|
244
|
+
* it has spent. Absent: drive at once.
|
|
245
|
+
*/
|
|
246
|
+
readonly retryAt?: number;
|
|
247
|
+
/**
|
|
248
|
+
* Epic marmot-rewound-own-commit-no-signal (S8, DD14/DD15): on a re-drive record (a `{type:'commit'}` intent re-enqueued
|
|
249
|
+
* for a withdrawn own commit), the changes it re-applies, each with its fork-point values and (DD11) its persisted verdict. This record is the ONLY verdict carrier.
|
|
250
|
+
*/
|
|
251
|
+
readonly changes?: readonly StoredOwnChange[];
|
|
252
|
+
/** S8 (DD13): the epoch (a non-negative integer, as `WindowNode.epoch`) of the fork point the re-drive's `changes` were captured at. */
|
|
253
|
+
readonly forkEpoch?: number;
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* A commit re-drive record (S1): the durable record a withdrawal writes for a withdrawn own commit — a `commit` carrying
|
|
257
|
+
* `changes` (DD15; the decoder and the encoder enforce `changes` => `{ type: 'commit' }` + `reenqueuedFrom`). The
|
|
258
|
+
* self-update re-enqueue paths (AC-RACE-1) must neither pick it up nor count it among their siblings.
|
|
259
|
+
*/
|
|
260
|
+
export declare function isCommitRedrive(record: Pick<PendingIntentRecord, 'changes'>): boolean;
|
|
261
|
+
export declare function decodePendingIntentRecord(intentId: string, raw: unknown): PendingIntentRecord;
|
|
262
|
+
export declare function encodePendingIntentRecord(record: PendingIntentRecord): Storable;
|
|
263
|
+
export declare function readPendingIntentRecord(view: KeyValueView, intentId: string): Promise<PendingIntentRecord | undefined>;
|
|
264
|
+
export declare function writePendingIntentRecord(view: KeyValueView, record: PendingIntentRecord): Promise<void>;
|
|
265
|
+
export declare function deletePendingIntentRecord(view: KeyValueView, intentId: string): Promise<void>;
|
|
266
|
+
/** Every pending-intent record, ordered by `seq` (ascending — creation order). */
|
|
267
|
+
export declare function listPendingIntentRecords(view: KeyValueView): Promise<PendingIntentRecord[]>;
|
|
268
|
+
/** `{ intentId, state, kind }` for every pending intent, ordered by `seq` (AC-PIPE-1). */
|
|
269
|
+
export declare function listPendingIntentSummaries(view: KeyValueView): Promise<Array<{
|
|
270
|
+
readonly intentId: string;
|
|
271
|
+
readonly state: PendingRecordState;
|
|
272
|
+
readonly kind: PendingIntentKind;
|
|
273
|
+
}>>;
|
|
274
|
+
/** The next `seq` to assign: max existing `seq` + 1 (1 when the group has no pending intents yet). */
|
|
275
|
+
export declare function nextSeq(view: KeyValueView): Promise<number>;
|
|
276
|
+
export interface QueuedRumorRecord {
|
|
277
|
+
readonly v: 1;
|
|
278
|
+
/** Also the intentId of the application intent the rumor becomes when it is published. */
|
|
279
|
+
readonly queueId: string;
|
|
280
|
+
/** Monotonic per group: queue order. */
|
|
281
|
+
readonly seq: number;
|
|
282
|
+
readonly rumor: Storable;
|
|
283
|
+
/** The rumor goes out only once the group's epoch is past this one (see `queueBarrier`). */
|
|
284
|
+
readonly barrier?: bigint;
|
|
285
|
+
/** Client clock (ms) when it was queued. */
|
|
286
|
+
readonly queuedAt: number;
|
|
287
|
+
}
|
|
288
|
+
export declare function decodeQueuedRumorRecord(queueId: string, raw: unknown): QueuedRumorRecord;
|
|
289
|
+
export declare function writeQueuedRumorRecord(view: KeyValueView, record: QueuedRumorRecord): Promise<void>;
|
|
290
|
+
export declare function readQueuedRumorRecord(view: KeyValueView, queueId: string): Promise<QueuedRumorRecord | undefined>;
|
|
291
|
+
/** Every queued rumor, in queue order. */
|
|
292
|
+
export declare function listQueuedRumorRecords(view: KeyValueView): Promise<QueuedRumorRecord[]>;
|
|
293
|
+
export interface TerminalLedgerEntry {
|
|
294
|
+
readonly disposition: string;
|
|
295
|
+
/** Client clock (ms) when the entry was written. */
|
|
296
|
+
readonly at: number;
|
|
297
|
+
/** The event's own `created_at` (unix seconds) — what retention is measured against; absent on entries that predate it. */
|
|
298
|
+
readonly createdAt?: number;
|
|
299
|
+
/** S10: an `application` entry's `acceptedDigest` — the state it was delivered under (a rewind abandoning it withdraws it). */
|
|
300
|
+
readonly node?: string;
|
|
301
|
+
/**
|
|
302
|
+
* S5 (AC-RACE-1): set on a confirmed own self-update commit's entry — its own `intentId` — so a later rewind
|
|
303
|
+
* that withdraws it (via `node`, the same mechanism as an application message) can re-enqueue an equivalent
|
|
304
|
+
* intent at the new tip. Absent on every other entry kind.
|
|
305
|
+
*/
|
|
306
|
+
readonly selfUpdateIntentId?: string;
|
|
307
|
+
/**
|
|
308
|
+
* S5 (AC-RACE-1): the confirmed self-update record's own `attempts` at confirm time, carried alongside
|
|
309
|
+
* `selfUpdateIntentId` so a re-enqueue built from this entry inherits the remaining `maxPublishAttempts`
|
|
310
|
+
* budget instead of resetting it on every withdrawal. Absent on every entry `selfUpdateIntentId` is absent on.
|
|
311
|
+
*/
|
|
312
|
+
readonly attempts?: number;
|
|
313
|
+
/**
|
|
314
|
+
* Epic marmot-device-key-rotation (S6, AC-REKEY-7): on a confirmed own REKEY self-update's entry, the target key
|
|
315
|
+
* (hex) it rotated the leaf to — so the re-enqueue a rewind causes is a `rekey` toward the same target, not a plain
|
|
316
|
+
* self-update. Absent on every entry `selfUpdateIntentId` is absent on, and on a plain self-update's.
|
|
317
|
+
*/
|
|
318
|
+
readonly rekey?: string;
|
|
319
|
+
/**
|
|
320
|
+
* Epic marmot-rewound-own-commit-no-signal (S8, AC-MARK-3): set, together with `node`, on a confirmed own commit's
|
|
321
|
+
* entry — the ROOT intent id of the call that made it. A distinct discriminator from `selfUpdateIntentId` and
|
|
322
|
+
* `rekey`, which it never accompanies (the reader refuses a combination, and a value without `node`). Set by the
|
|
323
|
+
* confirm writer and the DD17 stale-settle (pipeline.ts); read by `planTransition` (S1), which keeps the entry out of
|
|
324
|
+
* `message-withdrawn`, withdraws it in the ledger and re-drives it when its marker names changes. The marker (`marmot.own-commit`, keyed by
|
|
325
|
+
* the same event id) holds the re-drive facts.
|
|
326
|
+
*/
|
|
327
|
+
readonly ownCommitRoot?: string;
|
|
328
|
+
}
|
|
329
|
+
export declare function readTerminalLedgerEntry(view: KeyValueView, eventId: string): Promise<TerminalLedgerEntry | undefined>;
|
|
330
|
+
export declare function writeTerminalLedgerEntry(view: KeyValueView, eventId: string, entry: TerminalLedgerEntry): Promise<void>;
|
|
331
|
+
/**
|
|
332
|
+
* Retention: deletes every entry whose event `created_at` is below
|
|
333
|
+
* `belowCreatedAt`. The ingest cursor's `since` bounds what a relay can
|
|
334
|
+
* still redeliver, so an entry far below it no longer dedups anything the
|
|
335
|
+
* sync loop fetches; an older event fed to `ingest()` by hand falls back on
|
|
336
|
+
* the engine's own past-epoch / duplicate rules. Entries without a
|
|
337
|
+
* `createdAt` are kept, and so is every entry whose `node` is in `retained`
|
|
338
|
+
* (the stored rewind window's nodes, `retainedLedgerNodes`): a fork flip
|
|
339
|
+
* through that node still needs it for withdrawal detection and the
|
|
340
|
+
* self-update re-enqueue / cancel (ledger-retention-vs-rewind-horizon).
|
|
341
|
+
* Returns the number deleted.
|
|
342
|
+
*/
|
|
343
|
+
export declare function pruneTerminalLedger(view: KeyValueView, belowCreatedAt: number, retained?: ReadonlySet<string>): Promise<number>;
|
|
344
|
+
/**
|
|
345
|
+
* One change of an own commit as stored for the re-drive (DD2, DD11-DD16): the diff entry itself, the child's bytes of
|
|
346
|
+
* a `component` change, the values at the FORK POINT (the common ancestor of the withdrawn branch and the winner) that
|
|
347
|
+
* the re-drive classifies against, the winner-side evidence, and the persisted verdict. A union on `change.type`
|
|
348
|
+
* carrying exactly the members each kind has (the decoder enforces the same rule): `component` has `data` (the
|
|
349
|
+
* child's value, `null`: the commit deleted the entry) and `fork.component` (`null`: absent at the fork point);
|
|
350
|
+
* `admin` has `fork.admin`; `member-removed` has `fork.leafKeys` (the account's keys at the fork point, closed under
|
|
351
|
+
* the successions the winner shows, DD12); `member-added` has `fork.held` (DD16), the invitee's `keyPackage` ({ event, inviteeRef }) and may have `winnerHeldInvitee` (winner-side evidence).
|
|
352
|
+
* `verdict` (DD11: the decided outcome, persisted before it is dispatched) is on all kinds.
|
|
353
|
+
*/
|
|
354
|
+
export type StoredOwnChange = OwnChangeVariant & {
|
|
355
|
+
readonly verdict?: OwnChangeLostReason | 'reapplied';
|
|
356
|
+
};
|
|
357
|
+
/** A {@link StoredOwnChange} without a verdict — the marker's change list never carries one. On a MARKER its fork values are not authoritative: a withdrawal recomputes them and uses the list only to say which changes belong to the root. */
|
|
358
|
+
export type MarkerChange = OwnChangeVariant;
|
|
359
|
+
type OwnChangeVariant = {
|
|
360
|
+
readonly change: Extract<OwnChange, {
|
|
361
|
+
readonly type: 'component';
|
|
362
|
+
}>;
|
|
363
|
+
readonly data: Uint8Array | null;
|
|
364
|
+
readonly fork: {
|
|
365
|
+
readonly component: Uint8Array | null;
|
|
366
|
+
};
|
|
367
|
+
} | {
|
|
368
|
+
readonly change: Extract<OwnChange, {
|
|
369
|
+
readonly type: 'admin';
|
|
370
|
+
}>;
|
|
371
|
+
readonly fork: {
|
|
372
|
+
readonly admin: boolean;
|
|
373
|
+
};
|
|
374
|
+
} | {
|
|
375
|
+
readonly change: Extract<OwnChange, {
|
|
376
|
+
readonly type: 'member-removed';
|
|
377
|
+
}>;
|
|
378
|
+
readonly fork: {
|
|
379
|
+
readonly leafKeys: readonly string[];
|
|
380
|
+
};
|
|
381
|
+
/** Winner-side fact (DD4, amended): a commit of the winning branch above the fork point removed the target. Absent: not established. */
|
|
382
|
+
readonly winnerRemovedTarget?: boolean;
|
|
383
|
+
} | {
|
|
384
|
+
readonly change: Extract<OwnChange, {
|
|
385
|
+
readonly type: 'member-added';
|
|
386
|
+
}>;
|
|
387
|
+
readonly fork: {
|
|
388
|
+
readonly held: boolean;
|
|
389
|
+
};
|
|
390
|
+
/** Winner-side fact (absent: not established). */
|
|
391
|
+
readonly winnerHeldInvitee?: boolean;
|
|
392
|
+
/**
|
|
393
|
+
* The invitee's KeyPackage event and ref (copied from the marker's invitees at withdrawal): a re-drive record is
|
|
394
|
+
* self-sufficient because the node-only marker prune (DD6) can drop the original marker before a delayed or
|
|
395
|
+
* repeated re-drive builds (S1 lead decision 2026-10-29).
|
|
396
|
+
*/
|
|
397
|
+
readonly keyPackage: {
|
|
398
|
+
readonly event: Storable;
|
|
399
|
+
readonly inviteeRef: string;
|
|
400
|
+
};
|
|
401
|
+
};
|
|
402
|
+
export type Fail = (detail: string) => MarmotError;
|
|
403
|
+
export declare function decodeOwnChange(raw: unknown, at: string, fail: Fail): OwnChange;
|
|
404
|
+
/**
|
|
405
|
+
* Strict decoder of one {@link StoredOwnChange}: a wrong type anywhere is a `store-failed` error built by `fail` (so
|
|
406
|
+
* the pending record and the marker each report under their own key). Shared by both records.
|
|
407
|
+
*/
|
|
408
|
+
export declare function decodeStoredOwnChange(raw: unknown, at: string, fail: Fail, allowVerdict?: boolean): StoredOwnChange;
|
|
409
|
+
/** The `Storable` form of a {@link StoredOwnChange}; absent members stay absent (so a decode re-encodes identically). */
|
|
410
|
+
export declare function encodeStoredOwnChange(c: StoredOwnChange, allowVerdict?: boolean): Storable;
|
|
411
|
+
/**
|
|
412
|
+
* The group extension holding one {@link OwnCommitMarker} per confirmed own commit, keyed by the commit's event id —
|
|
413
|
+
* the same key as its terminal-ledger entry (whose `ownCommitRoot` flags it). Written by the confirming transaction
|
|
414
|
+
* (S9); read when a rewind withdraws the commit.
|
|
415
|
+
*/
|
|
416
|
+
export declare const OWN_COMMIT_EXTENSION = "marmot.own-commit";
|
|
417
|
+
/**
|
|
418
|
+
* Everything the re-drive needs of a confirmed own commit that the ledger entry does not carry.
|
|
419
|
+
* `changes` / `forkEpoch` are written ONCE at the commit's first withdrawal (DD14) and never carry verdicts (the pending re-drive record is the only verdict carrier, DD11), `invitees` at confirm of an invite
|
|
420
|
+
* commit (DD8/DD16: the KeyPackage event and ref to re-add, and the invitee's leaf key at the time of the commit).
|
|
421
|
+
*/
|
|
422
|
+
export interface OwnCommitMarker {
|
|
423
|
+
readonly v: 1;
|
|
424
|
+
/** The root intent id (equals the ledger entry's `ownCommitRoot`). */
|
|
425
|
+
readonly root: string;
|
|
426
|
+
/** The commit's confirmation node (equals the ledger entry's `node`) — marker retention follows it (DD6). */
|
|
427
|
+
readonly node: string;
|
|
428
|
+
/** The confirmed record's `attempts`, so a re-drive inherits the remaining publish budget. */
|
|
429
|
+
readonly attempts: number;
|
|
430
|
+
readonly invitees?: readonly {
|
|
431
|
+
readonly event: Storable;
|
|
432
|
+
readonly inviteeRef: string;
|
|
433
|
+
readonly leafKey: string;
|
|
434
|
+
}[];
|
|
435
|
+
/**
|
|
436
|
+
* What the commit's intent declared besides an invite (DD2), written at confirm (S1): the withdrawal-time breakdown
|
|
437
|
+
* keeps only the diff entries the intent declared. Absent on a re-drive's marker (its `changes` are already the
|
|
438
|
+
* declared ones) and on a marker of an invite-only commit (the `invitees` declare the Adds).
|
|
439
|
+
*/
|
|
440
|
+
readonly declared?: OwnCommitDeclared;
|
|
441
|
+
/** With `forkEpoch` (both or neither); never carries verdicts. */
|
|
442
|
+
readonly changes?: readonly MarkerChange[];
|
|
443
|
+
readonly forkEpoch?: number;
|
|
444
|
+
}
|
|
445
|
+
/** The declared changes a marker stores: `removed` accounts, `admins` set, component ids (the Adds come from `invitees`). */
|
|
446
|
+
export type OwnCommitDeclared = Pick<DeclaredChanges, 'removed' | 'components'> & {
|
|
447
|
+
readonly admins?: true;
|
|
448
|
+
};
|
|
449
|
+
export declare function decodeOwnCommitMarker(eventId: string, raw: unknown): OwnCommitMarker;
|
|
450
|
+
export declare function encodeOwnCommitMarker(marker: OwnCommitMarker, eventId?: string): Storable;
|
|
451
|
+
/** `view` is the group's `OWN_COMMIT_EXTENSION` namespace. */
|
|
452
|
+
export declare function readOwnCommitMarker(view: KeyValueView, eventId: string): Promise<OwnCommitMarker | undefined>;
|
|
453
|
+
export declare function writeOwnCommitMarker(view: KeyValueView, eventId: string, marker: OwnCommitMarker): Promise<void>;
|
|
454
|
+
/**
|
|
455
|
+
* DD9: the part of its root's publish budget a commit re-drive record holds that no marker does yet — its failed
|
|
456
|
+
* publishes and re-mints (`attempts`) and, while a relay-accepted publish awaits its confirm (`pending-confirm`), the
|
|
457
|
+
* one publish that confirm would have counted.
|
|
458
|
+
*/
|
|
459
|
+
export declare function redriveSpendOf(record: Pick<PendingIntentRecord, 'attempts' | 'state'>): number;
|
|
460
|
+
/** DD9: the highest spend any marker of `root` in `view` (the `OWN_COMMIT_EXTENSION` namespace) records; 0 when none. */
|
|
461
|
+
export declare function rootMarkerSpend(view: KeyValueView, root: string): Promise<number>;
|
|
462
|
+
/**
|
|
463
|
+
* DD9: raises every marker of `root` in `view` — or only those of `eventIds` — to at least `spend` attempts (max-based,
|
|
464
|
+
* idempotent), so a later restore or withdrawal seeds its record from the marker instead of a fresh budget.
|
|
465
|
+
*/
|
|
466
|
+
export declare function raiseRootSpend(view: KeyValueView, root: string, spend: number, eventIds?: Iterable<string>): Promise<void>;
|
|
467
|
+
export declare function deleteOwnCommitMarker(view: KeyValueView, eventId: string): Promise<void>;
|
|
468
|
+
/**
|
|
469
|
+
* Marker retention follows the node (DD6, AC-MARK-4): deletes every marker whose `node` is not in `retained` (the
|
|
470
|
+
* stored rewind window's nodes, `retainedLedgerNodes`) — whether or not its terminal-ledger entry still exists: a
|
|
471
|
+
* node that left the window can no longer be abandoned or restored by a fork flip, so its marker has nothing left to
|
|
472
|
+
* serve. `retained` is required so a caller cannot prune against an empty window by omission. Returns the number
|
|
473
|
+
* deleted. Called by the ingest ledger prune, in its transaction (S9).
|
|
474
|
+
*/
|
|
475
|
+
export declare function pruneOwnCommitMarkers(markers: KeyValueView, retained: ReadonlySet<string>): Promise<number>;
|
|
476
|
+
/**
|
|
477
|
+
* Reads the group's persisted kind-445 ingest cursor, or `undefined` when
|
|
478
|
+
* history has never been synced. `pins`, `busy` and `resume` are optional: a
|
|
479
|
+
* record written before those tiers existed decodes with every hold in the
|
|
480
|
+
* evictable tier, and without a resume window.
|
|
481
|
+
*/
|
|
482
|
+
export declare function readIngestCursor(view: KeyValueView): Promise<IngestCursor | undefined>;
|
|
483
|
+
/** Persists `cursor` as the group's kind-445 ingest cursor. */
|
|
484
|
+
export declare function writeIngestCursor(view: KeyValueView, cursor: IngestCursor): Promise<void>;
|
|
485
|
+
export {};
|