@941design/marmot 0.0.0-stage → 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 +739 -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 +190 -0
- package/dist/account/teardown.js +878 -0
- 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-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 +182 -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 +92 -0
- package/dist/client/commit-redrive.js +274 -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 +55 -0
- package/dist/client/confirm-hooks.js +74 -0
- package/dist/client/create-client.d.ts +1126 -0
- package/dist/client/create-client.js +1232 -0
- package/dist/client/group-availability.d.ts +182 -0
- package/dist/client/group-availability.js +301 -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 +461 -0
- package/dist/client/group-history.js +1365 -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 +522 -0
- package/dist/client/group-records.js +1117 -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 +415 -0
- package/dist/client/group-runtime.js +2811 -0
- package/dist/client/group-snapshot.d.ts +104 -0
- package/dist/client/group-snapshot.js +474 -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 +24 -0
- package/dist/client/index.js +13 -0
- package/dist/client/ingest.d.ts +82 -0
- package/dist/client/ingest.js +1584 -0
- package/dist/client/invitation-outcomes.d.ts +50 -0
- package/dist/client/invitation-outcomes.js +135 -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 +82 -0
- package/dist/client/opaque-candidates.js +170 -0
- package/dist/client/own-change-outbox.d.ts +66 -0
- package/dist/client/own-change-outbox.js +158 -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 +583 -0
- package/dist/client/pipeline.js +3666 -0
- package/dist/client/reentrancy-guard.d.ts +102 -0
- package/dist/client/reentrancy-guard.js +159 -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/admission-lineage.d.ts +186 -0
- package/dist/history/admission-lineage.js +589 -0
- package/dist/history/equivocation.d.ts +55 -0
- package/dist/history/equivocation.js +113 -0
- package/dist/history/fencing.d.ts +66 -0
- package/dist/history/fencing.js +121 -0
- package/dist/history/hex.d.ts +3 -0
- package/dist/history/hex.js +10 -0
- package/dist/history/index.d.ts +74 -0
- package/dist/history/index.js +32 -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 +118 -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 +67 -0
- package/dist/invitations/decline.js +149 -0
- package/dist/invitations/delivery-evidence.d.ts +288 -0
- package/dist/invitations/delivery-evidence.js +766 -0
- package/dist/invitations/expect-welcome.d.ts +66 -0
- package/dist/invitations/expect-welcome.js +138 -0
- package/dist/invitations/index.d.ts +18 -0
- package/dist/invitations/index.js +18 -0
- package/dist/invitations/invitation-outcome.d.ts +110 -0
- package/dist/invitations/invitation-outcome.js +210 -0
- package/dist/invitations/invite.d.ts +358 -0
- package/dist/invitations/invite.js +1102 -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 +272 -0
- package/dist/invitations/welcome-processor.js +1241 -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 +28 -0
- package/dist/shared/errors.js +96 -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 +237 -0
- package/dist/storage/index.js +491 -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 +54 -0
- package/dist/storage/lease.js +168 -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
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,739 @@
|
|
|
1
|
+
# @941design/marmot
|
|
2
|
+
|
|
3
|
+
## 0.2.0-alpha.1
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- a7a483c: `client.invitations.cleanupDisposition(ref)` reads, by a decline candidate's `cleanupRef`, what the store's durable evidence proves about the admission that delivery made: `eligible` (the proven original admission is present), `absent` (`add-off-path`, `occupancy-ended`) or `insufficient-evidence` (`unresolved-selector`, `ambiguous-legacy`, `no-anchor`, `lineage-gap`), as `CleanupDispositionReport` `{ groupId, candidateId, disposition, cause?, lastKnown }`. An admission is the leaf one exact Add commit inserted, continuing through verified Updates and ending at the first Remove of that position; re-adding the same position, key or last-resort KeyPackage is a new admission. The read is offline and read-only (no runtime, no publication, no intent, no store write), answers on a fenced group with `lastKnown: true`, rejects `invalid-options` (`malformed-reference`, `foreign-reference`, `unknown-reference`) with no effect, and rejects `reentrant` synchronously from inside group hooks, consumer group-store calls and account-scope callbacks. New exported types: `CleanupDispositionReport`, `CleanupDisposition`, `CleanupDispositionCause`.
|
|
8
|
+
|
|
9
|
+
Admission lineage is kept per anchored delivery in the new group extension `marmot.admission-lineage`, advanced with every persisted transition, and carried by group snapshots (an additive optional payload field); `groups.restore` keeps only what the snapshot's own window proves and reads everything else as insufficient evidence until re-proven.
|
|
10
|
+
|
|
11
|
+
Behaviour change: cleanup references (and `DeclineCandidate.cleanupRef`) always carry the signer's account, never a custom `AccountStore.account` that differs from it.
|
|
12
|
+
- a7a483c: `client.invitations.declineCandidates({ after?, limit? })` recovers, offline and from the account store alone, every Welcome delivery its invitee's account declined, as stable candidates: `{ candidateId, groupId, recipient, inviteeRef, welcomeId, status: 'actionable' | 'ambiguous', basis: 'unqualified' | 'qualified' | 'legacy', rev, cleanupRef }`, in bounded pages with explicit completion. The new `declineCandidate` event reports each new candidate, late match and refinement after it is durable; register it before scanning and deduplicate by `(candidateId, rev)`. The scan is read-only: no publication, no intent, no pruning, no store write, no group opened. It rejects `reentrant` synchronously from inside an account-scope store, signer or verifier callback. New exported types: `DeclineCandidate`, `DeclineCandidatePage`, `CleanupReference`.
|
|
13
|
+
|
|
14
|
+
Every issued delivery now keeps small, payload-free evidence (new account extensions `marmot.delivery-evidence` and `marmot.decline-evidence`) that outlives `inviteRetentionMs` and is removed with the group or an account wipe, so a decline arriving after the retry payload was pruned still matches. Retained records of earlier releases are backfilled lazily.
|
|
15
|
+
|
|
16
|
+
Behaviour changes: `welcomeDeclined` gains `candidateId`. `invitations.decline(id, { declineRumor: true })` adds the consumed `keyPackageRef` to the v1 DECLINE rumor (older readers ignore it); an upgraded inviter then declines only that delivery, leaving a sibling device's delivery and retries untouched, and a present but invalid selector changes nothing. An unqualified decline of a Welcome shared by several devices of one account still declines every retained delivery, and its candidates stay `ambiguous` until a device qualifies its own.
|
|
17
|
+
- a7a483c: `MarmotGroup.observeAvailability(listener)` observes a group's availability without a subscription gap. Each `GroupAvailability` reports three independent facts: the fence (`clear` or `fenced` with a coarse `FenceCause`: `lost-path-secrets`, `invalid-stored-evidence` or `unknown`), the sync state (`syncing` / `synced`) and the membership (`member`, `membership-lost`, `disbanded`). It also reports `writable`. The current snapshot is delivered at once, then every change in order, with a strictly increasing `seq`. A fence is an ordinary observation: the subscription stays open, and within a client session no `clear` follows `fenced`, even when the fence marker could not be written. Exactly one `ended` closes a subscription. Its reason is `torn-down`, `restore-undone`, `disposed` or `no-lease`, and `final.writable` is `false`. After that, a new subscription gets the `ended` at once.
|
|
18
|
+
|
|
19
|
+
The storage port gains an optional `AccountStore.onLeaseEnded(listener)`. The built-in memory and IndexedDB backends fire it once when the lease is released, closed or stolen by another context. The client then ends every group's availability `no-lease` at once, without scheduling group work.
|
|
20
|
+
|
|
21
|
+
Behaviour change: a present but malformed fence marker now fences the group on load (`invalid-stored-evidence`) instead of being read as no fence. Fence markers now record their cause; a marker written before this release reads `unknown`. An ingest batch that reaches a fence verdict but fails to commit now fences the client session in memory (rolled back, no marker), where it used to leave the group unfenced.
|
|
22
|
+
- a7a483c: `client.invitations.outcome(id)` reports whether one exact Welcome caused this device to join its group: `pending`, `joining` (resumable), `unresolved` (a competing Welcome or a restore-deferred join still waiting), `joined` (`via: 'adoption'` or `'switch'`), `not-joined` (`declined`, `rejected` or `kept-out`, with the stored reason as `detail`), `unknown` (no record) or `indeterminate` (a record from an earlier release without invitation-specific evidence). The answer is read at one instant from durable evidence only: a new `marmot.adoption` proof written in the adoption's own group transaction, the existing branch-switch proof, an adoption stamp on the invitation record (written when the join completes and by teardown before the group is deleted), or, for records written before this release, the group index entry's `adoptedBy`. A `joined` outcome survives teardown, other invitations' branch switches and restarts. The read works before `inbox.start()`, runs behind the current inbox task, never publishes or writes, rejects `store-failed`/`no-lease` instead of guessing, and rejects `reentrant` synchronously when called from inside a hook, an inbox handler or another account-scope consumer surface. The new type `InvitationOutcome` is exported.
|
|
23
|
+
|
|
24
|
+
`invitations.accept(id)` is unchanged and can still resolve with the held group's handle for a Welcome that was kept out; `outcome(id)` is the authoritative read.
|
|
25
|
+
|
|
26
|
+
Behaviour change: tearing down a group whose join was interrupted after its group state committed (but before the `joined` record) now keeps that invitation `joined` (stamped) instead of turning it `rejected` with reason `abandoned`. A redelivered Welcome still answers `already-member` and does not bring the group back.
|
|
27
|
+
- a7a483c: `MarmotGroup.removeAdmission(ref)` removes exactly the one admission a declined delivery made — the leaf position the decline candidate's proven original Add put in the group — by the candidate's `cleanupRef`, re-deriving authority from durable evidence and lineage on every call. It resolves a `CleanupDispositionReport`: `pending` (root `intentId`) once the cleanup is durably accepted, or the current non-eligible disposition. A submit for a cleanup already in flight (lost reply, awaiting confirmation, a library re-drive of a withdrawn one, after a restart) coalesces before anything is resumed: no transport call, no store write, no new intent. Refusals enqueue nothing: `fenced`, `not-a-member`, `invalid-options` (`malformed-reference`, `foreign-reference`, `unknown-reference`, `self`, `not-admin`), `confirm-blocked`, `commit-pending` (retryable), `send-rejected` with `details.retryable` (`staged-add-conflict`, `staged-removal-of-target`, `staged-admin-policy-update`). The commit is an inline Remove of the target position, built in the background after re-checking the admission on the actual parent; if the admission changed, ended or can no longer be proven there (`admission-changed`, `admission-ended`, `admission-unproven`), nothing is removed and the intent fails `send-rejected` (`intentFailed`).
|
|
28
|
+
|
|
29
|
+
`invitations.cleanupDisposition(ref)` now also reports `pending`, `removed-revisable` and `removed-settled` (with `intentId` / `commitDigest`); attribution comes only from the cleanup's own confirmed inline Remove on the selected path, and settlement happens once `REWIND_HORIZON` later commits follow the Remove (it has left the retained window). New client event `cleanupDisposition` (best effort). New group extension `marmot.admission-cleanup`.
|
|
30
|
+
|
|
31
|
+
Behaviour change (pre-1.0 minor): the public `OwnChange` union gained `{ type: 'admission-removed'; account; leafKey; candidateId }`; exhaustive switches over it need the new case. A cleanup is never reported as `member-removed` and never re-driven as an account-wide removal.
|
|
32
|
+
|
|
33
|
+
## 0.2.0-alpha.0
|
|
34
|
+
|
|
35
|
+
### Minor Changes
|
|
36
|
+
|
|
37
|
+
- c425a58: The engine stamp stored envelopes are compared against is now a stored-state format, `ENGINE_VERSION = "state.<N>"`
|
|
38
|
+
(`ENGINE_STATE_FORMAT`), instead of a digest of the engine code; the code identity moves to the new `ENGINE_BUILD`.
|
|
39
|
+
Engine changes that leave stored state reading the same (a comment, a read-only accessor) no longer refuse every store;
|
|
40
|
+
`state-format-ledger.json` and a test force a recorded decision on each code change.
|
|
41
|
+
This change itself moves the stamp once: stores written by earlier builds are refused with `storeIncompatible`.
|
|
42
|
+
- c538b1a: Generic client extension points for `account-sync`:
|
|
43
|
+
|
|
44
|
+
- `ConfirmContext` gains `snapshot: GroupSnapshot` — an opaque, branded `Storable` in marmot's versioned
|
|
45
|
+
envelope holding what `groups.restore` needs to resume as that leaf (state, retained rewind window, index
|
|
46
|
+
`createdAt`, cursor floor; restorable only by the same engine + ts-mls build). It is built lazily on first
|
|
47
|
+
read and readable only while the hook runs (`transaction-closed` afterwards) — and `kind` becomes the new
|
|
48
|
+
`ConfirmKind` (`GroupIntent['type'] | 'create' | 'join'`). `onConfirm` hooks now also run inside
|
|
49
|
+
`groups.create`'s persisting transaction (`kind: 'create'`) and inside a Welcome adoption's
|
|
50
|
+
(`kind: 'join'`), with `intentId` = group id and no notifications; a hook throw aborts the creation or
|
|
51
|
+
adoption like a confirmation. **Behaviour change:** a hook registered before `groups.create` now runs for
|
|
52
|
+
the creation too.
|
|
53
|
+
- `groups.restore(groupId, snapshot)`: adopts a snapshot, replays the group's commits from its relays,
|
|
54
|
+
commits a self-update and resolves the handle once that self-update is confirmed; a fence, teardown or
|
|
55
|
+
dispose ends it at once and removes the adopted group. After a dispose or crash mid-restore the next client
|
|
56
|
+
over the same stores resumes the unfinished adoption (marked by the group extension `marmot.restorePending`)
|
|
57
|
+
on its own — a startup scan, or any access — re-publishing a recorded self-update byte-identically and
|
|
58
|
+
confirming it, or committing a fresh one; the group is discarded only when that self-update goes terminal for
|
|
59
|
+
good or the group is fenced. `groups.list()` skips a group being restored, and a
|
|
60
|
+
Welcome for it is deferred (`inboxDisposition` `pending`, invitation kept `joining`, never blocking the inbox)
|
|
61
|
+
and completed by the inbox pass the restore's settling runs. A second `groups.restore` while a failed one is still
|
|
62
|
+
being taken back rejects `commit-pending` (`reason: 'restore-ending'`, retryable). New error code `already-member`.
|
|
63
|
+
A snapshot whose rewind window carries, as a link, anything but a framed MLS Commit (e.g. a genuine application
|
|
64
|
+
message with its true digest) is refused `envelope-mismatch` (`reason: 'malformed'`) before anything is written.
|
|
65
|
+
- `groups.restore` and `extensions.sendInboxRumor` reject `reentrant` from inside a group's `onConfirm` hook.
|
|
66
|
+
- `extensions.sendInboxRumor({ to, rumor })`: one gift-wrapped rumor to a recipient's inbox relays through
|
|
67
|
+
the budgeted signer, `{ status: 'delivered' | 'retryable' | 'failed', reason?, relays? }`; refuses
|
|
68
|
+
`RUMOR_KINDS` with `reserved-kind`; persists nothing.
|
|
69
|
+
- New public types `GroupSnapshot`, `ConfirmKind`, `InboxRumorDelivery`.
|
|
70
|
+
- 74bc747: The branch-aware own-leaf fence's hidden-credit policy defaults to anchored-zero: a clone of this
|
|
71
|
+
device's own leaf can no longer fence the real device by publishing a burst it cannot read, as long as canonical
|
|
72
|
+
carries another member's commit after the fork. The residual — members who followed the clone — is reported by the
|
|
73
|
+
device's `leaf-equivocation` record. No wire or stored-format change.
|
|
74
|
+
- e77d367: `extensions.onBeforePublish(hook)` — a pre-publish extension point for an own `commit` / `self-update`:
|
|
75
|
+
|
|
76
|
+
- The hook runs between the commit's staging and its first publish, once per staged envelope, in its own
|
|
77
|
+
group-store transaction (a throw rolls back only that hook's writes), handed a `BeforePublishContext`
|
|
78
|
+
(`{ groupId, intentId, kind, epoch, commit: { eventId, digest, parentTag, tag }, tx, snapshot, forgetting?,
|
|
79
|
+
resumed }`). After a crash between staging and the publish the resume path runs it again (`resumed: true`);
|
|
80
|
+
hooks must be idempotent per `commit.digest`. It never runs for application messages, proposals,
|
|
81
|
+
`groups.create`, a Welcome adoption, a foreign commit's ingest or the `groups.restore` adoption itself.
|
|
82
|
+
- `ctx.snapshot` is a **pending-tagged `GroupSnapshot`** of the state the commit produces (payload kind
|
|
83
|
+
`marmot.groupSnapshot.pending`, carrying `pending: { digest, parentTag }`; its window's tip edge is the commit
|
|
84
|
+
from its parent). A build that predates it refuses such a snapshot (`envelope-mismatch`), and
|
|
85
|
+
`groups.restore` rejects an inconsistent pending payload before anything is written. `ConfirmContext.snapshot`
|
|
86
|
+
is unchanged (today's kind, never pending-tagged). `groups.restore` resolves the marker (see the
|
|
87
|
+
`groups.restore` pending-snapshot entry).
|
|
88
|
+
- A hook may return a `PublishBarrier` — the commit's first publish waits for it, best-effort and bounded: all
|
|
89
|
+
barriers run concurrently under one deadline `options.beforePublishTimeoutMs` (new, integer >= 1, default
|
|
90
|
+
10 000 ms); a rejection or the deadline abandons a barrier (its `AbortSignal` fires) and the commit is
|
|
91
|
+
published anyway, reported by the new `beforePublishSkipped` client event
|
|
92
|
+
(`reason: 'hook-error' | 'barrier-failed' | 'barrier-timeout'`).
|
|
93
|
+
- `onBeforePublish` is a guarded consumer surface: from inside the hook or the barrier, mutating group
|
|
94
|
+
operations, `groups.restore`, `devices.*` and `extensions.sendInboxRumor` reject `reentrant`.
|
|
95
|
+
|
|
96
|
+
With no hook registered, behaviour is unchanged.
|
|
97
|
+
- 5ee090c: Branch-aware own-leaf fence: the own-leaf fence of
|
|
98
|
+
`groups.restore` and of every sync is now branch-aware — the group is fenced only whenever the opaque branch could win.
|
|
99
|
+
|
|
100
|
+
`@941design/marmot` opts in to the engine seam (`branchAwareFence`, a single literal beside `equivocationCredit` in
|
|
101
|
+
`group-runtime.ts`). A device whose state predates a commit of its own leaf that it cannot open used to be fenced the
|
|
102
|
+
moment it met one; it is now fenced only if the best case of that unreadable branch could still be the canonical one.
|
|
103
|
+
A snapshot taken before an own commit that lost a same-epoch race — canonical won it, deeper or by the tiebreak,
|
|
104
|
+
and holds no own-leaf commit after the snapshot — is restored unfenced onto the canonical tip, with `U = 0` and
|
|
105
|
+
mutual decryption, whichever of the two competing commits the history batch lists first (a restore whose own commit
|
|
106
|
+
won the race, or that a later own commit of the leaf followed — e.g. a re-driven self-update — stays `fenced`, as does
|
|
107
|
+
a sole member's). The `groups.restore` documentation says so: `fenced` reads "whenever the opaque branch
|
|
108
|
+
could win".
|
|
109
|
+
|
|
110
|
+
- **Conservative default policy, pending a decision.** The hidden-credit policy is one constant,
|
|
111
|
+
`MARMOT_HIDDEN_CREDIT_POLICY = 'conservative'` (`history/policy.ts`); it is not a public client option. Under it
|
|
112
|
+
the goal — the real device staying unfenced after a cloned-leaf burst — is not met against a
|
|
113
|
+
deliberate attacker (the device is fenced and still records the `leaf-equivocation`); the `anchored-zero` policy
|
|
114
|
+
would meet it, and flipping the default after that decision is that one constant.
|
|
115
|
+
- **New persisted group extension `marmot.opaque`.** The engine's held candidates and the group's undecryptable
|
|
116
|
+
count `U` are persisted in the batch transaction that ledgers the provisional `skipped`, restored on load and on
|
|
117
|
+
reload and handed to every rebuilt engine (gate and fence rollbacks included). A fence deletes the record in its
|
|
118
|
+
own transaction; with the engine seam off nothing is ever written. The record is unbounded in `U` and rewritten
|
|
119
|
+
whole on a change.
|
|
120
|
+
- **Fail closed.** A stored `marmot.opaque` record that fails validation, or that the engine refuses, FENCES the group
|
|
121
|
+
on load and on reload — reading it as "nothing held" would forget a candidate that may still win, handing it on
|
|
122
|
+
would brick the load.
|
|
123
|
+
- **Pre-join history and batches.** Groups whose history fetch carries envelopes the device can never open —
|
|
124
|
+
the pre-join history of a late joiner, junk — carry a high `U` and fall back to today's fence, even for a lost race
|
|
125
|
+
with no re-drive. The verdict is taken on the whole call: `group.ingest(events)` and a sync pass's history window
|
|
126
|
+
hand the engine their events one at a time and settle once at the end (batch settle), so the order of the events in
|
|
127
|
+
one call does not matter. Residuals: live delivery is one event per call, so a lone own-leaf commit that arrives
|
|
128
|
+
alone is fenced on arrival (sound for what the device has received; a fence is terminal), and a history walk that
|
|
129
|
+
spans several windows decides each window as its own batch.
|
|
130
|
+
|
|
131
|
+
- **A fence decided by a call is taken at its end.** `group.ingest(events)` and a sync window settle once, after
|
|
132
|
+
every event of the call was stepped: the call's earlier events stay applied (application messages are delivered),
|
|
133
|
+
its other events keep their own dispositions, and every later call is `fenced`. Before the batch settle a fence
|
|
134
|
+
rolled back what the same drain had applied.
|
|
135
|
+
|
|
136
|
+
A new engine patch set changes `ENGINE_VERSION`: every store written by an earlier build is refused with
|
|
137
|
+
`storeIncompatible` (`envelope-mismatch`) and can be recovered by a wipe. See the `@941design/marmot-engine` changeset
|
|
138
|
+
for the engine side.
|
|
139
|
+
- 3182df9: `ConfirmContext` gains an optional `forgetting: { leafKeys }`. It is
|
|
140
|
+
set only on the confirmation of the Remove commit `devices.forget` issues in a
|
|
141
|
+
group — the signature keys of the leaves it removes — and omitted on every
|
|
142
|
+
other confirmation. `deviceForgotten` fires only once every group of the forget
|
|
143
|
+
settled, after this confirmation's hooks ran (and scheduled their publishes), so
|
|
144
|
+
the flag lets an `onConfirm` hook act on the forget before anything of that
|
|
145
|
+
confirmation leaves the device.
|
|
146
|
+
- cf51538: A second Welcome for a group the device holds is classified and decided. The
|
|
147
|
+
decision is the members' own rule, `compareBranchScores` over (epoch, committer, commit digest), where the competing
|
|
148
|
+
side's digest is the Welcome's `commit` tag; nothing switches a group yet (the group runtime implements the ports in
|
|
149
|
+
a later change), so a client without the ports keeps the earlier `already-member` answer.
|
|
150
|
+
|
|
151
|
+
- New pure `decideCompetingWelcome` / `judgeCompetingWelcome(held, competing)` answering `keep`, `switch` or
|
|
152
|
+
`undecidable` (with the reason a Welcome is kept: `same-branch`, `lower-epoch`, `same-lineage`,
|
|
153
|
+
`sponsor-not-a-member`, `beyond-horizon`, `lower-ranked`; `switch-failed` and `expired` end a record). A missing digest or committer at the step that needs it is
|
|
154
|
+
`undecidable`, never `switch`.
|
|
155
|
+
- `WelcomeServiceDeps.graceWindowMs` and `WelcomeServiceDeps.competing` (optional `CompetingWelcomePorts`: `competingGate`, `heldBranch`, `rebaseToWelcome`,
|
|
156
|
+
`onBranchSwitched`) and an optional fourth argument `joinEvidence` on `adoptJoinedGroup`.
|
|
157
|
+
- New `InvitationStatus` `competing`: a Welcome that could not be decided (its group's gate is closed, or the
|
|
158
|
+
comparison is undecidable) is held durably with its rumor and consumed key, re-decided on every inbox pass,
|
|
159
|
+
expires when the held tip passes its epoch or at the matching manifest's deadline, is not listed by
|
|
160
|
+
`invitations.pending()`, is rejected by `accept`, is removed with its group and counts as live for the consumed
|
|
161
|
+
key's retention. A kept Welcome is a terminal `joined` record carrying a `reason`.
|
|
162
|
+
- New `RumorDisposition` kind `branch-switched` (`invitationId`, `groupId`, `from`, `to`).
|
|
163
|
+
- `accept`, a late manifest and a stuck join of a held group run the same classification and decision.
|
|
164
|
+
- 5141e1a: Device key rotation. `client.devices.rotateKey()` replaces this device's MLS leaf
|
|
165
|
+
signature key (the device signing key) in every group and retires the KeyPackages signed with the old one. A device used
|
|
166
|
+
to keep one leaf key for the life of the install; it now has one key at a time and is a **lineage** of keys. Nothing
|
|
167
|
+
rotates unless the application calls `rotateKey()`: there is no automatic or scheduled rotation. Requires the
|
|
168
|
+
`@941design/marmot-engine` release with device key rotation support (its `selfUpdate` leaf-patch seam and `leafKeySuccessions`).
|
|
169
|
+
|
|
170
|
+
**API**
|
|
171
|
+
|
|
172
|
+
- **`devices.rotateKey()` / `devices.rotation()`.** `rotateKey()` resolves with `DeviceKeyRotationOutcome` `{ rotationId,
|
|
173
|
+
from, to, perGroupOutcome, settled, status }` once the new key is the device key and one pass drove every held group;
|
|
174
|
+
the rest continues in the background and after a restart. `perGroupOutcome` values are `rekeyed`, `satisfied`,
|
|
175
|
+
`removed`, `timed-out`, `cancelled` or `pending`; `status` is `rotating`, `rotated`, or `gave-up` (settled with a
|
|
176
|
+
`timed-out` group, which keeps its previous key and stays fully operable). `rotation()` returns the open rotation, else
|
|
177
|
+
the one that made the current device key, else the newest (`undefined` when the device never rotated). A call while a
|
|
178
|
+
rotation is open returns it. It rejects `invalid-options` with `details.reason` `no-device-key` (no key minted and no
|
|
179
|
+
group held), `device-forgetting` (see Precedence) or `rotation-unavailable` (a device service built without the group re-key
|
|
180
|
+
port or the KeyPackage retirement port; `createMarmotClient` wires both).
|
|
181
|
+
- **Events and unions (additive; an exhaustive `switch` needs the new cases or a default branch).** `deviceKeyRotated`
|
|
182
|
+
`{ rotationId, from, to, groups }` after the prepare committed and `deviceKeyRotationSettled` `{ rotationId,
|
|
183
|
+
perGroupOutcome }` when every group is terminal; each fires AT MOST ONCE per rotation, also across a crash (a crash
|
|
184
|
+
between the commit and the emit loses the event; read `devices.rotation()` for the durable state). `MarmotClientEvents`
|
|
185
|
+
gains both, `DeviceMaintenanceKind` gains `'device-rotation'` (a pass that keeps failing, or a KeyPackage retirement that
|
|
186
|
+
stays blocked, is given up after ten counted failures), and `GroupNotification` gains `leaf-key-rotated { account,
|
|
187
|
+
leafIndex, fromLeafKey, toLeafKey, commitDigest }`, `leaf-key-rotation-withdrawn` (same fields, when a rewind removes the
|
|
188
|
+
commit; `leaf-key-rotated` is delivered again if it rejoins the path) and `retired-key-readded { account, leafIndex,
|
|
189
|
+
leafKey, commitDigest }` (detection only: a commit added a leaf of the local account under a retired, non-head key of its
|
|
190
|
+
lineage; nothing is refused). New exports: `rotatedLeaves(parent, child)`, `successionsInWindow(window, tipState)` and the
|
|
191
|
+
types `LeafKeyRotatedNotification`, `LeafKeyRotationWithdrawnNotification`, `RetiredKeyReaddedNotification`,
|
|
192
|
+
`RotatedLeaf`, `WindowSuccession`, `DeviceKeyRotationOutcome`, `DeviceKeyRotationOutcomeStatus`.
|
|
193
|
+
- **`DeviceInfo` gains `previousLeafKeys` and `self`** (additive; an exact-keys assertion needs the two new members).
|
|
194
|
+
`devices.list()` returns one entry per DEVICE, under its lineage head (`leafKey` = the newest key, `previousLeafKeys` =
|
|
195
|
+
the older keys, oldest first, `self` = the local device), even while its groups hold different keys.
|
|
196
|
+
`devices.label(k, text)` takes any key of a chain and binds the label to the head. `devices.forget(k)` acts on the whole
|
|
197
|
+
chain (a group is `removed` only when no chain key is left in it, so a rotation landing between the Remove's build and
|
|
198
|
+
its read-back is never read as the leaf leaving; the kind-5 covers every chain key's KeyPackages; the tombstone follows
|
|
199
|
+
the lineage and is on the head; forgetting the own device leaves every group holding one of its keys).
|
|
200
|
+
|
|
201
|
+
**How it runs**
|
|
202
|
+
|
|
203
|
+
- **Prepare.** The account signer signs the new key's account identity proof ONCE; one account transaction then flips
|
|
204
|
+
`deviceRegistry/self` (the proof is stored with the key, the retired private half is dropped), records a durable
|
|
205
|
+
`rotation:<id>` intent with every held group, writes a `rotated:<oldKey>` link per replaced key and moves the registry
|
|
206
|
+
entry (label, enrolment time, tombstone) to the new key. The signer cost is that one proof plus the KeyPackage slot events (at most two
|
|
207
|
+
calls per replaced slot), independent of the number of groups.
|
|
208
|
+
- **Per group.** The device service re-keys each group's own leaf with a self-update whose UpdatePath leaf carries the new
|
|
209
|
+
key and the stored proof (no signer call per group), bounded concurrency of 4, and reads each group back from its state.
|
|
210
|
+
Three counted failed attempts, a fenced group, a refused proof or ten minutes undecided are `timed-out` (the ten minutes run per service instance, so a restart or a clock moving back restarts them, and never for a group whose own re-key commit is in flight). A group still on
|
|
211
|
+
an older key is an operable state, so a crash anywhere is resumed by the next `resumeInBackground` pass.
|
|
212
|
+
- **KeyPackage step.** Every slot whose KeyPackage carries a retired key is replaced by one on the device key (replacement
|
|
213
|
+
published first, kind-5 deletion of the old event only on relays that accepted it, so a slot is never without an
|
|
214
|
+
advertised KeyPackage and a Welcome built against the old one still joins within the grace window). A slot whose relays
|
|
215
|
+
refuse even the re-publish is blocked as `relay-unreachable` (a block reason, not a `status`): the rotation settles anyway and
|
|
216
|
+
the slot is retried once per service lifetime, at the first resume pass with no open rotation (up to three failed rechecks at
|
|
217
|
+
least 30 s apart); other blocks keep the rotation open on the capped backoff. After a crash that left a KeyPackage publish
|
|
218
|
+
pending the step can wait up to 30 s (`RESUME_BACKOFF_MS`) before it retries. A step given up after ten counted blocks
|
|
219
|
+
fires `maintenanceFailed` (`device-rotation`) while the rotation's `status` stays `rotated`.
|
|
220
|
+
- **Precedence.** Leaving beats re-keying. `rotateKey()` rejects `device-forgetting` while ANY record of a `devices.forget`
|
|
221
|
+
of the own device exists, open, settled or given up (a given-up forget, `gaveUp` set and never resumed, leaves its record
|
|
222
|
+
in place); the resume sweep is off under the same rule. The record is deleted when an enrolment approval for that
|
|
223
|
+
key finalizes in the store holding it (the approving sibling's) and, on the forgotten install itself, when a Welcome is
|
|
224
|
+
adopted (or switched to) under an enrolment request the device made at or after the forget started (settled or given-up
|
|
225
|
+
records and their tombstone; an open forget and a later forget are never cleared; a record whose kind-5 deletion is
|
|
226
|
+
still unsettled is marked superseded, ignored here and deleted once the deletion settles). `requestEnrolment()` rejects
|
|
227
|
+
`invalid-options` / `device-forgetting` while an own forget is open. An open rotation cancels its not-yet-terminal groups and its KeyPackage step when an
|
|
228
|
+
own forget is open or starts after it.
|
|
229
|
+
- **Resume sweep.** Independently of any rotation record, every resume pass of a device that holds retired keys re-keys each
|
|
230
|
+
held group whose own leaf carries a retired key of this device (a group created or joined on the old key across a prepare,
|
|
231
|
+
a group a rotation timed out in) toward the current key, with no new key and no signer call; once per pass, never re-armed,
|
|
232
|
+
with a per-group back-off after a refusal. A device that never rotated pays one registry read. A late Welcome join, a
|
|
233
|
+
competing-Welcome switch or a restore that lands a retired-key leaf records the same re-key. After `groups.restore` onto a replaced device, call
|
|
234
|
+
`rotateKey()` once: it re-keys the restored leaves and retires the lost key in the lineage only (the lost install's
|
|
235
|
+
KeyPackages are not deleted and stay advertised until they expire; a peer adding one raises `retired-key-readded`).
|
|
236
|
+
- **Dropped and refused re-keys.** A re-key with nothing left to do is dropped without a commit: `send-rejected` with
|
|
237
|
+
`details.reason` `already-rekeyed` (the leaf already carries the target) or `superseded` (the device key moved on), or,
|
|
238
|
+
when no caller is waiting, reported once through `intentFailed`, so an `intentFailed` listener can see failures for
|
|
239
|
+
self-updates it never sent. A re-key whose stored proof is absent or binds another key is refused `proof-invalid` before
|
|
240
|
+
anything is published. A re-key over staged Adds commits the Adds first and carries the re-key into a second commit; one
|
|
241
|
+
withdrawn by a fork rewind is re-enqueued toward the same target. The pending-intent record names only the public target
|
|
242
|
+
key; the private key and proof are read from the account store when the commit is built.
|
|
243
|
+
|
|
244
|
+
**Behaviour changes**
|
|
245
|
+
|
|
246
|
+
- **A rotation is no removal.** `leaf-removed` is no longer withheld for "the same account at the same index" but only for a
|
|
247
|
+
leaf that replaced its key in place, so a Remove plus an Add of the same account at one index (the new leaf from a
|
|
248
|
+
KeyPackage) is now announced as the `leaf-removed` it is. A duplicate-leaf repair commit announces one `leaf-key-rotated`
|
|
249
|
+
and no `leaf-removed`.
|
|
250
|
+
- **Duplicate-leaf repair and Add refusal.** When the target key is already in the tree at another index with the local
|
|
251
|
+
account's credential (an invite or a fork added the new-key KeyPackage), the re-key Removes that leaf in the same commit as
|
|
252
|
+
the path rotation (no admin right needed). `group.invite` and the enrolment Add refuse, sender-side only, a KeyPackage
|
|
253
|
+
of the device's own key chain when a chain key is already in the tree (`send-rejected`, `details.reason:
|
|
254
|
+
'device-already-member'`).
|
|
255
|
+
- **`removeMember` survives a rotation of its target.** A recorded `removeMember` is bounded by the leaf keys the account held
|
|
256
|
+
when it was called; a leaf now also counts when the target replaced that key in place since (a succession on the canonical
|
|
257
|
+
path of the retained window, or on an abandoned branch the window still shows), so the record is no longer dropped as
|
|
258
|
+
`absent` while the account still has that leaf. A re-add with a fresh KeyPackage stays "added later". A rotation older than
|
|
259
|
+
the retained rewind horizon is not visible to the bound.
|
|
260
|
+
- **Enrolment compares by lineage.** An approval recorded for a key whose device rotated is not reopened by a rewind and
|
|
261
|
+
causes no second Add; `enrolmentApproved.leafKey` is the key the joined leaf actually carries.
|
|
262
|
+
- **Successions are ingested** (a commit by the leaf itself, or a committed Update proposal of it) from the held groups' canonical-path windows at the first resume pass and on each
|
|
263
|
+
`leaf-key-rotated` notification (the local account only; a withdrawn rotation never un-records a link). A second, different
|
|
264
|
+
successor recorded for a key (a rotation withdrawn by a fork, then another) is kept as alternate evidence; two installations
|
|
265
|
+
that share an origin key stay two devices.
|
|
266
|
+
- **Stored proof.** `DeviceSigningKey` carries an optional 64-byte `proof` (strict decode; additive). A key that carries it
|
|
267
|
+
mints KeyPackages, enrolment KeyPackages and the creator leaf of `groups.create()` with no kind-450 signer call.
|
|
268
|
+
|
|
269
|
+
**Residuals.** A device restored past the retained rewind window loses the successions it never saw and shows a rotated
|
|
270
|
+
sibling as a new, unlabelled device until it observes another succession or a label is applied again; a peer on a build
|
|
271
|
+
without lineage support does the same. The retired private key remains inside retained rewind-window snapshots, in a group
|
|
272
|
+
not yet re-keyed and in superseded KeyPackage private material until its grace expiry. The account-signed proof of a retired
|
|
273
|
+
key is never revoked. Rotation ends the old key's signing identity; it is not protection against theft of a full device store.
|
|
274
|
+
- **Late Welcome on a retired own key is already-member.** The joiner's `same-lineage` check of a competing Welcome (`inboxDisposition` `already-member`) now also matches a retired key of the SAME device: the held branch view carries an optional `ownLeafChain` (the device's directed ancestry through the recorded rotation links, filled from the account store when the Welcome is judged), so a Welcome built on a KeyPackage minted before a rotation is kept out without a branch switch. A live sibling installation sharing an origin key is not the same device and is still judged normally; an unreadable lineage degrades to the held key alone and never blocks the Welcome path.
|
|
275
|
+
- **Re-enrolled device rotates again.** `enrolmentManifests` records written by `requestEnrolment` carry an optional `recordedAt` (ms), removed from every waiting manifest when an own forget starts; the Welcome service's new optional dep `onManifestFulfilled(tx, manifest)` runs in the account transaction that marks a manifest fulfilled (join or confirmed switch) and the client wires it to `supersedeOwnForget`, which ends the device's own settled forget record and tombstone when it is admitted again, so `rotateKey()` and the resume sweep work after a forget plus re-enrolment. `devices.requestEnrolment()` rejects `invalid-options` (`device-forgetting`) while an own forget is open.
|
|
276
|
+
- 6e8c963: A peer's disband that the convergence settlement selected is now persisted and
|
|
277
|
+
surfaced instead of living only in the engine's memory. The group store gets a
|
|
278
|
+
durable `marmot.disband` marker, `MarmotGroup.disbanded` (new `GroupDisbanded`
|
|
279
|
+
type: `{ actor, epoch, nodeTag, commitDigest, at }`) names the selected
|
|
280
|
+
disband, and a new `group-disbanded` notification
|
|
281
|
+
(`GroupDisbandedNotification`) is dispatched once. From then on, also after a
|
|
282
|
+
reload, the group no longer syncs, `ingest` rejects every event (reason
|
|
283
|
+
`group-disbanded`), and `send`, the other own-intent operations and `synced()`
|
|
284
|
+
reject `not-a-member` with `details.reason: 'disbanded'`. Previously a reload
|
|
285
|
+
rebuilt the group from its pre-disband state and treated it as live.
|
|
286
|
+
- 4f0f9d9: New `ClientOptions.maxGiftWrapBytes` (default 65 536): the relay event-size budget of the gift wrap an own
|
|
287
|
+
enrolment request is sent in. `devices.requestEnrolment` now also refuses, before anything is minted, stored or
|
|
288
|
+
published, a request whose wrap's event JSON could exceed it — `invalid-options`, `details.reason:
|
|
289
|
+
'request-too-large'`, with `wrapBytes` and `maxGiftWrapBytes`. Before, a request within NIP-44's bounds (up to
|
|
290
|
+
~25 groups) could produce a ~74 KB wrap that 64 KiB relay caps refuse; it was persisted and re-published until it
|
|
291
|
+
expired, never delivered.
|
|
292
|
+
- 73baee0: Close the rewind takeover via a stale leaf snapshot: other-leaf credited depth at equivocation nodes.
|
|
293
|
+
|
|
294
|
+
`@941design/marmot` opts in: a holder of a leaf snapshot within `maxRewindCommits` who hides the post-snapshot
|
|
295
|
+
history and outgrows canonical no longer pulls honest members off the real device's branch once another member has
|
|
296
|
+
committed on canonical after the real device's first commit past the snapshot, however the holder frames its commits
|
|
297
|
+
on the wire. Other members' commits before that one do not suffice: the holder can advance its snapshot through them
|
|
298
|
+
and fork just below the real device's commit, where it still wins with a deeper branch (the engine reports that
|
|
299
|
+
equivocation). The persisted rewind window stores each node's commit
|
|
300
|
+
sender (optional; a window written before it restores the framing's). `groups.restore` does not trust the sender a
|
|
301
|
+
snapshot's window stores: it re-derives each link's sender from the commit at its parent, refuses a snapshot whose
|
|
302
|
+
stored sender disagrees (`envelope-mismatch`, `details.reason: 'malformed'`) and adopts only derived senders, so a
|
|
303
|
+
backup written by another holder of the sync key cannot move equivocation credit. Residuals (pure single-leaf equivocation, a snapshot of a leaf with no post-snapshot commit, the
|
|
304
|
+
real device fencing on its cloned leaf's commits, private-framed edges persisted before senders were, a takeover
|
|
305
|
+
defeated through cross-subtree evidence being corrected without being reported, an equal-depth honest race whose
|
|
306
|
+
loser re-drove onto the winner while others built on the abandoned commit selecting differently from MDK) remain known limitations.
|
|
307
|
+
|
|
308
|
+
`@941design/marmot` surfaces the engine's report as a new `GroupNotification` variant, `leaf-equivocation`
|
|
309
|
+
(`LeafEquivocationNotification`: `leafIndex`, `account`, `leafKey`, `epoch` as a `bigint`, `nodeTag`,
|
|
310
|
+
`commitDigests`), delivered through `onNotification` at most once per group and `(nodeTag, leafIndex)`: the evidence is
|
|
311
|
+
recorded in the group store (extension `marmot.equivocation`) in the ingest batch's transaction (or, when found outside a batch, in a transaction of its own)
|
|
312
|
+
and announced only after that commit, never again for the same evidence — including after a reload. The stored
|
|
313
|
+
record is the source of truth — the notification is a live hint, lost if no listener is attached or the process ends
|
|
314
|
+
before dispatch — and the new `MarmotGroup.equivocations()` returns every recorded equivocation (ordered by `(epoch,
|
|
315
|
+
nodeTag, leafIndex)`, `[]` when none), also after a reload. Informational
|
|
316
|
+
only: nothing is removed automatically. An exhaustive `switch` over `GroupNotification['type']` needs a case for it.
|
|
317
|
+
- 3e09d54: `MarmotGroup.removeMember(account)`.
|
|
318
|
+
|
|
319
|
+
- **One commit, account-scoped.** ONE durable admin commit removes every leaf the account holds when the commit is
|
|
320
|
+
built. The stored commit intent has a new `removeAccounts` field (the account, never leaf indexes). An admin may remove
|
|
321
|
+
another admin in the same commit, with no demotion first: the engine's coupling splice drops the removed admin's entry
|
|
322
|
+
(needs this release's receive-side fix, so the removed admin's devices accept their own removal and end as tombstones).
|
|
323
|
+
`onConfirm` hooks see `kind: 'commit'`.
|
|
324
|
+
- **Bounded re-parenting.** The record also snapshots the signature keys of the account's leaves at call time in
|
|
325
|
+
`removeAccountLeafKeys`, a new strictly decoded intent field. A record whose parent epoch moved is re-parented onto the
|
|
326
|
+
current tree only if one of those leaves is still in the tree (then ALL the account's current leaves are removed, also
|
|
327
|
+
one added meanwhile); a caller demoted meanwhile is refused `send-rejected` by the engine. A member who was removed and
|
|
328
|
+
re-added meanwhile no longer matches, so the record drops as `absent` (a waiting caller resolves; an unattended record
|
|
329
|
+
reports `intentFailed`, `details.reason: 'absent'`). Residual: the snapshot identifies a device key, not a membership
|
|
330
|
+
incarnation, so another admin's remove-and-re-add of the same device makes a resumed record remove the account again.
|
|
331
|
+
- **Refusals** (nothing recorded, epoch unchanged): `invalid-options` with `details.reason` `'malformed-account'`,
|
|
332
|
+
`'self'` (use `departAsAdmin()` / `leave()`) or `'not-admin'`; `commit-pending` while an own commit is pending. An
|
|
333
|
+
account holding no leaf resolves as a no-op.
|
|
334
|
+
- **Staged proposals.** Leaves a staged Remove or SelfRemove already targets are skipped (carried by reference).
|
|
335
|
+
`send-rejected`, nothing recorded, when a staged Add admits a leaf of the account (`details.reason:
|
|
336
|
+
'staged-add-of-removed-account'`), when a staged Update names the account's leaf, or when a staged admin-list change
|
|
337
|
+
still names a removed admin (`'staged-admin-policy-update'`): commit the staged proposal first
|
|
338
|
+
(`send({ type: 'commit' })`) and retry. A staged admin-list change is committed together with the removal.
|
|
339
|
+
- devices.forget: refused send-rejected (details.reason staged-add-of-removed-leaf) while a staged Add re-admits the
|
|
340
|
+
forgotten leaf key; commit it first.
|
|
341
|
+
- **Removed side.** Unchanged (Q1 option a): a tombstoned group; that device's own group emits no `leaf-removed`
|
|
342
|
+
notification (the remaining members' groups do).
|
|
343
|
+
- **Stores.** The new intent fields are additive; a stored commit record without them decodes as before. A record with
|
|
344
|
+
`removeAccounts` but no `removeAccountLeafKeys` (or the reverse), or either not a non-empty array of 64-lowercase-hex
|
|
345
|
+
strings, is refused as a malformed intent. No engine change.
|
|
346
|
+
- 57ff027: New client event `groupRemoved` `{ groupId, actor? }`: a peer removed this device from the group and the removal settled
|
|
347
|
+
(no longer revisable, after `removalSettleMs`); `actor` is the hex account identity of the admin whose removing commit
|
|
348
|
+
was selected, absent when the committer cannot be resolved. The group and its history stay held, read-only; the application decides
|
|
349
|
+
whether to `abandon()` it. Not fired for a removal this device asked for (`leave()`, an own-leaf `devices.forget`, or an
|
|
350
|
+
`abandon()`/`destroy()` in progress). At most once: a crash between the settle and the emit loses it.
|
|
351
|
+
`MarmotClientEvents` and `MarmotClientEventName` gain the member, so an exhaustive `switch` over event names needs the
|
|
352
|
+
new case.
|
|
353
|
+
- cf99252: `MarmotGroup.rename(name, { description? })`, the read-only `MarmotGroup.description` and the exported
|
|
354
|
+
`groupProfileProposal({ name, description })` builder.
|
|
355
|
+
|
|
356
|
+
- **`rename`.** ONE durable admin commit that replaces the group profile (`marmot.group.profile.v1`: name and
|
|
357
|
+
description). It is a stored commit intent with a new `profile: { name, description }` field, so a record resumed
|
|
358
|
+
after a reload drives to the same committed profile, and the `onConfirm` hooks see `kind: 'commit'`. An omitted
|
|
359
|
+
`description` keeps the current one, resolved when the call is made and stored by value; `description: ''` clears
|
|
360
|
+
it. A non-admin caller is refused `invalid-options` with `details.reason: 'not-admin'` before anything is recorded.
|
|
361
|
+
Gate order: not a member, send gate closed, malformed argument, not-admin, `commit-pending`, proposal policy. While
|
|
362
|
+
a `0x8001` proposal is staged on the group, `rename` rejects `send-rejected`
|
|
363
|
+
(`details.reason: 'staged-profile-update'`) with nothing recorded: a commit that carried both would hold two
|
|
364
|
+
profile updates.
|
|
365
|
+
- **Two updates of one component.** A commit carries staged proposals by reference first and the committer's own
|
|
366
|
+
update by value after them, and receivers resolve a component to its last update, the committer's own. `setAdmins`
|
|
367
|
+
and the demotion of `departAsAdmin` therefore stay allowed while a foreign admin-policy proposal is staged (a
|
|
368
|
+
refusal would block teardown for good, since teardown never commits it); only `rename` refuses. A record that goes
|
|
369
|
+
terminal at build time keeps the cause's `details.reason` on its `send-rejected`.
|
|
370
|
+
- **Limits.** `name` is a non-empty string of at most 256 UTF-8 bytes and `description` a string of at most 4096
|
|
371
|
+
UTF-8 bytes (byte limits, not character counts, the component's own); a violation is `invalid-options` before
|
|
372
|
+
anything is recorded.
|
|
373
|
+
- **`groupProfileProposal`.** Returns the ts-mls `Proposal` (`appDataUpdate`, component `0x8001`) for the remaining
|
|
374
|
+
route, where a non-admin sends `{ type: 'proposal', proposal }` and an admin sends `{ type: 'commit' }`, with no
|
|
375
|
+
hand-encoded bytes; it wraps the engine's one encoder and `rename` builds from the same function. Exported from the
|
|
376
|
+
package root (with the `GroupProfile` type), not from `@941design/marmot/mls`.
|
|
377
|
+
- **Stores.** The new intent field is additive: a stored commit record without `profile` decodes as before, and a
|
|
378
|
+
record whose `profile` is not a pair of strings within the component's limits is refused as a malformed intent.
|
|
379
|
+
No engine change, so `PATCHSET_DIGEST` does not move.
|
|
380
|
+
- 3182df9: New `ClientOptions.inboxHandlerBudgetMs` (default 30 000 client-clock ms,
|
|
381
|
+
`0` never reports) and `handlerSlow` client event: an inbox consumer callback
|
|
382
|
+
(an `extensions.registerInboxHandler` handler or `onApplicationRumor`) still
|
|
383
|
+
running after the budget is reported once with `{ surface, rumorKind, wrapId,
|
|
384
|
+
budgetMs }`. It is a diagnostic only. The handler is not detached or
|
|
385
|
+
redelivered, and the inbox queue still waits for it, so the "handlers must
|
|
386
|
+
not await long work" contract is unchanged.
|
|
387
|
+
- dead108: A joined group's first sync fetches from its join floor — the Welcome's `created_at` (clamped to [arrival − grace
|
|
388
|
+
window, arrival]) minus the 300 s clock-skew allowance — instead of the group's whole history, so pre-join history is no
|
|
389
|
+
longer downloaded and no longer saturates the branch-aware fence's undecryptable set. Events below
|
|
390
|
+
the floor that a relay delivers anyway are still processed; restores and created groups are unchanged.
|
|
391
|
+
- 897a824: New root export `keyPackageRefOf(event)`: the hex KeyPackageRef of a kind-30443 KeyPackage event — what
|
|
392
|
+
`invitations.expectWelcome()` takes as `keyPackageRef` (and `group.invite()` reports as `inviteeRef`) — for the
|
|
393
|
+
event `keyPackages.create()` / `.offer()` returned or one fetched from a relay. Rejects `invalid-options` for an
|
|
394
|
+
event that is not a KeyPackage. Replaces the `@941design/marmot/mls` derivation recipe docs/migration.md gave.
|
|
395
|
+
- 3182df9: New `GroupNotification` variants `leaf-removed` and `leaf-removal-withdrawn`
|
|
396
|
+
(types `LeafRemovedNotification`, `LeafRemovalWithdrawnNotification`):
|
|
397
|
+
a commit on the canonical path that removes leaves is announced once per removed
|
|
398
|
+
leaf as `{ type: 'leaf-removed', commitDigest, account, leafIndex, leafKey }`
|
|
399
|
+
(account and index as of the commit's parent state), dispatched with that
|
|
400
|
+
commit's `applied` notifications — also when the account keeps other leaves,
|
|
401
|
+
where the engine's `memberRemoved` does not fire, so a same-account device
|
|
402
|
+
removal is visible as such. A rewind that supersedes the commit emits
|
|
403
|
+
`leaf-removal-withdrawn` with the same fields. A leaf that replaced its own key
|
|
404
|
+
at the same index is not a removal.
|
|
405
|
+
- 3751eec: Export the types that already appear in public signatures, so consumers can name them (type-only exports):
|
|
406
|
+
`RumorDisposition` (what `InboxDisposition` extends), `InboxRumorHandler` (the type `InboxHandler` aliases),
|
|
407
|
+
`MaintenanceKind` and `DeviceMaintenanceKind` (the `maintenanceFailed` event's `kind`) from the package root, and
|
|
408
|
+
the structural IndexedDB types `IDBFactoryLike.open` reaches — `IDBOpenDBRequestLike`, `IDBRequestLike`,
|
|
409
|
+
`IDBDatabaseLike`, `IDBTransactionLike`, `IDBObjectStoreLike`, `IDBValidKeyLike` — from
|
|
410
|
+
`@941design/marmot/storage/indexeddb`. No runtime change.
|
|
411
|
+
- f2b9617: A device that joined a group on one branch of a same-epoch race is moved onto the branch of a competing Welcome the
|
|
412
|
+
members' rule ranks higher. The group runtime implements the ports the Welcome
|
|
413
|
+
service decides through, and `WelcomeServiceDeps.competing` is now required.
|
|
414
|
+
|
|
415
|
+
- New client event `groupBranchSwitched` (`invitationId`, `groupId`, `from`, `to`: the confirmation tags of the
|
|
416
|
+
abandoned tip and of the Welcome's state). It fires once per switch, also when the switch was decided in an inbox
|
|
417
|
+
pass with no wrap in hand; `groupJoined` does not fire again and the abandoned Welcome's invitation stays `joined`.
|
|
418
|
+
The inbox disposition `branch-switched` is reported when the switch ran inside the Welcome's dispatch. A crash between
|
|
419
|
+
the report and the invitation's confirmation reports the switch once more on the next pass: deduplicate by
|
|
420
|
+
`invitationId`.
|
|
421
|
+
- The switch is one group transaction: the Welcome's state, a tip-only window carrying the join evidence, the per-state
|
|
422
|
+
group extensions (`marmot.opaque`, `marmot.removal`, `marmot.pendingLeaf`, the restore marker) cleared, everything the
|
|
423
|
+
abandoned branch applied that its retained window holds withdrawn (`withdrawn`, `message-withdrawn`; messages the
|
|
424
|
+
application sent on it are not re-sent), a settlement-recheck marker (`DeviceGroupPort.onRewind` fires), the
|
|
425
|
+
`onConfirm` hooks with `kind: 'join'` (an account's leaf backup follows the new branch; a throwing hook rolls the whole
|
|
426
|
+
switch back), and the group's pre-join ingest floor and cursor lowered to the Welcome so what was sent on the new
|
|
427
|
+
branch before the switch is fetched again. A crash at any step is completed by the next inbox pass.
|
|
428
|
+
- The decision waits (durably, as a `competing` invitation) while the group is not loaded, fenced, restoring, purging,
|
|
429
|
+
abandoned, syncing (its first sync since the load, or the engine's quiescence window) or has an own commit,
|
|
430
|
+
self-update or proposal pending; the end of each of those asks for an inbox pass.
|
|
431
|
+
- `adoptJoinedGroup` persists the join evidence of a tagged Welcome on the window root; an imported snapshot never
|
|
432
|
+
supplies it.
|
|
433
|
+
- `CompetingWelcomePorts.competingGate` may answer asynchronously; `HeldBranch` gains `joinedAtMs`, which lets an
|
|
434
|
+
interrupted join of the very Welcome be recognised after the join root left the retained window.
|
|
435
|
+
- A switch also withdraws own application messages minted on the abandoned branch that were not yet confirmed
|
|
436
|
+
(`message-withdrawn`; they never read as sent on the new branch), and re-enqueues withdrawn own self-updates. An
|
|
437
|
+
`onConfirm` hook that refuses a switch is retried every inbox pass without counting toward the give-up. The
|
|
438
|
+
Welcome's `created_at` lowers the pre-join floor only within the grace window.
|
|
439
|
+
- `CompetingWelcomePorts.switchState` and `WelcomeServiceDeps.passNow` are new ports; a switch leaves a durable proof row
|
|
440
|
+
in the group extension `marmot.branchSwitch`, so a recovery after the group moved on (or the join root left the
|
|
441
|
+
window) still finds the switch written, and a group that merely carries the Welcome's branch keeps it out as its own
|
|
442
|
+
lineage.
|
|
443
|
+
- 2c11e4b: Removal finality: `@941design/marmot` opts in to the engine's
|
|
444
|
+
`removalFinality` (a single literal beside `equivocationCredit` and `branchAwareFence` in `group-runtime.ts`).
|
|
445
|
+
|
|
446
|
+
- **A removed member cannot rewind back in.** A member removed at epoch E that, not having seen the removal, keeps
|
|
447
|
+
committing from E no longer wins its leaf back by depth: its own commits past the removal earn nothing, and the
|
|
448
|
+
removal is preferred on an equal-finality race. This holds for dead chains up to `maxRewindCommits - 1` commits past
|
|
449
|
+
the removal's parent (4 with the shipped horizon of 5) (counting the removed leaf's self-updates after its first commit off `P`; the guard is `tipEpoch − epoch(P) ≤ maxRewindCommits`, so a chain of exactly `maxRewindCommits` commits past `P` is still decided); a longer chain is followed by today's ordering and the
|
|
450
|
+
remover's withdrawn `removeMember` is re-driven on top of it, within the shared re-drive budget (`maxPublishAttempts`).
|
|
451
|
+
- **Behaviour changes visible to applications.** An equal-depth race between a removal and a commit of another member
|
|
452
|
+
now goes to the removal; a removal is withdrawn (`leaf-removal-withdrawn`, then re-driven) only when members other
|
|
453
|
+
than the remover and the removed leaf out-commit it. A forget's or `removeMember`'s race with the target device's own
|
|
454
|
+
rotation is won by the removal unless another member backs the rotation. A settled device forget is reopened by a
|
|
455
|
+
fork rewind only under the same condition.
|
|
456
|
+
- **The removed device decides `removed` by itself** in the same interleavings as the members, and settles through
|
|
457
|
+
the existing `removalSettleMs` path, except when the removal is extended by work it cannot read while its own branch
|
|
458
|
+
carries two commits by other members, or past the rule's guard.
|
|
459
|
+
- **Joiners.** A joiner's competing-Welcome ranking ignores removal finality; a joiner stranded on a
|
|
460
|
+
demoted branch is healed by the re-driven invite.
|
|
461
|
+
|
|
462
|
+
The engine patch set changes `ENGINE_VERSION`: every store written by an earlier build is refused with
|
|
463
|
+
`storeIncompatible` (`envelope-mismatch`) and can be recovered by a wipe. See the `@941design/marmot-engine` changeset
|
|
464
|
+
for the engine side.
|
|
465
|
+
- a4dcb1f: `groups.restore` resolves a pending-tagged `GroupSnapshot`:
|
|
466
|
+
|
|
467
|
+
- The snapshot is adopted at its tip S_C (the state of an own commit C that no relay was known to hold when the
|
|
468
|
+
snapshot was taken). Once the restore's first sync is over, a resolution step runs once, on the persisted tip:
|
|
469
|
+
if the sync delivered C (matched by commit digest only) or moved the group off S_C in any way, the adopted tip
|
|
470
|
+
stands and a competing branch is followed by the ordinary fork rules; if no relay delivered C (a silent or
|
|
471
|
+
truncated relay counts as not having it) the group is rewound to C's parent P in ONE transaction — state, rewind
|
|
472
|
+
window, the parked node and the marker's clearing — and the restore's self-update is made on P. A backup of a
|
|
473
|
+
commit that never reached a relay therefore no longer puts the device on a branch no member holds, and a backup
|
|
474
|
+
of a published commit no longer fences the device.
|
|
475
|
+
- The rewound-away S_C is parked in a side record (group extension `marmot.pendingLeaf`), outside the rewind
|
|
476
|
+
window and the engine's history tree, so it competes in no selection and feeds no equivocation report. If C
|
|
477
|
+
is delivered later (any ingest path), ingest checks its digest before the engine sees it, reinstates the node
|
|
478
|
+
as an ordinary own-leaf fork node, rebuilds the engine and re-offers what the lost pool held. The record is
|
|
479
|
+
dropped when its parent leaves the rewind window, and cleared by any restore or Welcome adoption of the group.
|
|
480
|
+
- Any envelope that opens under S_C's own epoch key (a peer's message, proposal or commit built on it) counts as C
|
|
481
|
+
seen. The rewind runs as an ordinary transition (what was delivered under S_C is withdrawn, the rewind is announced)
|
|
482
|
+
and fails closed under an own operation recorded on the adopted tip; a fork leaf S_C that no peer holds is parked
|
|
483
|
+
too. The consumer `verifier` decides before any of this, and a re-encrypted copy of a reinstated C is ledgered.
|
|
484
|
+
- Recognising C is durable (the ingest transaction that sees it clears the restore's marker beside its cursor and
|
|
485
|
+
ledger write) and the resolution is idempotent, so a client disposed or crashed anywhere between the adoption and
|
|
486
|
+
the self-update's confirmation resolves it identically on the next client over the same stores.
|
|
487
|
+
- Restoring a confirmed (unmarked) snapshot is unchanged. No vendored `marmot-engine` change.
|
|
488
|
+
- 0a5de38: A successful `groups.restore` now starts a device-key rotation: a lost or stolen device still holding
|
|
489
|
+
the backed-up key no longer keeps reading the restored groups. Restoring a batch of groups costs one rotation (one
|
|
490
|
+
`deviceKeyRotated`); it is best-effort, survives a restart (durable marker), and never fails the restore. Signer cost:
|
|
491
|
+
the rotation's prepare signature and its KeyPackage republishes.
|
|
492
|
+
- 3182df9: marmot now has a transport (re)connect signal. Wire the transport adapter's
|
|
493
|
+
(re)connect callback into the new `client.transportEvents.connected(relayUrl)`
|
|
494
|
+
sink, beside `authFailed`. It is re-emitted as the `transportConnected`
|
|
495
|
+
client event `{ relayUrl }`, with the relay string exactly as reported. It
|
|
496
|
+
ignores a non-string relay and is a no-op after `dispose()`.
|
|
497
|
+
|
|
498
|
+
`attachAccountSync` listens for `transportConnected`. Each event marks the
|
|
499
|
+
sync-key ring stale and runs the retry round (ring sync, refresh pass,
|
|
500
|
+
carrier pull + flush), so an application wired to marmot no longer has to
|
|
501
|
+
call `handle.transportEvents.connected()` as well. That sink still works for
|
|
502
|
+
adapters wired to the handle directly. The listener is registered and
|
|
503
|
+
removed with the attachment's other registrations.
|
|
504
|
+
- b27f674: Welcome rumors carry the digest of the commit they belong to. Every Welcome
|
|
505
|
+
rumor an invite commit stages now has a `['commit', <64 lowercase hex>]` tag after the `relays` (and `e`) tags: the
|
|
506
|
+
`commitDigest` (SHA-256) of the encoded MLS message the commit is published and confirmed with, so a joiner holding
|
|
507
|
+
two Welcomes for one group can later rank the two branches by (epoch, committer account, digest) the way the members
|
|
508
|
+
do. The rumor id is recomputed over the tagged draft; `e`, `relays` and the MLS Welcome content are unchanged, so the
|
|
509
|
+
engine's `getWelcome` and every Marmot reader that validates only those tags keeps decoding it.
|
|
510
|
+
|
|
511
|
+
- Welcomes staged before this release stay untagged: `decodeStoredWelcomes` reads them unchanged and `retryWelcome`
|
|
512
|
+
re-wraps a stored rumor byte for byte (tagged or not, same rumor id).
|
|
513
|
+
- Internal API of the `invitations` module: `buildWelcomeRumors` takes the encoded commit bytes (`commit`, required);
|
|
514
|
+
new `welcomeCommitTagOf(rumor)` reads the tag totally (`undefined` for no tag, a repeated tag, or a value that is not
|
|
515
|
+
64 lowercase hex; it never throws) and `WELCOME_COMMIT_TAG` names it.
|
|
516
|
+
- Interop residual: other Marmot implementations must tolerate the extra tag (MIP-02 forbids only `encoding`); the
|
|
517
|
+
client does not yet act on it.
|
|
518
|
+
- 0aec8e1: The retained rewind window can carry join evidence. A window root gains an
|
|
519
|
+
optional `joinEvidence { digest, committer }` (hex): the commit digest from the Welcome's `commit` tag and the account
|
|
520
|
+
of the member that signed the Welcome's GroupInfo, recorded when a device joined. Nothing writes it yet; the joined
|
|
521
|
+
node's own record of its commit is what a later competing Welcome is ranked against.
|
|
522
|
+
|
|
523
|
+
- `tipOnlyWindow(state, evidence?)` puts it on the root (evidence that is not two 64-lowercase-hex strings throws); it survives `writeWindow`/`readWindow` (stored as `j`
|
|
524
|
+
`{ d, c }`; a window written before this release reads without it, and a malformed value is dropped, never
|
|
525
|
+
guessed), `extendWindow` for any number of own commits while the join node is inside `REWIND_HORIZON`, `bounded`
|
|
526
|
+
(`withForkNode`, `rewoundToParent`), `windowFor` and `sameNode`, and leaves the window only with its node.
|
|
527
|
+
- `captureWindow(tree, tip, horizon, prior)` takes the window it replaces as a REQUIRED fourth argument (`undefined` for a deliberate fresh capture, so omitting it is a compile error) and carries
|
|
528
|
+
the evidence of `prior` over by node tag (the engine's tree knows nothing of a join). The client's three
|
|
529
|
+
`captureWindow` sites (ingest) pass the window they replace, and the own-commit path (`windowAfterOwnCommit`) builds
|
|
530
|
+
its base with `windowFor`, so evidence survives ingest batches, own commits and reloads.
|
|
531
|
+
- New `heldBranchScore(window, tip)` returns `{ complete: true, score }` or `{ complete: false, missing }`: the held
|
|
532
|
+
side of `compareBranchScores` (depth = tip epoch for both depths, no witnesses, the tip's own link digest and its
|
|
533
|
+
committer from `tipCommitterOf`, else the join evidence). A digest or committer the window cannot supply gives the
|
|
534
|
+
second form, which carries no score, so an incomplete score cannot be compared.
|
|
535
|
+
- An imported snapshot never supplies evidence: its window rows are read field by field, so a claim in the payload is
|
|
536
|
+
not read.
|
|
537
|
+
|
|
538
|
+
### Patch Changes
|
|
539
|
+
|
|
540
|
+
- 1b6789d: First npm pre-release (alpha) of all four packages.
|
|
541
|
+
- 0f720da: Group history paging keeps, for an event id delivered by several relays, the first copy whose signature verifies (the
|
|
542
|
+
first delivered when none does), as `requestWithDeadline` does: a faster relay returning a tampered body under an honest
|
|
543
|
+
id no longer hides the valid copy.
|
|
544
|
+
- 4f0f9d9: Enrolment approvals: the retry of a group whose earlier Add may have landed (its commit was still in the pipeline
|
|
545
|
+
when the pass that issued it ended) is now checked like a reopened re-drive: it carries
|
|
546
|
+
the device's leaf key and the recorded approval epoch, so an Add that landed and was removed by a sibling before
|
|
547
|
+
any pass observed it is never re-added — the group concludes `failed`. Such a retry never advances the approval's
|
|
548
|
+
epoch bound, and the marking (`retried` on the approval group record) survives a crash between counting the
|
|
549
|
+
earlier attempt and the retry.
|
|
550
|
+
- 85dfd19: A leaf equivocation that only the engine's scheduled disband settlement detects is now recorded and announced once,
|
|
551
|
+
as a `leaf-equivocation` notification. `equivocations()` returns it too. The convergence continuation records a
|
|
552
|
+
drive that returns only that report, then stops without rolling the engine back, as it does for a drive that
|
|
553
|
+
returns nothing. A peer's disband of a multi-admin group is no longer rejected as `admin-leaf-coupling` either.
|
|
554
|
+
|
|
555
|
+
The bundled `@941design/marmot-engine` moves `ENGINE_VERSION`, so stores written by earlier builds are refused
|
|
556
|
+
(`storeIncompatible`); wipe the store by marker to recover.
|
|
557
|
+
- 2829d73: `MarmotClient.dispose()` now finishes every service's teardown when a
|
|
558
|
+
consumer-supplied `options.timers.clear` throws. Before this fix, a throwing
|
|
559
|
+
clear stopped that service's dispose at the first timer. The inbox's and the
|
|
560
|
+
groups' live subscriptions stayed open, and a sleeping `leave()` was never
|
|
561
|
+
rejected. The client now wraps the consumer's timers once. A `clear` that
|
|
562
|
+
throws is recorded and returns, and `dispose()` lists the recorded errors in
|
|
563
|
+
its `AggregateError`. A clear that throws during normal operation (for example
|
|
564
|
+
in `inbox.stop()`) no longer escapes into that operation. It is reported at
|
|
565
|
+
`dispose()` instead.
|
|
566
|
+
- cf2115a: Application messages are decoded as strictly as MDK decodes them: a message whose bytes start with U+FEFF, that
|
|
567
|
+
holds malformed UTF-8, or whose strings hold an unpaired surrogate escape, is refused (before, it was accepted here while MDK peers refused it, so members on different
|
|
568
|
+
implementations saw different histories). Avatar `dim`/`thumbhash` hints keep a leading U+FEFF. New conformance
|
|
569
|
+
patches move the engine stamp, so stores written by the previous build are refused with `storeIncompatible`.
|
|
570
|
+
- 2ab78c6: Marmot text fields keep a leading U+FEFF: `decodeUtf8` no longer strips it as a byte-order mark, so a group name or
|
|
571
|
+
description starting with it reads back exactly (a name of just U+FEFF no longer decodes as empty), as other
|
|
572
|
+
implementations read it. A new local patch moves the engine stamp, so
|
|
573
|
+
stores written by the previous build are refused with `storeIncompatible`.
|
|
574
|
+
- c538b1a: `groups.restore` is now fenced (`fenced`) when the snapshot predates an own commit that won a same-epoch race but
|
|
575
|
+
reached the first sync after the competing commit — previously the restore resolved on a forked branch. The client's
|
|
576
|
+
fencing predicate (`isFencingError`) now delegates to the engine's `isNoOverlapError`, so it fences on exactly what
|
|
577
|
+
every engine replay path surfaces.
|
|
578
|
+
- 3182df9: A throwing inbox handler no longer costs a signer unwrap on every retry. The
|
|
579
|
+
counted `handler-failed` deferral now stores the unwrapped rumor with the
|
|
580
|
+
wrap (the same at-rest posture as a pending invitation's Welcome), and later
|
|
581
|
+
passes redispatch it without asking the account signer to decrypt again, so
|
|
582
|
+
a remote signer that prompts per decrypt is asked once per wrap. The stored
|
|
583
|
+
rumor is bounded by the processing-failure cap and cleared when the wrap is
|
|
584
|
+
delivered or dropped; a stored rumor that does not decode is ignored and the
|
|
585
|
+
wrap is unwrapped as before.
|
|
586
|
+
- abbee6d: A group's history sync no longer walks its backlog twice when the live
|
|
587
|
+
subscription opens while a deep backlog walk is still running. The history
|
|
588
|
+
pass is now single-flight per group. A resync requested while a pass runs (the
|
|
589
|
+
catch-up after the subscribe, a retry firing, a failed live event) is folded
|
|
590
|
+
into one follow-up pass that starts from the lowered catch-up floor once the
|
|
591
|
+
walk ends. On a relay serving one event per request, a 218-event backlog
|
|
592
|
+
needed about twice the requests after the subscribe. A routing change still
|
|
593
|
+
restarts the sync at once on the new relays.
|
|
594
|
+
- 4f0f9d9: Inbox: the "live covers it" shortcut — a continued backfill walk resumed inside the live session that saved it
|
|
595
|
+
skips re-walking the newer window — is now trusted for at most 10 minutes since
|
|
596
|
+
a pass last walked that window. A transport that silently re-establishes a dropped socket (an `autoReconnect`
|
|
597
|
+
adapter re-issuing the `limit: 0` filter without telling the observer) left wraps published during the outage
|
|
598
|
+
undelivered until the next restart; they now arrive with the next pass past the cap.
|
|
599
|
+
- 6e8c963: `EnrolmentPrompt.relays` (and the `enrolmentRequested` prompt) now names the
|
|
600
|
+
inbox relay(s) the request's wrap actually arrived from, using the transport's
|
|
601
|
+
relay provenance: every inbox relay whose history walk returned the wrap, or
|
|
602
|
+
the relay a live subscription delivered it on (`DeliveryMeta`). Previously it
|
|
603
|
+
was the whole inbox relay set the request was read over. That set is still
|
|
604
|
+
reported for a delivery that carries no provenance (a transport that passes no
|
|
605
|
+
`DeliveryMeta`, or a deferred wrap retried from the store).
|
|
606
|
+
- 55fee37: A device that joined a group by Welcome now applies the members' own rewind bound when it decides a competing Welcome: it switches only while `tipEpoch - (joinEpoch - 1) <= REWIND_HORIZON`, measured
|
|
607
|
+
from the fork's parent as `isBranchEligible` does, instead of from its join root. Before, at exactly `REWIND_HORIZON`
|
|
608
|
+
followed commits the joiner switched to a branch the members could no longer converge on.
|
|
609
|
+
|
|
610
|
+
The joiner only has an upper bound on the fork epoch (it holds nothing below its join root): parity at the horizon holds
|
|
611
|
+
when the sponsor of its Welcome had no commits the joiner did not see, otherwise the joiner may switch up to that many
|
|
612
|
+
epochs past the members' bound.
|
|
613
|
+
- 3182df9: A late fork flip in a quiet group no longer skips withdrawal detection. The
|
|
614
|
+
terminal ledger's age-based retention (seven days below the ingest cursor)
|
|
615
|
+
now keeps every entry whose delivery state is still a node of the stored
|
|
616
|
+
rewind window, so a group with few commits over more than a week of traffic
|
|
617
|
+
still reports `message-withdrawn` and still re-enqueues (or cancels the
|
|
618
|
+
re-enqueue of) an own self-update when a sibling commit flips the branch.
|
|
619
|
+
- d8f82b1: A lost store lease is now remembered by the group runtime (`leaseLost`), not only signalled. Before, a lease lost while
|
|
620
|
+
an `onBeforePublish` barrier ran stopped that pass, but the envelope stayed marked as handled, so a later resume pass in
|
|
621
|
+
the same runtime published it without its hooks. Now a pass whose hooks did not complete leaves the envelope unhandled,
|
|
622
|
+
and every later pass sees the ended runtime and publishes nothing; the durable record waits for the next holder of the
|
|
623
|
+
stores.
|
|
624
|
+
- 4f0f9d9: Every record codec's decode/validation failure (`store-failed`) now carries `details.malformed: true` — enrolment
|
|
625
|
+
sessions, the device registry and device signing key, KeyPackage slots, invite and decline records, enrolment
|
|
626
|
+
manifests, and a stored group state naming an unknown ciphersuite or carrying no Marmot group view. The inbox
|
|
627
|
+
classifies such a failure as a non-transient `malformed-record` (a poison wrap is rejected after its counted
|
|
628
|
+
deferrals) by the flag, whatever the message says; before, two of these sites were classified transient because
|
|
629
|
+
their message did not contain the word "malformed".
|
|
630
|
+
- 3182df9: An own commit whose every publish acknowledgement was lost no longer goes
|
|
631
|
+
terminal at `maxPublishAttempts` when a relay stored it. The max-attempts path
|
|
632
|
+
now probes the group's relays for the envelope first: a stored commit is
|
|
633
|
+
confirmed as the group's next epoch (the send settles instead of firing
|
|
634
|
+
`intentFailed` with `send-rejected`), so the device no longer commits a second
|
|
635
|
+
time at the same epoch and its peers no longer flag an honest client with
|
|
636
|
+
`leaf-equivocation`. An absent envelope, or a probe that times out or fails,
|
|
637
|
+
keeps the previous drop.
|
|
638
|
+
- 6e8c963: The post-load ratchet skip now re-arms when the group's first post-load sync
|
|
639
|
+
shows its record is stale. If a load does not skip because the stored skip
|
|
640
|
+
record (`marmot.ratchetSkip`) is undelivered, which happens with a backup taken
|
|
641
|
+
while the first message after a restart was refused everywhere, and that sync
|
|
642
|
+
then reads back an own application message at or after the skipped generation
|
|
643
|
+
on the same epoch state, the record is marked delivered and the first post-gate
|
|
644
|
+
message skips again. That message no longer re-mints the generation of an own
|
|
645
|
+
message held only by a relay the sync excluded as silent. The `ratchetSkipMargin`
|
|
646
|
+
documentation now also states the existing relay-derived floor: own messages
|
|
647
|
+
the first sync reads are ingested, which moves the own sender ratchet past them,
|
|
648
|
+
so a second restore of one snapshot skips past what the first restore sent when
|
|
649
|
+
a relay holds it. The remaining carve-outs are limited to messages held only by
|
|
650
|
+
silence-excluded relays.
|
|
651
|
+
- 59224af: A Welcome-race branch switch now also lowers the in-memory catch-up floor, so a live event processed before the
|
|
652
|
+
resync can no longer drop the lowered fetch start and miss what was sent on the new branch before the switch.
|
|
653
|
+
- 74a8892: A removed admin's client now tombstones the group when another admin removes it, instead of staying active on a rejected
|
|
654
|
+
`admin-leaf-coupling` commit (engine fix in `@941design/marmot-engine`).
|
|
655
|
+
- 3182df9: `groups.restore` now refuses a snapshot whose rewind window carries a state
|
|
656
|
+
with a forged `privatePath`. Every window state must hold the private key of
|
|
657
|
+
its own leaf's encryption key in that state's ratchet tree. A path whose leaf
|
|
658
|
+
index was redirected to another member's leaf, or whose leaf key was
|
|
659
|
+
replaced, is refused `envelope-mismatch` (`reason: 'malformed'`) before
|
|
660
|
+
anything is written, so it can no longer redirect the sender attribution of
|
|
661
|
+
a fenced PrivateMessage commit. Honest snapshots restore as before.
|
|
662
|
+
- 6e8c963: A resumed own intent whose relay probe throws (rather than timing out) no
|
|
663
|
+
longer keeps the group's background resume retrying forever. The throwing
|
|
664
|
+
probe is now handled like a timed-out one: the record goes to its publish
|
|
665
|
+
retry, which spends `maxPublishAttempts` and, once they are exhausted, drops
|
|
666
|
+
the intent as before (`intentFailed` with `send-rejected`, reason
|
|
667
|
+
`max-attempts`), or confirms it when a publish is accepted. Other records of
|
|
668
|
+
the group are no longer held back behind the failing probe.
|
|
669
|
+
- 74a8892: `marmot.opaque` stores and restores the engine's `undecryptableSaturated` flag, so the bounded, fail-closed undecryptable
|
|
670
|
+
set survives a restart. A stored flag that is not exactly `true` is treated as corrupt and fences the group.
|
|
671
|
+
- 8904e31: A Welcome whose invite commit was abandoned by a rewind (it lost a same-epoch race) is no longer published. The delivery of every invitee still `pending` or `retryable` goes `failed` with
|
|
672
|
+
reason `commit-withdrawn` and the `welcomeFailed` event fires, so the application can re-invite (`retryWelcome` still
|
|
673
|
+
re-sends one on request; that, not a re-invite, is the remedy); the invitee no longer consumes and rotates its KeyPackage for a branch the group left. A
|
|
674
|
+
Welcome already being published when the rewind lands is not recalled: if a relay accepts it the delivery reads
|
|
675
|
+
`delivered`, and the invitee decides it like any competing Welcome. Invite records now store the confirmation tag of the
|
|
676
|
+
commit (`commitTag`); a record written before this change is never withdrawn automatically.
|
|
677
|
+
|
|
678
|
+
If the commit returns to the canonical path later (equivocation credit, a longer branch), its failed deliveries go back to
|
|
679
|
+
`pending` and are delivered, announced by the new client event `welcomeRestored` (`groupId`, `inviteeRef`). A load
|
|
680
|
+
reconciles the group's open and withdrawn invite commits against the stored window first, so a withdrawal a crash lost
|
|
681
|
+
is made up; a reconciliation that cannot be written is reported as the new event `welcomeReconcileFailed` (`groupId`,
|
|
682
|
+
`error`) and leaves the deliveries as they were.
|
|
683
|
+
- 996fc10: Export the types that public signatures already referenced, so the API docs build cleanly:
|
|
684
|
+
|
|
685
|
+
- `@941design/nostr-events/signer/nostr-connect`: `NostrConnectTransport` (the `transport` option of
|
|
686
|
+
`createNostrConnectSigner` and `listenForNostrConnect`; a `NostrNetworkInterface` or `TransportContract` satisfies it).
|
|
687
|
+
- `@941design/marmot`: `DeviceKeyRotationGroupOutcome` (`DeviceKeyRotationOutcome.perGroupOutcome`) and `JoinEvidence`
|
|
688
|
+
(`WindowNode.joinEvidence`). `OwnChangeLostReason` is now spelled out as a literal union (same members).
|
|
689
|
+
- Updated dependencies [c425a58]
|
|
690
|
+
- Updated dependencies [36e5299]
|
|
691
|
+
- Updated dependencies [05c888c]
|
|
692
|
+
- Updated dependencies [1b6789d]
|
|
693
|
+
- Updated dependencies [5794a86]
|
|
694
|
+
- Updated dependencies [09a3c7f]
|
|
695
|
+
- Updated dependencies [5ee090c]
|
|
696
|
+
- Updated dependencies [c9a0364]
|
|
697
|
+
- Updated dependencies [5141e1a]
|
|
698
|
+
- Updated dependencies [85dfd19]
|
|
699
|
+
- Updated dependencies [c538b1a]
|
|
700
|
+
- Updated dependencies [13a56b8]
|
|
701
|
+
- Updated dependencies [fb40ae1]
|
|
702
|
+
- Updated dependencies [c8cda86]
|
|
703
|
+
- Updated dependencies [76eeb86]
|
|
704
|
+
- Updated dependencies [0aa122f]
|
|
705
|
+
- Updated dependencies [72e42b4]
|
|
706
|
+
- Updated dependencies [2c11e4b]
|
|
707
|
+
- Updated dependencies [8858e61]
|
|
708
|
+
- Updated dependencies [05e238d]
|
|
709
|
+
- Updated dependencies [cf2115a]
|
|
710
|
+
- Updated dependencies [780e176]
|
|
711
|
+
- Updated dependencies [3294d70]
|
|
712
|
+
- Updated dependencies [16ed6ac]
|
|
713
|
+
- Updated dependencies [f7a682f]
|
|
714
|
+
- Updated dependencies [2ab78c6]
|
|
715
|
+
- Updated dependencies [372aaba]
|
|
716
|
+
- Updated dependencies [73baee0]
|
|
717
|
+
- Updated dependencies [b20aa59]
|
|
718
|
+
- Updated dependencies [f63fac7]
|
|
719
|
+
- Updated dependencies [f63fac7]
|
|
720
|
+
- Updated dependencies [a7d0158]
|
|
721
|
+
- Updated dependencies [cb9952f]
|
|
722
|
+
- Updated dependencies [74f30dd]
|
|
723
|
+
- Updated dependencies [05c888c]
|
|
724
|
+
- Updated dependencies [18a1138]
|
|
725
|
+
- Updated dependencies [c32d11d]
|
|
726
|
+
- Updated dependencies [ff32d79]
|
|
727
|
+
- Updated dependencies [a805f9c]
|
|
728
|
+
- Updated dependencies [05cadf6]
|
|
729
|
+
- Updated dependencies [996fc10]
|
|
730
|
+
- Updated dependencies [1b19215]
|
|
731
|
+
- Updated dependencies [8eb3026]
|
|
732
|
+
- Updated dependencies [a805f9c]
|
|
733
|
+
- Updated dependencies [7701c6a]
|
|
734
|
+
- Updated dependencies [f78d148]
|
|
735
|
+
- Updated dependencies [b637b3b]
|
|
736
|
+
- Updated dependencies [a805f9c]
|
|
737
|
+
- Updated dependencies [996fc10]
|
|
738
|
+
- @941design/marmot-engine@0.2.0-alpha.0
|
|
739
|
+
- @941design/nostr-events@0.2.0-alpha.0
|