@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/circle-reducers.d.ts

@@ -1,22 +1,38 @@
+import type { GroupAnchor } from '@kumiai/mls';
 import { type AdminRoleValue } from './admin-roster.js';
-import type { GroupAnchor } from './group-anchor.js';
-import type { FoldInput, LedgerReducer } from './ledger-fold.js';
+import type { LedgerReducer, PositionedFoldInput } from './ledger.js';
 /**
- * The fold's authority gate: was `issuer` a group admin at `hlc`? The reducer
- * factories take this predicate so the projection fold stays synchronous and
- * deterministic from the ledger alone — every peer that folds the same ledger
- * resolves the same authority and converges to the same state. By design this
- * gate is the LEDGER admin-fold ONLY: membership and MLS-removal are enforced
- * outside the projection (the live broadcast gate and the MLS roster), never
- * conjoined here, so the fold never needs an async store read.
+ * The fold's authority gate: was `issuer` a group admin when the entry at
+ * `position` was enacted?
+ *
+ * The LEDGER admin-fold ONLY — membership and MLS-removal are enforced outside the
+ * projection, never conjoined here, so the fold stays synchronous and every peer
+ * folding the same ledger converges. Applied by {@link authorizedEntries} BEFORE
+ * the fold, not inside a reducer's `verifyAuthority`: that hook sees only the
+ * entry, and the prefix an entry is judged against is a property of its slot.
+ */
+export type IsAdminAtPosition = (issuer: string, position: number) => boolean;
+/**
+ * Drop the entries whose issuer lacked admin authority at their own slot, keeping
+ * the rest in ledger order.
+ *
+ * INCLUSIVE compare against the ledger prefix through the entry's own position: a
+ * grant authorizes from its own slot onward, a demotion stops authorizing from its
+ * own slot onward.
  */
-export type IsAdminAtHLC = (issuer: string, hlc: string) => boolean;
-/** Ledger entry `type` for a circle-membership claim. */
-export declare const CIRCLE_MEMBER_ENTRY_TYPE = "circle.member";
+export declare function authorizedEntries<TValue>(entries: Array<PositionedFoldInput<TValue>>, isAdmin: IsAdminAtPosition): Array<PositionedFoldInput<TValue>>;
+/**
+ * Ledger entry `type` for a circle-membership claim. Every control-ledger type
+ * kubun mints lives under `kubun.*` — that namespace is kubun's, and the split
+ * between "kubun projects this" and "the MLS library interprets this" is drawn
+ * on it. Namespaces the library reserves for itself are its own to name and
+ * rename, so kubun stays out of them and never restates them.
+ */
+export declare const CIRCLE_MEMBER_ENTRY_TYPE = "kubun.circle.member";
 /**
  * The claim carried by a circle-member entry. The active form names the
  * member's role within the circle; the tombstone form removes them. Both are
- * whole-value: the highest-ordered entry for a subject replaces the projected
+ * whole-value: the last entry for a subject in the ledger replaces the projected
  * state outright, so the value alone decides active-with-role vs removed. `role`
  * mirrors the store's free-form role column (no fixed enum), so it stays a
  * string rather than inventing a circle-specific role type.
@@ -44,38 +60,12 @@ export declare function decodeCircleMemberSubject(subject: string): {
     circleID: string;
     memberDID: string;
 } | null;
-/**
- * Folded circle membership, keyed by composite subject. Only active members are
- * present — a subject whose highest-ordered entry is a tombstone is absent from
- * the map.
- */
-export type CircleMemberState = {
-    members: Map<string, {
-        circleID: string;
-        memberDID: string;
-        role: string;
-    }>;
-};
-/**
- * Per-member last-writer-wins circle roster. {@link foldLedger} sorts by the
- * total order `(hlc, entryID)`, so each subject's highest-ordered entry is
- * applied last and decides the outcome: an active value sets the member with its
- * role, a tombstone removes them. Whole-value replacement means add / remove /
- * re-add converge to the same state on every peer regardless of arrival order.
- *
- * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
- * HLC so a key authorized when it wrote stays authorized even after a later
- * revoke. The gate is the ledger admin-fold ONLY — membership and MLS-removal
- * are enforced outside this projection — so the fold remains synchronous and
- * deterministic from the ledger alone.
- */
-export declare function createCircleMemberReducer(isAdminAtHLC: IsAdminAtHLC): LedgerReducer<CircleMemberValue, CircleMemberState>;
 /** Ledger entry `type` for a circle definition (create / update / delete). */
-export declare const CIRCLE_DEF_ENTRY_TYPE = "circle.def";
+export declare const CIRCLE_DEF_ENTRY_TYPE = "kubun.circle.def";
 /**
  * The claim carried by a circle-definition entry. The active form is the whole
  * circle definition; the tombstone form deletes it. Both are whole-value: the
- * highest-ordered entry for a circle replaces the projected definition outright,
+ * last entry for a circle in the ledger replaces the projected definition outright,
  * so create and update share one shape and the value alone decides present vs
  * deleted.
  */
@@ -87,92 +77,63 @@ export type CircleDefValue = {
     removed: true;
 };
 /**
- * Folded circle definitions, keyed by circleID. Only present circles appear — a
- * circle whose highest-ordered entry is a tombstone is absent from the map.
+ * Ledger entry `type` for a group-settings claim. Namespaced under `kubun.*`
+ * like every kubun control-ledger type — a bare `group.settings` sits in the
+ * namespace the MLS library reserves, so a commit carrying it is refused whole.
  */
-export type CircleDefState = {
-    circles: Map<string, {
-        name: string;
-        description: string;
-        catalogIDs: Array<string>;
-    }>;
-};
+export declare const GROUP_SETTINGS_ENTRY_TYPE = "kubun.group.settings";
 /**
- * Per-circle last-writer-wins definition. The signed entry's `subject` is the
- * circleID directly, so no decode is needed. {@link foldLedger} sorts by the
- * total order `(hlc, entryID)`, so each circle's highest-ordered entry is
- * applied last and decides the outcome: an active value sets the definition, a
- * tombstone deletes it. Whole-value replacement means create / update / delete
- * converge to the same state on every peer regardless of arrival order.
+ * The claim carried by a group-settings entry. FIELD-WISE LWW, no tombstone: an
+ * omitted field leaves the prior value untouched, while `''` (or an empty list) is
+ * a REAL value that clears it.
  *
- * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
- * HLC. The gate is the ledger admin-fold ONLY — membership and MLS-removal are
- * enforced outside this projection — so the fold remains synchronous and
- * deterministic from the ledger alone.
- */
-export declare function createCircleDefReducer(isAdminAtHLC: IsAdminAtHLC): LedgerReducer<CircleDefValue, CircleDefState>;
-/** Ledger entry `type` for a group-settings claim. */
-export declare const GROUP_SETTINGS_ENTRY_TYPE = "group.settings";
-/**
- * The claim carried by a group-settings entry. Unlike `circle.def` /
- * `circle.member`, this value is PARTIAL: an entry sets only the fields it
- * carries and stays silent about the rest. A field omitted from the
- * value leaves the prior value untouched; setting a field to `''` is a real
- * value that clears it. There is no tombstone — group settings are never
- * deleted, only overwritten field by field.
+ * `commitHub` is the group's consensus commit-hub designation — the shared hub
+ * identity, NOT a local hub-row id. Folding it as group state is what stops two
+ * devices forking the group by each committing through their own first-bound hub.
  */
 export type GroupSettingsValue = {
     name?: string;
     description?: string;
+    openCircleIDs?: Array<string>;
+    commitHub?: {
+        url: string;
+        serverDID?: string;
+    };
 };
 /** Folded group settings, keyed by groupID (the entry subject). */
 export type GroupSettingsState = {
-    settings: Map<string, {
-        name?: string;
-        description?: string;
-    }>;
+    settings: Map<string, GroupSettingsValue>;
 };
 /**
  * Per-field last-writer-wins group settings. The signed entry's `subject` is the
- * groupID directly, so no decode is needed. {@link foldLedger} sorts by the total
- * order `(hlc, entryID)` and applies low→high, so for each field the
- * highest-ordered entry that SETS that field wins naturally.
+ * groupID directly, so no decode is needed. Replayed in the ledger's own
+ * enactment order, so for each field the LAST entry that SETS that field wins
+ * naturally.
  *
- * This reducer merges per field rather than replacing the whole value the way
- * `circle.def` / `circle.member` do: those project a single cohesive record
- * where add / remove / re-add must converge to one state, so whole-value
- * replacement is correct. Group settings instead accumulate independent fields
- * (`name`, `description`) that different entries touch in isolation, so a
- * name-only update must not clobber a previously-set description. Presence is
- * decided by `value.field !== undefined` rather than `'field' in value`: an
- * explicit `undefined` is treated as "not set" (no change), while `''` is a real
- * value that clears the field.
+ * Merges PER FIELD rather than replacing the whole value the way `circle.def` /
+ * `circle.member` do, because these fields are touched in isolation: a name-only
+ * update must not clobber a previously-set description. Presence is
+ * `value.field !== undefined`, not `'field' in value`, so an explicit `undefined`
+ * means no change while `''` or an empty list CLEARS the field.
  *
- * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
- * HLC. The gate is the ledger admin-fold ONLY — membership and MLS-removal are
- * enforced outside this projection — so the fold remains synchronous and
- * deterministic from the ledger alone.
+ * Unauthorized entries never reach here — see {@link authorizedEntries}.
  */
-export declare function createGroupSettingsReducer(isAdminAtHLC: IsAdminAtHLC): LedgerReducer<GroupSettingsValue, GroupSettingsState>;
+export declare function createGroupSettingsReducer(): LedgerReducer<GroupSettingsValue, GroupSettingsState>;
 /**
- * Build an {@link IsAdminAtHLC} predicate from the group's verified admin-role
- * ledger entries. It re-folds the admin sub-ledger at each queried entry's HLC,
- * so the answer is rotation-aware (was-admin-at-HLC, not is-admin-now): a key
- * granted admin at HLC h authorizes entries at or after h, and a later revoke
- * stops authorizing entries from that point on. `foldAdminRoster`'s `atHLC`
- * compare is inclusive (`entry.hlc <= atHLC`), so an entry at exactly the grant
- * HLC sees the grant and is authorized, and an entry at exactly the revoke HLC
- * sees the revoke and is not.
+ * Build an {@link IsAdminAtPosition} predicate from the group's admin-role ledger
+ * entries. It re-folds the admin sub-ledger through each queried slot, so the
+ * answer is rotation-aware (was-admin-then, not is-admin-now): a key granted
+ * admin at slot n authorizes entries from slot n onward, and a later demotion
+ * stops authorizing from its own slot onward. The compare is inclusive
+ * (`position <= throughPosition`), which matters only for a role entry judging
+ * itself — a circle entry never shares a slot with the grant that authorizes it.
  *
- * Callers load the verified admin entries once (via `loadVerifiedAdminEntries`)
- * and reuse the returned predicate across the circle / def / settings folds.
+ * Callers select the role entries once (via `selectRoleEntries`) and reuse the
+ * returned predicate across the circle / def / settings folds.
  *
- * Authority here is ledger-admin-only: it answers "did the ledger grant this
- * issuer admin at this HLC?" and does NOT check the issuer's MLS membership at
- * that HLC. So an admin who was removed from the MLS group but whose admin role
- * was never revoked on the ledger still has authorizing entries folded in.
- * Closing that requires removal to write a ledger revocation atomically with the
- * MLS-roster delta (the same MLS-commit/roster atomicity work that keeps a
- * removed member's writes from applying); it is deliberately out of scope here.
+ * LEDGER-ADMIN ONLY — it does not check the issuer's MLS membership, so an admin
+ * removed from the MLS group whose admin role was never revoked on the ledger still
+ * has its entries folded in. Closing that needs removal to write a ledger
+ * revocation atomically with the roster delta; out of scope here.
  */
-export declare function adminAuthorityFromEntries(adminEntries: Array<FoldInput<AdminRoleValue>>, anchor: GroupAnchor): IsAdminAtHLC;
+export declare function adminAuthorityFromEntries(adminEntries: Array<PositionedFoldInput<AdminRoleValue>>, anchor: GroupAnchor, groupID: string): IsAdminAtPosition;

package/lib/groups/circle-reducers.js

@@ -1,9 +1,22 @@
 import { normalizeDID } from '@kokuin/token';
 import { foldAdminRoster } from './admin-roster.js';
-/** Ledger entry `type` for a circle-membership claim. */ export const CIRCLE_MEMBER_ENTRY_TYPE = 'circle.member';
-function isRemovedValue(value) {
-    return 'removed' in value && value.removed === true;
+/**
+ * Drop the entries whose issuer lacked admin authority at their own slot, keeping
+ * the rest in ledger order.
+ *
+ * INCLUSIVE compare against the ledger prefix through the entry's own position: a
+ * grant authorizes from its own slot onward, a demotion stops authorizing from its
+ * own slot onward.
+ */ export function authorizedEntries(entries, isAdmin) {
+    return entries.filter(({ verified, position })=>isAdmin(verified.issuer, position));
 }
+/**
+ * Ledger entry `type` for a circle-membership claim. Every control-ledger type
+ * kubun mints lives under `kubun.*` — that namespace is kubun's, and the split
+ * between "kubun projects this" and "the MLS library interprets this" is drawn
+ * on it. Namespaces the library reserves for itself are its own to name and
+ * rename, so kubun stays out of them and never restates them.
+ */ export const CIRCLE_MEMBER_ENTRY_TYPE = 'kubun.circle.member';
 /**
  * Deterministic composite subject for a circle member. The signed entry's
  * `subject` encodes both the circle and the member, so the ledger's `subject`
@@ -38,121 +51,36 @@ const MEMBER_SEPARATOR = '/member:';
         memberDID
     };
 }
+/** Ledger entry `type` for a circle definition (create / update / delete). */ export const CIRCLE_DEF_ENTRY_TYPE = 'kubun.circle.def';
 /**
- * Per-member last-writer-wins circle roster. {@link foldLedger} sorts by the
- * total order `(hlc, entryID)`, so each subject's highest-ordered entry is
- * applied last and decides the outcome: an active value sets the member with its
- * role, a tombstone removes them. Whole-value replacement means add / remove /
- * re-add converge to the same state on every peer regardless of arrival order.
- *
- * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
- * HLC so a key authorized when it wrote stays authorized even after a later
- * revoke. The gate is the ledger admin-fold ONLY — membership and MLS-removal
- * are enforced outside this projection — so the fold remains synchronous and
- * deterministic from the ledger alone.
- */ export function createCircleMemberReducer(isAdminAtHLC) {
-    return {
-        type: CIRCLE_MEMBER_ENTRY_TYPE,
-        seed: ()=>({
-                members: new Map()
-            }),
-        verifyAuthority: (verified)=>isAdminAtHLC(verified.issuer, verified.entry.hlc),
-        apply: (verified, state)=>{
-            const members = new Map(state.members);
-            const { subject, value } = verified.entry;
-            if (isRemovedValue(value)) {
-                members.delete(subject);
-                return {
-                    members
-                };
-            }
-            const decoded = decodeCircleMemberSubject(subject);
-            if (decoded == null) {
-                // Malformed subject: leave the map untouched rather than guess the pair.
-                return state;
-            }
-            members.set(subject, {
-                circleID: decoded.circleID,
-                memberDID: decoded.memberDID,
-                role: value.role
-            });
-            return {
-                members
-            };
-        }
-    };
-}
-/** Ledger entry `type` for a circle definition (create / update / delete). */ export const CIRCLE_DEF_ENTRY_TYPE = 'circle.def';
-function isRemovedDef(value) {
-    return 'removed' in value && value.removed === true;
-}
-/**
- * Per-circle last-writer-wins definition. The signed entry's `subject` is the
- * circleID directly, so no decode is needed. {@link foldLedger} sorts by the
- * total order `(hlc, entryID)`, so each circle's highest-ordered entry is
- * applied last and decides the outcome: an active value sets the definition, a
- * tombstone deletes it. Whole-value replacement means create / update / delete
- * converge to the same state on every peer regardless of arrival order.
- *
- * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
- * HLC. The gate is the ledger admin-fold ONLY — membership and MLS-removal are
- * enforced outside this projection — so the fold remains synchronous and
- * deterministic from the ledger alone.
- */ export function createCircleDefReducer(isAdminAtHLC) {
-    return {
-        type: CIRCLE_DEF_ENTRY_TYPE,
-        seed: ()=>({
-                circles: new Map()
-            }),
-        verifyAuthority: (verified)=>isAdminAtHLC(verified.issuer, verified.entry.hlc),
-        apply: (verified, state)=>{
-            const circles = new Map(state.circles);
-            const { subject, value } = verified.entry;
-            if (isRemovedDef(value)) {
-                circles.delete(subject);
-                return {
-                    circles
-                };
-            }
-            circles.set(subject, {
-                name: value.name,
-                description: value.description,
-                catalogIDs: value.catalogIDs
-            });
-            return {
-                circles
-            };
-        }
-    };
-}
-/** Ledger entry `type` for a group-settings claim. */ export const GROUP_SETTINGS_ENTRY_TYPE = 'group.settings';
+ * Ledger entry `type` for a group-settings claim. Namespaced under `kubun.*`
+ * like every kubun control-ledger type — a bare `group.settings` sits in the
+ * namespace the MLS library reserves, so a commit carrying it is refused whole.
+ */ export const GROUP_SETTINGS_ENTRY_TYPE = 'kubun.group.settings';
 /**
  * Per-field last-writer-wins group settings. The signed entry's `subject` is the
- * groupID directly, so no decode is needed. {@link foldLedger} sorts by the total
- * order `(hlc, entryID)` and applies low→high, so for each field the
- * highest-ordered entry that SETS that field wins naturally.
+ * groupID directly, so no decode is needed. Replayed in the ledger's own
+ * enactment order, so for each field the LAST entry that SETS that field wins
+ * naturally.
  *
- * This reducer merges per field rather than replacing the whole value the way
- * `circle.def` / `circle.member` do: those project a single cohesive record
- * where add / remove / re-add must converge to one state, so whole-value
- * replacement is correct. Group settings instead accumulate independent fields
- * (`name`, `description`) that different entries touch in isolation, so a
- * name-only update must not clobber a previously-set description. Presence is
- * decided by `value.field !== undefined` rather than `'field' in value`: an
- * explicit `undefined` is treated as "not set" (no change), while `''` is a real
- * value that clears the field.
+ * Merges PER FIELD rather than replacing the whole value the way `circle.def` /
+ * `circle.member` do, because these fields are touched in isolation: a name-only
+ * update must not clobber a previously-set description. Presence is
+ * `value.field !== undefined`, not `'field' in value`, so an explicit `undefined`
+ * means no change while `''` or an empty list CLEARS the field.
  *
- * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
- * HLC. The gate is the ledger admin-fold ONLY — membership and MLS-removal are
- * enforced outside this projection — so the fold remains synchronous and
- * deterministic from the ledger alone.
- */ export function createGroupSettingsReducer(isAdminAtHLC) {
+ * Unauthorized entries never reach here — see {@link authorizedEntries}.
+ */ export function createGroupSettingsReducer() {
     return {
         type: GROUP_SETTINGS_ENTRY_TYPE,
         seed: ()=>({
                 settings: new Map()
             }),
-        verifyAuthority: (verified)=>isAdminAtHLC(verified.issuer, verified.entry.hlc),
+        // Every entry reaching this fold has already passed the admin gate in
+        // `authorizedEntries`, which judges an entry against the ledger prefix
+        // through its own slot. That question needs the entry's POSITION, which this
+        // hook is not given, so the gate cannot live here.
+        verifyAuthority: ()=>true,
         apply: (verified, state)=>{
             const settings = new Map(state.settings);
             const { subject, value } = verified.entry;
@@ -166,6 +94,12 @@ function isRemovedDef(value) {
             if (value.description !== undefined) {
                 next.description = value.description;
             }
+            if (value.openCircleIDs !== undefined) {
+                next.openCircleIDs = value.openCircleIDs;
+            }
+            if (value.commitHub !== undefined) {
+                next.commitHub = value.commitHub;
+            }
             settings.set(subject, next);
             return {
                 settings
@@ -174,25 +108,21 @@ function isRemovedDef(value) {
     };
 }
 /**
- * Build an {@link IsAdminAtHLC} predicate from the group's verified admin-role
- * ledger entries. It re-folds the admin sub-ledger at each queried entry's HLC,
- * so the answer is rotation-aware (was-admin-at-HLC, not is-admin-now): a key
- * granted admin at HLC h authorizes entries at or after h, and a later revoke
- * stops authorizing entries from that point on. `foldAdminRoster`'s `atHLC`
- * compare is inclusive (`entry.hlc <= atHLC`), so an entry at exactly the grant
- * HLC sees the grant and is authorized, and an entry at exactly the revoke HLC
- * sees the revoke and is not.
+ * Build an {@link IsAdminAtPosition} predicate from the group's admin-role ledger
+ * entries. It re-folds the admin sub-ledger through each queried slot, so the
+ * answer is rotation-aware (was-admin-then, not is-admin-now): a key granted
+ * admin at slot n authorizes entries from slot n onward, and a later demotion
+ * stops authorizing from its own slot onward. The compare is inclusive
+ * (`position <= throughPosition`), which matters only for a role entry judging
+ * itself — a circle entry never shares a slot with the grant that authorizes it.
  *
- * Callers load the verified admin entries once (via `loadVerifiedAdminEntries`)
- * and reuse the returned predicate across the circle / def / settings folds.
+ * Callers select the role entries once (via `selectRoleEntries`) and reuse the
+ * returned predicate across the circle / def / settings folds.
  *
- * Authority here is ledger-admin-only: it answers "did the ledger grant this
- * issuer admin at this HLC?" and does NOT check the issuer's MLS membership at
- * that HLC. So an admin who was removed from the MLS group but whose admin role
- * was never revoked on the ledger still has authorizing entries folded in.
- * Closing that requires removal to write a ledger revocation atomically with the
- * MLS-roster delta (the same MLS-commit/roster atomicity work that keeps a
- * removed member's writes from applying); it is deliberately out of scope here.
- */ export function adminAuthorityFromEntries(adminEntries, anchor) {
-    return (issuer, hlc)=>foldAdminRoster(adminEntries, anchor, hlc).admins.has(normalizeDID(issuer));
+ * LEDGER-ADMIN ONLY — it does not check the issuer's MLS membership, so an admin
+ * removed from the MLS group whose admin role was never revoked on the ledger still
+ * has its entries folded in. Closing that needs removal to write a ledger
+ * revocation atomically with the roster delta; out of scope here.
+ */ export function adminAuthorityFromEntries(adminEntries, anchor, groupID) {
+    return (issuer, position)=>foldAdminRoster(adminEntries, anchor, groupID, position).admins.has(normalizeDID(issuer));
 }

package/lib/groups/commit-adoption.d.ts

@@ -0,0 +1,77 @@
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { P2PEventEmitter } from './events.js';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+import type { SerializedMLSGroupState } from './mls-state.js';
+export type SerializeCommitJournalBlobParams = {
+    serializedHandle: SerializedMLSGroupState;
+    invitePayload?: string;
+    requestID?: string;
+};
+export declare function serializeCommitJournalBlob(params: SerializeCommitJournalBlobParams): Uint8Array;
+/**
+ * Read just the control request id a commit journalled, if it carried one.
+ *
+ * A lost commit the host re-drives (a `ledger` whose tokens survive) is settled
+ * under the SAME id it was first enacted for, and that id lives only in the
+ * blob. This exposes it without re-implementing the codec: the deserialize stays
+ * one function, so the blob shape and its `reviver` are read the same way on
+ * every path. An absent id returns `undefined` — never a placeholder, which
+ * would flow as a real request and settle an unrelated row.
+ */
+export declare function readJournalRequestID(blob: Uint8Array): string | undefined;
+export type AdoptCommitJournalBlobDeps = {
+    registry: GroupHandleRegistry;
+    groupID: string;
+    stores: StoreProvider;
+    /**
+     * Announces the settle this adopt performs. Optional — without it the request
+     * still settles durably, only silently, so a caller reading the row back
+     * still sees the outcome.
+     */
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * Adopt a journalled commit now confirmed accepted: restore its post-commit
+ * handle, swap it into the registry (persisting the advance), and settle the
+ * request it enacted with whatever artifact it produced.
+ *
+ * An invite's payload is PERSISTED here, never sent. A Welcome reaches its
+ * invitee out of band, and by the time a replay runs the caller that would have
+ * carried it there is gone — so the only thing this path can do, and the only
+ * thing it needs to do, is put the payload where that caller's app can still
+ * fetch it by request id.
+ *
+ * Idempotent, as the journal contract requires — a crash between recording
+ * acceptance and clearing the slot replays this. Restoring the serialized handle
+ * is a fixed value, `replaceHandle` installs the same advanced state again, and
+ * a repeated settle rewrites the same terminal row.
+ */
+export declare function adoptCommitJournalBlob(blob: Uint8Array, deps: AdoptCommitJournalBlobDeps): Promise<void>;
+export type SettleLostControlRequestDeps = {
+    stores: StoreProvider;
+    /**
+     * Announces the settle. Optional — without it the request still settles
+     * durably, only silently, so a caller reading the row back still sees the
+     * outcome.
+     */
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * Settle the control request a lost commit was enacting as `lost`.
+ *
+ * The mirror image of {@link adoptCommitJournalBlob}: it reads the same blob a
+ * pending commit journalled, but a lost commit NEVER landed, so — unlike the
+ * accepted path — nothing here restores or advances the handle. The only thing
+ * recovered is the request the commit was for, so the caller holding its id
+ * learns the action did not happen. For a remove that notice is the admin's
+ * sole signal that an eviction they believe took effect did not.
+ *
+ * A blob with no request id settles NOTHING: an absent id means no request rode
+ * this commit, and settling a placeholder id would flow as a real request and
+ * mark an unrelated row lost. Idempotent like the adopt path — a repeated
+ * settle rewrites the same terminal row.
+ */
+export declare function settleLostControlRequest(blob: Uint8Array, deps: SettleLostControlRequestDeps): Promise<void>;

package/lib/groups/commit-adoption.js

@@ -0,0 +1,108 @@
+import { settleControlRequest } from './control-request.js';
+import { restoreMLSGroupHandle } from './mls-group-handle.js';
+import { replacer, reviver } from './mls-json.js';
+export function serializeCommitJournalBlob(params) {
+    const blob = {
+        serializedHandle: params.serializedHandle,
+        ...params.invitePayload != null ? {
+            invitePayload: params.invitePayload
+        } : {},
+        ...params.requestID != null ? {
+            requestID: params.requestID
+        } : {}
+    };
+    return new TextEncoder().encode(JSON.stringify(blob, replacer));
+}
+function deserializeCommitJournalBlob(blob) {
+    const json = new TextDecoder().decode(blob);
+    return JSON.parse(json, reviver);
+}
+/**
+ * Read just the control request id a commit journalled, if it carried one.
+ *
+ * A lost commit the host re-drives (a `ledger` whose tokens survive) is settled
+ * under the SAME id it was first enacted for, and that id lives only in the
+ * blob. This exposes it without re-implementing the codec: the deserialize stays
+ * one function, so the blob shape and its `reviver` are read the same way on
+ * every path. An absent id returns `undefined` — never a placeholder, which
+ * would flow as a real request and settle an unrelated row.
+ */ export function readJournalRequestID(blob) {
+    return deserializeCommitJournalBlob(blob).requestID;
+}
+/**
+ * Adopt a journalled commit now confirmed accepted: restore its post-commit
+ * handle, swap it into the registry (persisting the advance), and settle the
+ * request it enacted with whatever artifact it produced.
+ *
+ * An invite's payload is PERSISTED here, never sent. A Welcome reaches its
+ * invitee out of band, and by the time a replay runs the caller that would have
+ * carried it there is gone — so the only thing this path can do, and the only
+ * thing it needs to do, is put the payload where that caller's app can still
+ * fetch it by request id.
+ *
+ * Idempotent, as the journal contract requires — a crash between recording
+ * acceptance and clearing the slot replays this. Restoring the serialized handle
+ * is a fixed value, `replaceHandle` installs the same advanced state again, and
+ * a repeated settle rewrites the same terminal row.
+ */ export async function adoptCommitJournalBlob(blob, deps) {
+    const { serializedHandle, invitePayload, requestID } = deserializeCommitJournalBlob(blob);
+    const handle = await restoreMLSGroupHandle({
+        serialized: serializedHandle
+    });
+    await deps.registry.replaceHandle(deps.groupID, handle, {
+        stores: deps.stores
+    });
+    // Settling here is what closes the loop for a request whose process died
+    // between publishing the commit and adopting it: the commit landed, so its
+    // request landed with it, and the app learns the outcome under the id it has
+    // been holding since before the restart. Idempotent like the rest of this
+    // function — a repeated adopt rewrites the same terminal row.
+    if (requestID != null) {
+        await settleControlRequest({
+            stores: deps.stores,
+            requestID,
+            outcome: 'committed',
+            ...invitePayload != null ? {
+                result: invitePayload
+            } : {},
+            ...deps.emitter != null ? {
+                emitter: deps.emitter
+            } : {},
+            ...deps.logger != null ? {
+                logger: deps.logger
+            } : {}
+        });
+    }
+}
+/**
+ * Settle the control request a lost commit was enacting as `lost`.
+ *
+ * The mirror image of {@link adoptCommitJournalBlob}: it reads the same blob a
+ * pending commit journalled, but a lost commit NEVER landed, so — unlike the
+ * accepted path — nothing here restores or advances the handle. The only thing
+ * recovered is the request the commit was for, so the caller holding its id
+ * learns the action did not happen. For a remove that notice is the admin's
+ * sole signal that an eviction they believe took effect did not.
+ *
+ * A blob with no request id settles NOTHING: an absent id means no request rode
+ * this commit, and settling a placeholder id would flow as a real request and
+ * mark an unrelated row lost. Idempotent like the adopt path — a repeated
+ * settle rewrites the same terminal row.
+ */ export async function settleLostControlRequest(blob, deps) {
+    const { requestID } = deserializeCommitJournalBlob(blob);
+    if (requestID == null) {
+        deps.logger?.debug('lost commit carried no control request to settle');
+        return;
+    }
+    await settleControlRequest({
+        stores: deps.stores,
+        requestID,
+        outcome: 'lost',
+        ...deps.emitter != null ? {
+            emitter: deps.emitter
+        } : {},
+        ...deps.logger != null ? {
+            logger: deps.logger
+        } : {}
+    });
+}