@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.
Files changed (206) hide show
  1. package/CHANGELOG.md +739 -0
  2. package/LICENSE +21 -0
  3. package/README.md +33 -2
  4. package/dist/account/admin.d.ts +72 -0
  5. package/dist/account/admin.js +209 -0
  6. package/dist/account/device-deps.d.ts +379 -0
  7. package/dist/account/device-deps.js +36 -0
  8. package/dist/account/device-lineage.d.ts +199 -0
  9. package/dist/account/device-lineage.js +390 -0
  10. package/dist/account/device-registry.d.ts +93 -0
  11. package/dist/account/device-registry.js +1290 -0
  12. package/dist/account/device-rotation.d.ts +61 -0
  13. package/dist/account/device-rotation.js +827 -0
  14. package/dist/account/enrolment.d.ts +339 -0
  15. package/dist/account/enrolment.js +1247 -0
  16. package/dist/account/identity-proof.d.ts +79 -0
  17. package/dist/account/identity-proof.js +264 -0
  18. package/dist/account/index.d.ts +17 -0
  19. package/dist/account/index.js +16 -0
  20. package/dist/account/restore-rotation.d.ts +21 -0
  21. package/dist/account/restore-rotation.js +22 -0
  22. package/dist/account/same-account-authorization.d.ts +86 -0
  23. package/dist/account/same-account-authorization.js +180 -0
  24. package/dist/account/teardown.d.ts +190 -0
  25. package/dist/account/teardown.js +878 -0
  26. package/dist/client/admission-cleanup.d.ts +197 -0
  27. package/dist/client/admission-cleanup.js +635 -0
  28. package/dist/client/adoption-proof.d.ts +39 -0
  29. package/dist/client/adoption-proof.js +102 -0
  30. package/dist/client/before-create-group.d.ts +18 -0
  31. package/dist/client/before-create-group.js +65 -0
  32. package/dist/client/before-publish-hooks.d.ts +121 -0
  33. package/dist/client/before-publish-hooks.js +182 -0
  34. package/dist/client/client-config.d.ts +42 -0
  35. package/dist/client/client-config.js +13 -0
  36. package/dist/client/commit-redrive.d.ts +92 -0
  37. package/dist/client/commit-redrive.js +274 -0
  38. package/dist/client/component-update.d.ts +43 -0
  39. package/dist/client/component-update.js +53 -0
  40. package/dist/client/confirm-hooks.d.ts +55 -0
  41. package/dist/client/confirm-hooks.js +74 -0
  42. package/dist/client/create-client.d.ts +1126 -0
  43. package/dist/client/create-client.js +1232 -0
  44. package/dist/client/group-availability.d.ts +182 -0
  45. package/dist/client/group-availability.js +301 -0
  46. package/dist/client/group-disband.d.ts +28 -0
  47. package/dist/client/group-disband.js +64 -0
  48. package/dist/client/group-history.d.ts +461 -0
  49. package/dist/client/group-history.js +1365 -0
  50. package/dist/client/group-profile.d.ts +31 -0
  51. package/dist/client/group-profile.js +62 -0
  52. package/dist/client/group-records.d.ts +522 -0
  53. package/dist/client/group-records.js +1117 -0
  54. package/dist/client/group-removal.d.ts +36 -0
  55. package/dist/client/group-removal.js +127 -0
  56. package/dist/client/group-remove-member.d.ts +49 -0
  57. package/dist/client/group-remove-member.js +163 -0
  58. package/dist/client/group-runtime.d.ts +415 -0
  59. package/dist/client/group-runtime.js +2811 -0
  60. package/dist/client/group-snapshot.d.ts +104 -0
  61. package/dist/client/group-snapshot.js +474 -0
  62. package/dist/client/history-pages.d.ts +107 -0
  63. package/dist/client/history-pages.js +194 -0
  64. package/dist/client/inbox-send.d.ts +19 -0
  65. package/dist/client/inbox-send.js +71 -0
  66. package/dist/client/index.d.ts +24 -0
  67. package/dist/client/index.js +13 -0
  68. package/dist/client/ingest.d.ts +82 -0
  69. package/dist/client/ingest.js +1584 -0
  70. package/dist/client/invitation-outcomes.d.ts +50 -0
  71. package/dist/client/invitation-outcomes.js +135 -0
  72. package/dist/client/lifecycle-events.d.ts +63 -0
  73. package/dist/client/lifecycle-events.js +35 -0
  74. package/dist/client/opaque-candidates.d.ts +82 -0
  75. package/dist/client/opaque-candidates.js +170 -0
  76. package/dist/client/own-change-outbox.d.ts +66 -0
  77. package/dist/client/own-change-outbox.js +158 -0
  78. package/dist/client/pending-leaf.d.ts +116 -0
  79. package/dist/client/pending-leaf.js +378 -0
  80. package/dist/client/permissions.d.ts +9 -0
  81. package/dist/client/permissions.js +12 -0
  82. package/dist/client/pipeline.d.ts +583 -0
  83. package/dist/client/pipeline.js +3666 -0
  84. package/dist/client/reentrancy-guard.d.ts +102 -0
  85. package/dist/client/reentrancy-guard.js +159 -0
  86. package/dist/client/rekey.d.ts +58 -0
  87. package/dist/client/rekey.js +149 -0
  88. package/dist/client/transport-policy.d.ts +181 -0
  89. package/dist/client/transport-policy.js +214 -0
  90. package/dist/history/admission-lineage.d.ts +186 -0
  91. package/dist/history/admission-lineage.js +589 -0
  92. package/dist/history/equivocation.d.ts +55 -0
  93. package/dist/history/equivocation.js +113 -0
  94. package/dist/history/fencing.d.ts +66 -0
  95. package/dist/history/fencing.js +121 -0
  96. package/dist/history/hex.d.ts +3 -0
  97. package/dist/history/hex.js +10 -0
  98. package/dist/history/index.d.ts +74 -0
  99. package/dist/history/index.js +32 -0
  100. package/dist/history/notifications.d.ts +270 -0
  101. package/dist/history/notifications.js +264 -0
  102. package/dist/history/ordering-key.d.ts +24 -0
  103. package/dist/history/ordering-key.js +101 -0
  104. package/dist/history/own-change-fork.d.ts +112 -0
  105. package/dist/history/own-change-fork.js +196 -0
  106. package/dist/history/own-change.d.ts +118 -0
  107. package/dist/history/own-change.js +146 -0
  108. package/dist/history/policy.d.ts +48 -0
  109. package/dist/history/policy.js +52 -0
  110. package/dist/history/retained-window.d.ts +215 -0
  111. package/dist/history/retained-window.js +565 -0
  112. package/dist/inbox/demux.d.ts +90 -0
  113. package/dist/inbox/demux.js +78 -0
  114. package/dist/inbox/handler-registry.d.ts +42 -0
  115. package/dist/inbox/handler-registry.js +37 -0
  116. package/dist/inbox/index.d.ts +11 -0
  117. package/dist/inbox/index.js +10 -0
  118. package/dist/inbox/seen-set.d.ts +82 -0
  119. package/dist/inbox/seen-set.js +202 -0
  120. package/dist/inbox/subscription.d.ts +236 -0
  121. package/dist/inbox/subscription.js +644 -0
  122. package/dist/index.d.ts +10 -0
  123. package/dist/index.js +9 -0
  124. package/dist/invitations/competing-welcome.d.ts +223 -0
  125. package/dist/invitations/competing-welcome.js +128 -0
  126. package/dist/invitations/decline.d.ts +67 -0
  127. package/dist/invitations/decline.js +149 -0
  128. package/dist/invitations/delivery-evidence.d.ts +288 -0
  129. package/dist/invitations/delivery-evidence.js +766 -0
  130. package/dist/invitations/expect-welcome.d.ts +66 -0
  131. package/dist/invitations/expect-welcome.js +138 -0
  132. package/dist/invitations/index.d.ts +18 -0
  133. package/dist/invitations/index.js +18 -0
  134. package/dist/invitations/invitation-outcome.d.ts +110 -0
  135. package/dist/invitations/invitation-outcome.js +210 -0
  136. package/dist/invitations/invite.d.ts +358 -0
  137. package/dist/invitations/invite.js +1102 -0
  138. package/dist/invitations/offers.d.ts +79 -0
  139. package/dist/invitations/offers.js +115 -0
  140. package/dist/invitations/on-proposal.d.ts +47 -0
  141. package/dist/invitations/on-proposal.js +40 -0
  142. package/dist/invitations/pending-proposal-policy.d.ts +52 -0
  143. package/dist/invitations/pending-proposal-policy.js +139 -0
  144. package/dist/invitations/proposal-deadline.d.ts +133 -0
  145. package/dist/invitations/proposal-deadline.js +164 -0
  146. package/dist/invitations/relay-planes.d.ts +43 -0
  147. package/dist/invitations/relay-planes.js +70 -0
  148. package/dist/invitations/welcome-processor.d.ts +272 -0
  149. package/dist/invitations/welcome-processor.js +1241 -0
  150. package/dist/key-packages/device-key.d.ts +131 -0
  151. package/dist/key-packages/device-key.js +272 -0
  152. package/dist/key-packages/device-rotation-records.d.ts +83 -0
  153. package/dist/key-packages/device-rotation-records.js +173 -0
  154. package/dist/key-packages/group-refs.d.ts +40 -0
  155. package/dist/key-packages/group-refs.js +79 -0
  156. package/dist/key-packages/index.d.ts +18 -0
  157. package/dist/key-packages/index.js +18 -0
  158. package/dist/key-packages/key-package-ref.d.ts +16 -0
  159. package/dist/key-packages/key-package-ref.js +21 -0
  160. package/dist/key-packages/observation-stream.d.ts +4 -0
  161. package/dist/key-packages/observation-stream.js +120 -0
  162. package/dist/key-packages/offer-rumor.d.ts +26 -0
  163. package/dist/key-packages/offer-rumor.js +69 -0
  164. package/dist/key-packages/publisher.d.ts +174 -0
  165. package/dist/key-packages/publisher.js +1247 -0
  166. package/dist/key-packages/select-key-package.d.ts +24 -0
  167. package/dist/key-packages/select-key-package.js +90 -0
  168. package/dist/key-packages/slot-manager.d.ts +167 -0
  169. package/dist/key-packages/slot-manager.js +327 -0
  170. package/dist/key-packages/validate-key-package-event.d.ts +3 -0
  171. package/dist/key-packages/validate-key-package-event.js +49 -0
  172. package/dist/media/cache.d.ts +14 -0
  173. package/dist/media/cache.js +10 -0
  174. package/dist/media/index.d.ts +52 -0
  175. package/dist/media/index.js +71 -0
  176. package/dist/mls.d.ts +15 -0
  177. package/dist/mls.js +15 -0
  178. package/dist/shared/account-pubkey.d.ts +4 -0
  179. package/dist/shared/account-pubkey.js +10 -0
  180. package/dist/shared/errors.d.ts +28 -0
  181. package/dist/shared/errors.js +96 -0
  182. package/dist/shared/hex.d.ts +4 -0
  183. package/dist/shared/hex.js +13 -0
  184. package/dist/shared/index.d.ts +14 -0
  185. package/dist/shared/index.js +14 -0
  186. package/dist/shared/kinds.d.ts +8 -0
  187. package/dist/shared/kinds.js +28 -0
  188. package/dist/shared/publish-classification.d.ts +26 -0
  189. package/dist/shared/publish-classification.js +31 -0
  190. package/dist/storage/envelope.d.ts +39 -0
  191. package/dist/storage/envelope.js +201 -0
  192. package/dist/storage/index.d.ts +237 -0
  193. package/dist/storage/index.js +491 -0
  194. package/dist/storage/indexeddb/idb-types.d.ts +68 -0
  195. package/dist/storage/indexeddb/idb-types.js +1 -0
  196. package/dist/storage/indexeddb/index.d.ts +17 -0
  197. package/dist/storage/indexeddb/index.js +141 -0
  198. package/dist/storage/lease.d.ts +54 -0
  199. package/dist/storage/lease.js +168 -0
  200. package/dist/storage/memory/deterministic-signer.d.ts +27 -0
  201. package/dist/storage/memory/deterministic-signer.js +65 -0
  202. package/dist/storage/memory/index.d.ts +32 -0
  203. package/dist/storage/memory/index.js +87 -0
  204. package/dist/storage/memory/lock-manager.d.ts +8 -0
  205. package/dist/storage/memory/lock-manager.js +71 -0
  206. package/package.json +66 -3
@@ -0,0 +1,102 @@
1
+ /** Consumer-supplied surfaces a `marmot` operation calls into (DD13 enumeration). */
2
+ export type ConsumerSurface = 'store' | 'signer' | 'verifier' | 'onConfirm'
3
+ /** AC-HOOK-8: an `extensions.onBeforePublish` hook or the barrier it returned (before an own commit's first publish). */
4
+ | 'onBeforePublish' | 'onProposal' | 'transport' | 'adminPolicyCallback' | 'authorizeCommit' | 'compareKeyPackageToLeafNode' | 'beforeCreateGroup' | 'inboxHandler' | 'onApplicationRumor'
5
+ /** S10: the rumor history backend seam (`MarmotClientOptions.history`). */
6
+ | 'historyBackend'
7
+ /** S10: the media cache seam (`MarmotClientOptions.mediaCache`). */
8
+ | 'mediaCache'
9
+ /**
10
+ * Not consumer code: the frame a `devices.*` operation runs in on
11
+ * {@link DEVICE_SCOPE} (S8), so that consumer code it calls — an `onConfirm`
12
+ * hook of its commit, a store, a signer — carries it and a nested `devices.*`
13
+ * call from there is rejected instead of queueing behind the operation that
14
+ * waits for it.
15
+ */
16
+ | 'deviceOperation';
17
+ /**
18
+ * The consumer-supplied surfaces that run inside a group operation, on that group's queue: their live frame (on ANY
19
+ * group) blocks an operation that would queue behind it — a `devices.*` op (S3, AC-RE-2) or a recovery read
20
+ * (epic marmot-invitation-outcomes SC-9). The one list both refusals read.
21
+ */
22
+ export declare const GROUP_CONSUMER_SURFACES: readonly ConsumerSurface[];
23
+ /** Scope key of account-level operations (group operations use their group id). */
24
+ export declare const ACCOUNT_SCOPE = "\0account";
25
+ /** Scope key of the device service's serial queue (`devices.*` operations and their background passes, S8). */
26
+ export declare const DEVICE_SCOPE = "\0devices";
27
+ /** The subset of `AsyncLocalStorage` the guard uses. */
28
+ export interface AsyncContextLike<T> {
29
+ run<R>(store: T, fn: () => R): R;
30
+ getStore(): T | undefined;
31
+ }
32
+ /** One surface call; frames chain outwards through `parent`. */
33
+ export interface SurfaceFrame {
34
+ readonly scope: string;
35
+ readonly surface: ConsumerSurface;
36
+ readonly parent: SurfaceFrame | undefined;
37
+ /** True until the surface call settles; a dead frame is skipped by every lookup. */
38
+ live: boolean;
39
+ }
40
+ export interface ReentrancyGuardOptions {
41
+ /**
42
+ * Async-context carrier. Omitted: `AsyncLocalStorage` when the runtime has
43
+ * one. `null`: none — synchronous detection only (the browser behaviour).
44
+ */
45
+ readonly asyncContext?: AsyncContextLike<SurfaceFrame | undefined> | null;
46
+ }
47
+ export interface ReentrancyGuard {
48
+ /** Whether re-entry after an `await` inside a surface is detected (an async context is available). */
49
+ readonly tracksAsync: boolean;
50
+ /**
51
+ * Runs `fn` (a call into consumer code) inside a surface frame on `scope`:
52
+ * the whole async duration of `fn` when {@link tracksAsync}, else its
53
+ * synchronous part. A synchronous throw from `fn` becomes a rejection.
54
+ */
55
+ call<T>(scope: string, surface: ConsumerSurface, fn: () => T | Promise<T>): Promise<T>;
56
+ /** Runs `fn` inside a surface frame only while it runs synchronously; returns its value unchanged. */
57
+ callSync<T>(scope: string, surface: ConsumerSurface, fn: () => T): T;
58
+ /**
59
+ * Throws `MarmotError('reentrant')` (details `{ scope, operation, surface }`,
60
+ * `surface` = innermost frame on `scope`) when the calling code runs inside
61
+ * a surface frame on `scope`.
62
+ */
63
+ assertNotReentrant(scope: string, operation: string): void;
64
+ /** Whether the calling code runs inside a surface frame on `scope`. */
65
+ active(scope: string): boolean;
66
+ /**
67
+ * The innermost live `surface` frame of `scope` the current context runs inside (any depth), or `undefined`
68
+ * when none is live. `scope` of `undefined` matches a live frame of `surface` on ANY scope — for a check
69
+ * that must fire from inside a given surface regardless of which scope's operation is running it (e.g.
70
+ * AC-RE-2: a device operation must not enqueue while a GROUP's own `onConfirm`/`verifier`/`onProposal`
71
+ * surface is live, whichever group — a caller matching with `scope: undefined` still needs the matched
72
+ * frame's own `scope` back, e.g. to exclude `ACCOUNT_SCOPE`/`DEVICE_SCOPE` or to report it in an error's
73
+ * `details`, which a plain boolean could not carry). A truthy/falsy check on the result still reads like a
74
+ * boolean (`if (guard.within(...))`).
75
+ */
76
+ within(scope: string | undefined, surface: ConsumerSurface): SurfaceFrame | undefined;
77
+ /**
78
+ * The innermost live `surface` frame whose scope is an actual GROUP id — never `ACCOUNT_SCOPE` or
79
+ * `DEVICE_SCOPE` — or `undefined` when none is live (AC-RE-2). Unlike
80
+ * `within(undefined, surface)`, this does not stop at the innermost matching frame if THAT frame's scope is
81
+ * excluded: it keeps walking outward past an `ACCOUNT_SCOPE`/`DEVICE_SCOPE` frame of the same surface (e.g.
82
+ * an account-scope `verifier` nested inside a group's own `verifier`) to find the genuine group frame
83
+ * beneath it. Filtering `within`'s result AFTER the fact cannot do this — it only ever sees the innermost
84
+ * match, so a nested excluded frame of the same surface would hide a live, outer group frame entirely.
85
+ */
86
+ withinGroupScope(surface: ConsumerSurface): SurfaceFrame | undefined;
87
+ /**
88
+ * The innermost live frame of ANY surface whose scope is a group id or {@link ACCOUNT_SCOPE} — never a
89
+ * {@link DEVICE_SCOPE} frame — or `undefined` when the calling code runs inside none: whether it runs inside
90
+ * consumer code some group's or the account's serialised queue is waiting on (AC-MX-2: a wait of unbounded
91
+ * length from there would hold that queue for as long).
92
+ */
93
+ withinConsumerScope(): SurfaceFrame | undefined;
94
+ /**
95
+ * Runs `fn` outside every surface frame (no synchronous frame, an empty async
96
+ * context): for notifications `marmot` dispatches but does not await, whose
97
+ * listeners must be free to start operations of their own — they queue, and
98
+ * nothing waits on them.
99
+ */
100
+ detached<T>(fn: () => T): T;
101
+ }
102
+ export declare function createReentrancyGuard(options?: ReentrancyGuardOptions): ReentrancyGuard;
@@ -0,0 +1,159 @@
1
+ /**
2
+ * ADR-013 / DD13 re-entrancy guard (AC-PIPE-11).
3
+ *
4
+ * Every call from a `marmot` operation into consumer-supplied code — the
5
+ * ADR-007 stores, the `Signer`, the event `verifier`, `onConfirm` hooks,
6
+ * `onProposal`, the engine seams (`adminPolicyCallback`, `authorizeCommit`,
7
+ * `compareKeyPackageToLeafNode`), `beforeCreateGroup` gates, inbox handlers
8
+ * and `onApplicationRumor` — runs through {@link ReentrancyGuard.call}
9
+ * with the scope (a group id, or {@link ACCOUNT_SCOPE}) whose serialised
10
+ * operation queue the caller holds. Mutating operations call
11
+ * {@link ReentrancyGuard.assertNotReentrant} synchronously before they
12
+ * enqueue: a call made FROM INSIDE such a surface on the same scope is
13
+ * rejected `reentrant`, because it would queue behind the very operation
14
+ * that is waiting for it (a storage transaction's `fn` awaiting
15
+ * `group.send()` never settles — the storage module's re-entrancy rule).
16
+ *
17
+ * "From inside" is tracked per execution context, not by wall-clock overlap:
18
+ * where the runtime offers `AsyncLocalStorage` (Node, Deno, Bun — reached
19
+ * through `process.getBuiltinModule`, so browser bundles import nothing) the
20
+ * surface frame follows the consumer's code across its own `await`s, and an
21
+ * independent top-level call made while an operation happens to be awaiting a
22
+ * surface is never in that context — it simply queues. Without it (browsers
23
+ * today) only re-entry during the surface's synchronous part is detectable;
24
+ * an asynchronous re-entry that the surface then awaits deadlocks that one
25
+ * group's queue — and, for a `devices.*` call made from inside that surface
26
+ * (`assertNotInGroupConsumerSurface`, S3 AC-RE-2), the device queue as well:
27
+ * that check is the same `within` lookup, so it shares the same inability to
28
+ * see an asynchronous re-entry without async-context tracking. That is the
29
+ * bounded residue ADR-013 Decision item 4 asks to be stated: it needs
30
+ * consumer code that awaits a mutating `marmot` call from inside a callback
31
+ * `marmot` is itself awaiting, and it affects up to two queues — the
32
+ * surface's own scope and, for a device-op call made from inside it,
33
+ * DEVICE_SCOPE too.
34
+ *
35
+ * A frame is live only while its surface call runs: once `fn` settles the
36
+ * frame is marked dead, and every lookup skips it. `AsyncLocalStorage` hands
37
+ * the frame on to anything the surface scheduled — a timer, an un-awaited
38
+ * async function — and that detached work outlives the call; it no longer
39
+ * waits on the operation that invoked the surface, so it is not re-entry
40
+ * and simply queues.
41
+ *
42
+ * Transport calls use {@link ReentrancyGuard.callSync}: a synchronous frame
43
+ * only. Callbacks a transport registers (socket handlers, subscription
44
+ * observers) must not inherit a surface frame, or every live event they
45
+ * later deliver would look re-entrant.
46
+ *
47
+ * Per-instance state only (INV-NO-SINGLETONS): one guard per client.
48
+ */
49
+ import { MarmotError } from '../shared/index.js';
50
+ /**
51
+ * The consumer-supplied surfaces that run inside a group operation, on that group's queue: their live frame (on ANY
52
+ * group) blocks an operation that would queue behind it — a `devices.*` op (S3, AC-RE-2) or a recovery read
53
+ * (epic marmot-invitation-outcomes SC-9). The one list both refusals read.
54
+ */
55
+ export const GROUP_CONSUMER_SURFACES = Object.freeze(['onConfirm', 'onBeforePublish', 'verifier', 'onProposal']);
56
+ /** Scope key of account-level operations (group operations use their group id). */
57
+ export const ACCOUNT_SCOPE = '\u0000account';
58
+ /** Scope key of the device service's serial queue (`devices.*` operations and their background passes, S8). */
59
+ export const DEVICE_SCOPE = '\u0000devices';
60
+ function defaultAsyncContext() {
61
+ const proc = globalThis.process;
62
+ const load = proc?.getBuiltinModule;
63
+ if (typeof load !== 'function')
64
+ return undefined;
65
+ try {
66
+ const mod = load.call(proc, 'node:async_hooks');
67
+ return mod?.AsyncLocalStorage === undefined ? undefined : new mod.AsyncLocalStorage();
68
+ }
69
+ catch {
70
+ return undefined;
71
+ }
72
+ }
73
+ export function createReentrancyGuard(options = {}) {
74
+ const context = options.asyncContext === null ? undefined : (options.asyncContext ?? defaultAsyncContext());
75
+ // Frame of the synchronous surface call currently on the stack, if any.
76
+ let syncFrame;
77
+ function current() {
78
+ return syncFrame ?? context?.getStore();
79
+ }
80
+ function innermost(scope) {
81
+ for (let f = current(); f !== undefined; f = f.parent)
82
+ if (f.live && f.scope === scope)
83
+ return f;
84
+ return undefined;
85
+ }
86
+ function runSync(frame, fn) {
87
+ const saved = syncFrame;
88
+ syncFrame = frame;
89
+ try {
90
+ return fn();
91
+ }
92
+ finally {
93
+ syncFrame = saved;
94
+ }
95
+ }
96
+ return {
97
+ tracksAsync: context !== undefined,
98
+ async call(scope, surface, fn) {
99
+ const frame = { scope, surface, parent: current(), live: true };
100
+ try {
101
+ if (context === undefined)
102
+ return await runSync(frame, fn);
103
+ return await context.run(frame, () => runSync(frame, fn));
104
+ }
105
+ finally {
106
+ frame.live = false;
107
+ }
108
+ },
109
+ callSync(scope, surface, fn) {
110
+ const frame = { scope, surface, parent: current(), live: true };
111
+ try {
112
+ return runSync(frame, fn);
113
+ }
114
+ finally {
115
+ frame.live = false;
116
+ }
117
+ },
118
+ assertNotReentrant(scope, operation) {
119
+ const frame = innermost(scope);
120
+ if (frame === undefined)
121
+ return;
122
+ throw new MarmotError('reentrant', `${operation}: re-entrant call on scope ${JSON.stringify(scope)} (inside ${frame.surface})`, {
123
+ details: { scope, operation, surface: frame.surface },
124
+ });
125
+ },
126
+ active(scope) {
127
+ return innermost(scope) !== undefined;
128
+ },
129
+ within(scope, surface) {
130
+ for (let f = current(); f !== undefined; f = f.parent)
131
+ if (f.live && (scope === undefined || f.scope === scope) && f.surface === surface)
132
+ return f;
133
+ return undefined;
134
+ },
135
+ withinGroupScope(surface) {
136
+ for (let f = current(); f !== undefined; f = f.parent) {
137
+ if (f.live && f.surface === surface && f.scope !== ACCOUNT_SCOPE && f.scope !== DEVICE_SCOPE)
138
+ return f;
139
+ }
140
+ return undefined;
141
+ },
142
+ withinConsumerScope() {
143
+ for (let f = current(); f !== undefined; f = f.parent)
144
+ if (f.live && f.scope !== DEVICE_SCOPE)
145
+ return f;
146
+ return undefined;
147
+ },
148
+ detached(fn) {
149
+ const saved = syncFrame;
150
+ syncFrame = undefined;
151
+ try {
152
+ return context === undefined ? fn() : context.run(undefined, fn);
153
+ }
154
+ finally {
155
+ syncFrame = saved;
156
+ }
157
+ },
158
+ };
159
+ }
@@ -0,0 +1,58 @@
1
+ import type { SendIntent } from '@941design/marmot-engine/engine';
2
+ import { type ClientState } from '@941design/marmot-engine/mls';
3
+ import { type DeviceSigningKey } from '../key-packages/index.js';
4
+ import type { GroupRuntime } from './group-runtime.js';
5
+ /** The signature key (hex) the local leaf of `state` holds, or `undefined` when its index holds no leaf. */
6
+ export declare function ownLeafKeyOf(state: ClientState): string | undefined;
7
+ /** The local leaf's index and signature key (hex) in `state`, or `undefined` when its index holds no leaf. */
8
+ export declare function ownLeafOf(state: ClientState): {
9
+ readonly leafIndex: number;
10
+ readonly leafKey: string;
11
+ } | undefined;
12
+ /** The account (hex credential identity) of the local leaf in `state`, or `undefined` when it cannot be read. No signer call. */
13
+ export declare function ownAccountOf(state: ClientState): string | undefined;
14
+ /** What {@link planRekey} decided about a `rekey` record at drive time. */
15
+ export type RekeyPlan =
16
+ /** The target is not (or no longer) the device's current key: the newer rotation's re-key set covers the group. */
17
+ {
18
+ readonly kind: 'superseded';
19
+ }
20
+ /** The local leaf already carries the target: no commit (an empty epoch bump) is made. */
21
+ | {
22
+ readonly kind: 'already-rekeyed';
23
+ }
24
+ /** The engine intent to stage. */
25
+ | {
26
+ readonly kind: 'build';
27
+ readonly intent: Extract<SendIntent, {
28
+ kind: 'selfUpdate';
29
+ }>;
30
+ };
31
+ /**
32
+ * `deviceRegistry/self`, read through the account store on the account scope. Never inside a group transaction: the
33
+ * account store is the wider scope (lock order group -> account holds for a transaction, not for a read made first).
34
+ */
35
+ export declare function readSelfKey(rt: GroupRuntime): Promise<DeviceSigningKey | undefined>;
36
+ /**
37
+ * An account-store read made on behalf of a group operation: framed on the account scope AND the group's scope (like
38
+ * `callSignerForGroup`), so a store that awaits a mutating call on this group — which would queue behind the operation
39
+ * awaiting the store — is rejected `reentrant` instead of deadlocking.
40
+ */
41
+ export declare function accountRead<T>(rt: GroupRuntime, fn: () => Promise<T>): Promise<T>;
42
+ /**
43
+ * Whether the tree of `state` holds `target` at an index other than the local leaf's, and whose leaf is of the
44
+ * local account: a duplicate-leaf state (Design Decision 10, AC-REKEY-12). The indexes found are the ones the rekey
45
+ * commit Removes in the same commit as the path rotation. A leaf of ANOTHER account holding `target` is never
46
+ * removed here: the engine refuses the patch (`signature keys not unique`) and the intent goes terminal.
47
+ */
48
+ export declare function duplicateLeafIndexes(state: ClientState, target: string): number[];
49
+ /**
50
+ * Decides and builds the engine intent of a `rekey` record toward `target`, against the engine's current state:
51
+ * - `superseded` when `deviceRegistry/self` no longer holds `target` (a later rotation) — checked first;
52
+ * - `already-rekeyed` when the local leaf already carries `target`;
53
+ * - otherwise a `selfUpdate` whose `leafNodePatch` is the device key pair and the own leaf's extensions with the
54
+ * proof extension replaced by the stored proof (the proof is NOT checked here: the sender-side
55
+ * `enforceStateTransition` gate after `engine.send` is the one place that refuses a missing or foreign proof,
56
+ * AC-REKEY-4), plus a by-value `Remove` of every duplicate same-account leaf holding `target` (atomic repair).
57
+ */
58
+ export declare function planRekey(rt: GroupRuntime, target: string): Promise<RekeyPlan>;
@@ -0,0 +1,149 @@
1
+ /**
2
+ * The `rekey` self-update (epic marmot-device-key-rotation, S6; spec Design Decisions 3, 5, 10): a self-update whose
3
+ * UpdatePath leaf carries the device's NEW signature key and the proof the account signed for it once, so the local
4
+ * leaf of a group moves from the key it holds to `deviceRegistry/self`'s key in one ordinary own commit.
5
+ *
6
+ * This module decides and builds; `pipeline.ts` records, drives, publishes and confirms. Everything it reads from the
7
+ * account store (the key pair, the stored proof) is read here, OUTSIDE any group transaction, at build time:
8
+ * the pending-intent record names the target by its PUBLIC key only (AC-REKEY-3).
9
+ */
10
+ import { ACCOUNT_IDENTITY_PROOF_EXTENSION_TYPE, getCredentialPubkey, makeAccountIdentityProofExtension, mlsSignatureScheme } from '@941design/marmot-engine/core';
11
+ import { defaultProposalTypes, nodeTypes } from '@941design/marmot-engine/mls';
12
+ import { readDeviceSigningKey } from '../key-packages/index.js';
13
+ import { ACCOUNT_SCOPE } from './reentrancy-guard.js';
14
+ function toHex(bytes) {
15
+ return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
16
+ }
17
+ function hexToBytes(hex) {
18
+ const out = new Uint8Array(hex.length / 2);
19
+ for (let i = 0; i < out.length; i++)
20
+ out[i] = Number.parseInt(hex.slice(2 * i, 2 * i + 2), 16);
21
+ return out;
22
+ }
23
+ /** The signature key (hex) the local leaf of `state` holds, or `undefined` when its index holds no leaf. */
24
+ export function ownLeafKeyOf(state) {
25
+ return ownLeafOf(state)?.leafKey;
26
+ }
27
+ /** The local leaf's index and signature key (hex) in `state`, or `undefined` when its index holds no leaf. */
28
+ export function ownLeafOf(state) {
29
+ const leafIndex = Number(state.privatePath.leafIndex);
30
+ const node = state.ratchetTree[2 * leafIndex];
31
+ if (node?.nodeType !== nodeTypes.leaf)
32
+ return undefined;
33
+ return { leafIndex, leafKey: toHex(node.leaf.signaturePublicKey) };
34
+ }
35
+ /** The account (hex credential identity) of the local leaf in `state`, or `undefined` when it cannot be read. No signer call. */
36
+ export function ownAccountOf(state) {
37
+ const node = state.ratchetTree[2 * Number(state.privatePath.leafIndex)];
38
+ if (node?.nodeType !== nodeTypes.leaf)
39
+ return undefined;
40
+ try {
41
+ return getCredentialPubkey(node.leaf.credential);
42
+ }
43
+ catch {
44
+ return undefined;
45
+ }
46
+ }
47
+ /**
48
+ * `deviceRegistry/self`, read through the account store on the account scope. Never inside a group transaction: the
49
+ * account store is the wider scope (lock order group -> account holds for a transaction, not for a read made first).
50
+ */
51
+ export function readSelfKey(rt) {
52
+ return readDeviceSigningKey((fn) => accountRead(rt, () => rt.ctx.stores.account.transaction(fn)));
53
+ }
54
+ /**
55
+ * An account-store read made on behalf of a group operation: framed on the account scope AND the group's scope (like
56
+ * `callSignerForGroup`), so a store that awaits a mutating call on this group — which would queue behind the operation
57
+ * awaiting the store — is rejected `reentrant` instead of deadlocking.
58
+ */
59
+ export function accountRead(rt, fn) {
60
+ return rt.guard.call(rt.groupId, 'store', () => rt.guard.call(ACCOUNT_SCOPE, 'store', fn));
61
+ }
62
+ /**
63
+ * The leaf extensions of the original own leaf with the account identity proof replaced by `proof`'s (every other
64
+ * extension unchanged and in place; appended when the leaf carried none): ts-mls replaces the whole list a patch
65
+ * names, so the patch must restate the others.
66
+ */
67
+ function extensionsWithProof(leafExtensions, request, proof) {
68
+ const replacement = makeAccountIdentityProofExtension({ request, signature: proof });
69
+ const out = [];
70
+ let replaced = false;
71
+ for (const extension of leafExtensions) {
72
+ if (extension.extensionType === ACCOUNT_IDENTITY_PROOF_EXTENSION_TYPE) {
73
+ if (!replaced)
74
+ out.push(replacement);
75
+ replaced = true;
76
+ }
77
+ else
78
+ out.push(extension);
79
+ }
80
+ if (!replaced)
81
+ out.push(replacement);
82
+ return out;
83
+ }
84
+ /**
85
+ * Whether the tree of `state` holds `target` at an index other than the local leaf's, and whose leaf is of the
86
+ * local account: a duplicate-leaf state (Design Decision 10, AC-REKEY-12). The indexes found are the ones the rekey
87
+ * commit Removes in the same commit as the path rotation. A leaf of ANOTHER account holding `target` is never
88
+ * removed here: the engine refuses the patch (`signature keys not unique`) and the intent goes terminal.
89
+ */
90
+ export function duplicateLeafIndexes(state, target) {
91
+ const own = ownLeafOf(state);
92
+ const ownAccount = ownAccountOf(state);
93
+ if (own === undefined || ownAccount === undefined)
94
+ return [];
95
+ const out = [];
96
+ const leafCount = Math.ceil(state.ratchetTree.length / 2);
97
+ for (let leafIndex = 0; leafIndex < leafCount; leafIndex++) {
98
+ if (leafIndex === own.leafIndex)
99
+ continue;
100
+ const node = state.ratchetTree[2 * leafIndex];
101
+ if (node?.nodeType !== nodeTypes.leaf || toHex(node.leaf.signaturePublicKey) !== target)
102
+ continue;
103
+ try {
104
+ if (getCredentialPubkey(node.leaf.credential) === ownAccount)
105
+ out.push(leafIndex);
106
+ }
107
+ catch {
108
+ // A leaf with an unreadable credential is not provably the local account's: left to the engine's uniqueness check.
109
+ }
110
+ }
111
+ return out;
112
+ }
113
+ /**
114
+ * Decides and builds the engine intent of a `rekey` record toward `target`, against the engine's current state:
115
+ * - `superseded` when `deviceRegistry/self` no longer holds `target` (a later rotation) — checked first;
116
+ * - `already-rekeyed` when the local leaf already carries `target`;
117
+ * - otherwise a `selfUpdate` whose `leafNodePatch` is the device key pair and the own leaf's extensions with the
118
+ * proof extension replaced by the stored proof (the proof is NOT checked here: the sender-side
119
+ * `enforceStateTransition` gate after `engine.send` is the one place that refuses a missing or foreign proof,
120
+ * AC-REKEY-4), plus a by-value `Remove` of every duplicate same-account leaf holding `target` (atomic repair).
121
+ */
122
+ export async function planRekey(rt, target) {
123
+ const self = await readSelfKey(rt);
124
+ if (self === undefined || self.leafKey !== target)
125
+ return { kind: 'superseded' };
126
+ // Read after the await: the engine state the commit is built on (no await between this read and `engine.send`).
127
+ const state = rt.engine.state;
128
+ const own = ownLeafOf(state);
129
+ if (own?.leafKey === target)
130
+ return { kind: 'already-rekeyed' };
131
+ const leafIndex = Number(state.privatePath.leafIndex);
132
+ const ownNode = state.ratchetTree[2 * leafIndex];
133
+ if (ownNode?.nodeType !== nodeTypes.leaf)
134
+ return { kind: 'superseded' };
135
+ const leaf = ownNode.leaf;
136
+ const patch = { signatureKeyPair: { publicKey: self.publicKey.slice(), signKey: self.signKey.slice() } };
137
+ if (self.proof !== undefined) {
138
+ const ciphersuite = state.groupContext.cipherSuite;
139
+ const request = {
140
+ accountIdentity: hexToBytes(getCredentialPubkey(leaf.credential)),
141
+ mlsSignaturePublicKey: self.publicKey,
142
+ ciphersuite,
143
+ signatureScheme: mlsSignatureScheme(ciphersuite),
144
+ };
145
+ patch.extensions = extensionsWithProof(leaf.extensions, request, self.proof);
146
+ }
147
+ const removes = duplicateLeafIndexes(state, target).map((removed) => ({ proposalType: defaultProposalTypes.remove, remove: { removed } }));
148
+ return { kind: 'build', intent: { kind: 'selfUpdate', leafNodePatch: patch, ...(removes.length === 0 ? {} : { extraProposals: removes }) } };
149
+ }
@@ -0,0 +1,181 @@
1
+ /**
2
+ * Transport policy over the narrowed `TransportContract` (ADR-008; spec
3
+ * Design Decision 12): the kind-445 relay plane, publish classification,
4
+ * discard-on-`timedOut` (AC-PIPE-7), history-silence exclusion
5
+ * (AC-PIPE-14), and the durable-cursor arithmetic (AC-PIPE-5). Pure policy
6
+ * objects — the group runtime owns the I/O and the storage.
7
+ *
8
+ * Relay URLs are facts here (ADR-014): compared and reported as the raw
9
+ * strings the group state / `RequestWithDeadlineResult` carry, never
10
+ * normalised.
11
+ */
12
+ import type { Filter } from '@941design/nostr-events/event';
13
+ import type { RequestWithDeadlineResult } from '@941design/nostr-events/transport/contract';
14
+ import { classifyPublish, type PublishOutcome } from '../shared/index.js';
15
+ export { classifyPublish, type PublishOutcome };
16
+ /** Kind of Marmot group events (MIP-03). */
17
+ export declare const GROUP_EVENT_KIND = 445;
18
+ /**
19
+ * The group's relay plane for kind 445: the group state's relays (routing
20
+ * component), or `fallback` (the client's `relays.defaults`) when the group
21
+ * names none. Order preserved, raw strings, duplicates dropped by exact match.
22
+ */
23
+ export declare function groupRelayPlane(groupRelays: readonly string[], fallback: readonly string[]): string[];
24
+ /** The kind-445 filter for one group, `since` the cursor when given. */
25
+ export declare function groupEventFilter(nostrGroupId: string, since?: number): Filter;
26
+ /**
27
+ * Per-group consecutive history-timeout counters (AC-PIPE-14).
28
+ *
29
+ * `record(requested, result)` after each history request:
30
+ * - `timedOut: false` → every requested relay's counter resets to 0;
31
+ * - `timedOut: true` → each requested relay listed in `silentRelays`
32
+ * increments; every other requested relay resets to 0. A relay whose
33
+ * counter reaches `threshold` is excluded and returned (once, ever) in
34
+ * `newlySilent`.
35
+ * `exclude(relay)` excludes a relay for another reason (a history walk it
36
+ * never lets progress). `historyRelays(plane)` is `plane` minus excluded
37
+ * relays — or `plane` itself when that would leave no relay. Publishes and the live
38
+ * subscription never consult the exclusion.
39
+ */
40
+ export interface HistorySilenceTracker {
41
+ record(requested: readonly string[], result: Pick<RequestWithDeadlineResult, 'timedOut' | 'silentRelays'>): {
42
+ readonly newlySilent: readonly string[];
43
+ };
44
+ historyRelays(plane: readonly string[]): string[];
45
+ excluded(): readonly string[];
46
+ /** Excludes `relay` from history for a reason other than silence (a walk that makes no progress); `true` when newly excluded. */
47
+ exclude(relay: string): boolean;
48
+ }
49
+ export declare function createHistorySilenceTracker(threshold: number): HistorySilenceTracker;
50
+ /**
51
+ * Persisted ingest cursor (`ingestCursor` artifact, key {@link CURSOR_KEY}).
52
+ *
53
+ * `high` is the high-water `created_at` of events that were authenticated
54
+ * and processed terminally (applied / application / duplicate) — never of a
55
+ * rejected, wrong-group, verifier-rejected, undecryptable or past-epoch
56
+ * event, so an outsider stamping junk with the group's `h` tag cannot move
57
+ * it — and each contribution is clamped to the client clock plus
58
+ * {@link CURSOR_FUTURE_SKEW_S}.
59
+ *
60
+ * Events that still need redelivery are held in three tiers, id → `created_at`:
61
+ * - `pins` — events the engine deferred as group content not yet
62
+ * applicable (awaiting their epoch's commit). Not evicted by
63
+ * age or count; a pin goes when its event turns terminal, when a
64
+ * redelivery re-classifies it, or when a complete history pass that
65
+ * should have returned it did not (see {@link absentPins}).
66
+ * - `busy` — events dropped unclassified as `group-busy` while a
67
+ * confirmation was blocked. Nothing authenticated them (anything stamped
68
+ * with the group's `h` tag qualifies), so the tier is capped at
69
+ * {@link MAX_BUSY_PINS} under the eviction policy below. A busy entry
70
+ * never displaces an existing pin or hold of the same id, and is released
71
+ * like a pin when a completed history pass no longer returns it.
72
+ * - `holds` — unauthenticated, undecryptable envelopes (anyone can stamp
73
+ * one with the group's `h` tag). Bounded: older than
74
+ * {@link HOLD_MAX_AGE_S} is given up, and the tier is capped at
75
+ * {@link MAX_HOLDS} under the eviction policy below. A record written before pins existed
76
+ * decodes with all its holds in this evictable tier (its prior
77
+ * semantics).
78
+ *
79
+ * Eviction policy of the capped tiers (`busy`, `holds`): over the cap, the
80
+ * newest entries are dropped; the oldest are kept. So a flood of near-now
81
+ * junk can displace neither an older entry nor any pin, and the floor never
82
+ * rises above a dropped entry while an older one is kept.
83
+ * `since` = min(`high`, every pin, busy entry and hold) − {@link CURSOR_REDELIVERY_MARGIN_S}
84
+ * — the terminal ledger dedups what the margin redelivers.
85
+ *
86
+ * `resume` — a history backlog too deep for one pass (the per-relay
87
+ * pagination hit its page bound), walked down first and then ingested
88
+ * OLDEST-FIRST, window by window, so no event is ingested before an older
89
+ * one it may depend on:
90
+ * - descending: a pass over `[from, until]` that is not complete ingests
91
+ * nothing; it pushes `until` onto `above` and lowers `until` to the edge
92
+ * it reached;
93
+ * - ascending: a pass that completes `[from, until]` ingests it, then moves
94
+ * on to the window above: `from = until + 1`, `until = above[0]`
95
+ * (`above` shifted), or — `above` empty — the open-topped window
96
+ * `[until + 1, …)`, whose completion clears `resume`.
97
+ * `until` absent = open above. While set, `since` never rises above `from`.
98
+ * A record written before `resume` existed decodes without one.
99
+ */
100
+ export interface IngestCursor {
101
+ /**
102
+ * Inclusive `since` (unix seconds) the next history request / subscription starts from. A joined group starts at its
103
+ * join floor (owner decision 20: the Welcome's time minus `CURSOR_FUTURE_SKEW_S`), never at the group's beginning.
104
+ */
105
+ readonly since: number;
106
+ readonly high?: number;
107
+ /** Undecryptable (unauthenticated) holds: bounded by {@link MAX_HOLDS} and {@link HOLD_MAX_AGE_S}. */
108
+ readonly holds?: Readonly<Record<string, number>>;
109
+ /** Group-content holds: kept until their event is terminal, re-classified, or absent from a completed refetch. */
110
+ readonly pins?: Readonly<Record<string, number>>;
111
+ /** `group-busy` holds (unclassified): bounded by {@link MAX_BUSY_PINS}; released like pins. */
112
+ readonly busy?: Readonly<Record<string, number>>;
113
+ /** The unwalked rest of an incomplete history pass's window: `since` stays at or below `from` until a pass completes it. */
114
+ readonly resume?: HistoryResume;
115
+ }
116
+ /** The history window a pass walks next (inclusive; `until` absent = open above) and the tops of the windows above it, ascending. */
117
+ export interface HistoryResume {
118
+ readonly from: number;
119
+ readonly until?: number;
120
+ readonly above?: readonly number[];
121
+ }
122
+ export declare const CURSOR_KEY = "kind445";
123
+ /** Tolerated future skew of an event's `created_at` against the client clock (seconds). */
124
+ export declare const CURSOR_FUTURE_SKEW_S = 300;
125
+ /** `since` sits this far below the cursor's floor so late-stamped events are redelivered; the ledger dedups them (seconds). */
126
+ export declare const CURSOR_REDELIVERY_MARGIN_S = 300;
127
+ /** Ledger entries whose event `created_at` lies this far below the cursor's `since` are pruned (seconds). */
128
+ export declare const LEDGER_RETENTION_S: number;
129
+ /** An undecryptable hold older than this is given up, so junk cannot pin the cursor forever (seconds). Pins are exempt. */
130
+ export declare const HOLD_MAX_AGE_S: number;
131
+ /** At most this many undecryptable holds are kept (eviction policy: see {@link IngestCursor}), bounding the cursor record. Pins are exempt. */
132
+ export declare const MAX_HOLDS = 1000;
133
+ /** At most this many `group-busy` holds are kept (eviction policy: see {@link IngestCursor}), bounding the record during a long blocked confirmation. */
134
+ export declare const MAX_BUSY_PINS = 1000;
135
+ export interface CursorUpdate {
136
+ /** `created_at` of each authenticated, terminally processed event of the batch. */
137
+ readonly advanced: readonly number[];
138
+ /** id → `created_at` of each undecryptable event of the batch (evictable tier). */
139
+ readonly held: ReadonlyMap<string, number>;
140
+ /** id → `created_at` of each group-content event of the batch that still needs redelivery (pinned tier). Disjoint from `held`. */
141
+ readonly pinned: ReadonlyMap<string, number>;
142
+ /** id → `created_at` of each event of the batch dropped unclassified as `group-busy` (busy tier). */
143
+ readonly busy?: ReadonlyMap<string, number>;
144
+ /** Ids now terminal (ledgered, or a ledger hit), given up, or absent from a completed refetch: released from every tier. */
145
+ readonly released: ReadonlySet<string>;
146
+ /** A window → sets the cursor's `resume`; `null` → clears it; absent → keeps it. */
147
+ readonly resume?: HistoryResume | null;
148
+ }
149
+ /**
150
+ * The cursor after one sync batch (see {@link IngestCursor}); `current`
151
+ * itself when nothing moved it. `high` never decreases except through the
152
+ * future-skew clamp; `since` may move backwards when a new hold predates it.
153
+ * A cursor without `high` (nothing authenticated has advanced it yet) keeps
154
+ * its `since` until something does.
155
+ */
156
+ export declare function nextCursor(current: IngestCursor | undefined, update: CursorUpdate, nowSeconds: number): IngestCursor | undefined;
157
+ /** What one history pass covered, for {@link absentPins}. */
158
+ export interface HistoryCoverage {
159
+ /** The pass did not time out and its pagination reached the end on every relay asked (see `fetchHistoryPages`). */
160
+ readonly complete: boolean;
161
+ /** The filter's `since` (`undefined` = unbounded): the lower edge of the covered window. */
162
+ readonly since: number | undefined;
163
+ /** The filter's `until` (`undefined` = open above): the upper edge of the covered window. */
164
+ readonly until?: number | undefined;
165
+ /** Seconds some relay may have truncated (`fetchHistoryPages` gaps): nothing stamped on them is released. */
166
+ readonly gaps?: readonly number[];
167
+ /** Every relay of the group's full relay plane was asked — none was left out as silent (AC-PIPE-14). */
168
+ readonly wholePlane: boolean;
169
+ }
170
+ /**
171
+ * Pins and busy entries of `cursor` that a history pass should have
172
+ * returned but did not — so no relay can still redeliver them, and the
173
+ * entry would otherwise hold the floor forever. An entry is released only
174
+ * when the pass was complete (not `timedOut`, pagination finished — a
175
+ * truncated response proves nothing about what it cut off), covered the
176
+ * entry's `created_at` (within `[since, until]`, each edge open when absent,
177
+ * and not on a gap second a relay may have truncated), and
178
+ * asked the whole relay plane (a relay excluded as silent may still hold
179
+ * it). Anything else releases nothing.
180
+ */
181
+ export declare function absentPins(cursor: IngestCursor | undefined, coverage: HistoryCoverage, returnedIds: ReadonlySet<string>): Set<string>;