@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/manager.d.ts

@@ -1,12 +1,21 @@
 import { type Identity, type OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import { HLC } from '@kubun/hlc';
+import type { Logger } from '@kubun/logger';
 import { type GroupPermission, type Invite, type KeyPackageBundle } from '@kumiai/mls';
+import type { PendingCommit } from '@kumiai/rpc';
+import type { Runtime } from '@sozai/runtime';
+import type { P2PEventEmitter } from './events.js';
 import type { GroupHandleRegistry } from './group-handle-registry.js';
 import type { SuggestedHub } from './invite-payload.js';
 export type GroupManagerParams = {
     identity: Identity;
-    getRandomID: () => string;
+    /**
+     * Host runtime, propagated rather than constructed here: this package runs on
+     * React Native and in the browser as well as on node, so the environment's
+     * own primitives (id generation, randomness) must come from the caller.
+     */
+    runtime: Runtime;
     /**
      * Single canonical access point for the device's MLS `GroupHandle` instances.
      * Required: all member ops + createGroup/joinGroup route MLS state through
@@ -21,6 +30,21 @@ export type GroupManagerParams = {
      * timestamps (the second would silently lose under last-writer-wins).
      */
     hlc: HLC;
+    /**
+     * Device-wide store coordinator for work that runs DECOUPLED from any request
+     * transaction — a commit's `onAccepted` fires on the lane, long after the
+     * resolver that started it committed, so it must observe durable state and
+     * open its own short transaction. Optional: without it a device's own
+     * committed entries are not folded locally (the projections still heal from a
+     * reproject or catch-up).
+     */
+    stores?: StoreProvider;
+    /**
+     * Emitter for the domain events a device's own committed control entries
+     * drive — the same events a broadcast-delivered entry fires.
+     */
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
 };
 export type CreateGroupParams = {
     stores: StoreProvider;
@@ -43,6 +67,13 @@ export type InviteToGroupParams = {
 };
 export type InviteToGroupResult = {
     invite: Invite;
+    /**
+     * The signed ledger tokens this invite ADDS to the group's ledger (the
+     * invitee's role entry). Already persisted locally, and the bodies the
+     * add-commit's envelope names by content id alone: they ride that commit's own
+     * frame, which is where every other member resolves them.
+     */
+    addedTokens: Array<string>;
     /** Framed MLSMessage(Welcome) bytes for the invitee (`@kumiai/mls`). */
     welcomeMessage: Uint8Array;
     /** Framed MLSMessage(Commit) bytes to fan out to existing members. */
@@ -68,30 +99,103 @@ export type JoinGroupParams = {
     ratchetTree: unknown;
 };
 export type JoinGroupResult = undefined;
-export type RemoveMemberParams = {
-    stores: StoreProvider;
+export type BuildEnactLedgerCommitParams = {
     groupID: string;
-    leafIndex: number;
-    memberDID: string;
+    /** Signed control-ledger tokens this commit enacts, in enactment order. */
+    tokens: Array<string>;
+    /**
+     * The queued control request this commit enacts, settled `committed` the
+     * moment the commit lands. Optional: a commit driven with no request behind
+     * it (a test, or an internal re-enact) settles nothing.
+     */
+    requestID?: string;
 };
-export type RemoveMemberResult = {
-    commitMessage: Uint8Array;
+/**
+ * The raw MLS output of ONE invite attempt, handed to the caller's encoder.
+ *
+ * Everything a joiner needs beyond this — the group's name, its suggested hubs,
+ * the control-state seeds — lives in the context layer, which is why the encoder
+ * is injected rather than implemented here.
+ */
+export type InviteMaterial = {
+    invite: Invite;
+    /** Framed MLSMessage(Welcome) bytes for the invitee (`@kumiai/mls`). */
+    welcomeMessage: Uint8Array;
+    /**
+     * Ratchet tree from the post-commit handle. Typed `unknown` to match
+     * `@kumiai/mls`'s `ProcessWelcomeParams.ratchetTree`, which is opaque on that
+     * side too.
+     */
+    ratchetTree: unknown;
 };
-export type RemoveGroupMemberParams = {
-    stores: StoreProvider;
+/**
+ * The invite artifact of the attempt the group ACCEPTED, and only that one.
+ *
+ * A build closure runs once per rebase attempt and every losing attempt is
+ * discarded whole, so each attempt mints its own invite, Welcome and ratchet
+ * tree against the epoch it framed at — and therefore its own encoded payload.
+ * Handing the payload back through a callback fired inside `onAccepted` is what
+ * keeps a discarded attempt's from reaching a caller: `onAccepted` runs for the
+ * accepted attempt and no other, so a losing attempt's payload never surfaces.
+ * Firing the same callback from the build closure would surface every attempt's.
+ */
+export type AcceptedInvite = {
+    /** The encoded invite payload the caller's encoder built for this attempt. */
+    invitePayload: string;
+    /**
+     * The signed ledger tokens this invite ADDS to the group's ledger (the
+     * invitee's role entry). Already persisted locally, and the bodies the
+     * add-commit's envelope names by content id alone: they ride that commit's own
+     * frame, which is where every other member resolves them.
+     */
+    addedTokens: Array<string>;
+};
+export type BuildInviteCommitParams = {
+    groupID: string;
+    identity: OwnIdentity;
+    recipientDID: string;
+    recipientKeyPackage: KeyPackageBundle['publicPackage'];
+    permission: GroupPermission;
+    /**
+     * The queued control request this commit enacts, settled `committed` the
+     * moment the commit lands. Optional: a commit driven with no request behind it
+     * settles nothing.
+     */
+    requestID?: string;
+    /**
+     * Encode one attempt's material into the self-contained payload a joiner acts
+     * on. Injected because the fields it has to fold in — the group's name, its
+     * hubs, the control-state seeds — belong to the context layer, not here.
+     *
+     * Runs INSIDE the build closure, once per attempt, so the resulting bytes can
+     * ride the journal blob before the commit is published. That is what makes a
+     * crashed-and-replayed commit able to hand the payload back at all; a payload
+     * built after the drive would not exist on the replay path.
+     */
+    encodeInvitePayload: (material: InviteMaterial) => Promise<string>;
+    /**
+     * Receives the accepted attempt's payload once the commit has landed and this
+     * device's own rows are written. Never called for a losing attempt.
+     */
+    onInvited?: (accepted: AcceptedInvite) => Promise<void>;
+};
+export type BuildRemoveCommitParams = {
     groupID: string;
     memberDID: string;
     /**
-     * The HLC stamped by the caller for the roster tombstone. Lifted out of this
-     * method so the producer can stamp ONE HLC that orders both the MLS-roster
-     * tombstone here and the admin-role revocation it appends in the same
-     * transaction — the two must share a timestamp for the fold to drop exactly
-     * the ex-admin's later control entries.
+     * Signed control-ledger tokens this removal enacts. Removing an admin means
+     * riding their demotion entry on the same commit: a receiver refuses a Remove
+     * whose target is still an admin in the roster the commit folds to.
+     */
+    ledgerEntries?: Array<string>;
+    /**
+     * The HLC stamped by the caller for the roster tombstone, so one timestamp
+     * orders both the MLS-roster tombstone and the admin-role revocation riding
+     * the same commit — the fold drops exactly the ex-admin's later entries only
+     * when the two share a position.
      */
     hlc: string;
-};
-export type RemoveGroupMemberResult = {
-    commitMessage: Uint8Array;
+    requestID?: string;
 };
 export type LeaveGroupParams = {
     stores: StoreProvider;
@@ -111,10 +215,89 @@ export declare class GroupManager {
     #private;
     constructor(params: GroupManagerParams);
     createGroup(params: CreateGroupParams): Promise<CreateGroupResult>;
+    /**
+     * Add a member by committing directly against the local handle. TEST-ONLY.
+     *
+     * Production invites ride the commit lane: the Add is published to the commit
+     * hub's log under the head CAS, and the local epoch advances only once the hub
+     * accepts. This does neither — it advances and persists the epoch outright —
+     * so calling it on a hub-backed group forks that group, and the fork presents
+     * as a hang rather than an error. `git log -S "groupManager.inviteToGroup"`
+     * shows the last production caller removed by `2e901689`, when the invite
+     * moved onto the lane; `addGroupMember` was deleted rather than renamed for
+     * the same reason. Kept for the ~40 suites that drive a hubless group
+     * directly, and unreachable from outside this package: {@link GroupManager} is
+     * not exported from the plugin's entry point.
+     */
     inviteToGroup(params: InviteToGroupParams): Promise<InviteToGroupResult>;
     joinGroup(params: JoinGroupParams): Promise<JoinGroupResult>;
-    removeMember(params: RemoveMemberParams): Promise<RemoveMemberResult>;
-    removeGroupMember(params: RemoveGroupMemberParams): Promise<RemoveGroupMemberResult>;
+    /**
+     * The admin write path for the control ledger: build a commit carrying no
+     * membership change, only the entries it enacts and the head move covering them.
+     * A role entry that never rides a commit is invisible to every other peer's
+     * roster and to the ledger head.
+     *
+     * BUILD IS SPLIT FROM DRIVE, and every `build*Commit` here shares the contract:
+     * the returned closure is re-run per lane attempt, reads the group's CURRENT
+     * handle and derives a fresh commit against it without advancing the live one,
+     * so a rebase after a lost compare-and-set frames at the up-to-date epoch.
+     * Nothing is adopted, written or handed out before `onAccepted` — adopting
+     * earlier seals the bodies under an epoch no receiver holds — so a losing
+     * attempt is discarded whole.
+     */
+    buildEnactLedgerCommit(params: BuildEnactLedgerCommitParams): () => Promise<PendingCommit>;
+    /**
+     * The admin membership-add path for the commit lane: build an Add commit
+     * carrying the invitee's key package plus the role entry the invite mints, and
+     * the head move covering it. Same build-vs-drive contract as
+     * {@link buildEnactLedgerCommit}.
+     *
+     * `kind` is `'invite'` because a host cannot re-issue this commit after a crash:
+     * the intent lives in the Add proposal and the KeyPackage, neither of which
+     * survives the process.
+     */
+    buildInviteCommit(params: BuildInviteCommitParams): () => Promise<PendingCommit>;
+    /**
+     * The admin membership-removal path for the commit lane: build a Remove commit
+     * evicting a member, carrying any demotion entry the removal must enact and the
+     * head move covering it. Same build-vs-drive contract as
+     * {@link buildEnactLedgerCommit}; the leaf index is resolved per attempt so a
+     * rebase cannot evict the leaf a superseded roster held.
+     *
+     * An admin's demotion must ride this very commit — that is what `ledgerEntries`
+     * is for, enforced by {@link assertRemovalDemotes} so a caller that forgets it
+     * fails here rather than shipping a commit the group silently drops.
+     *
+     * `kind` is `'remove'` because a host cannot re-issue this commit after a crash:
+     * the intent lives in the MLS Remove proposal, which does not survive the
+     * process.
+     */
+    buildRemoveCommit(params: BuildRemoveCommitParams): () => Promise<PendingCommit>;
+    /**
+     * Record locally that this device has left, without touching MLS.
+     *
+     * Split from the teardown because the two want opposite timing. What the
+     * device says about ITSELF has to be true the moment `leaveGroup` returns — a
+     * screen that navigates away must not still be told it belongs to the group —
+     * while the departure announcement must reach co-members BEFORE the key it is
+     * encrypted under is deleted, and publishing cannot be awaited inside the
+     * caller's write transaction.
+     *
+     * The group row is kept and marked instead of deleted: its circles, circle
+     * members, peer announcements and hub bindings hang off it, and a device
+     * invited back would otherwise have to rebuild state it still holds.
+     */
+    markGroupLeft(params: LeaveGroupParams): Promise<void>;
+    /**
+     * Drop this device's MLS state for a group, and nothing else.
+     *
+     * The other half of {@link GroupManager.markGroupLeft}: it must run AFTER the
+     * departure announcement, because that announcement is encrypted under the key
+     * this deletes. Separate from the row writes so the caller can commit those
+     * with its own transaction and leave only this for afterwards — repeating the
+     * writes out here would have them block on a connection the caller still holds.
+     */
+    tearDownGroupMLS(stores: StoreProvider, groupID: string): Promise<void>;
     leaveGroup(params: LeaveGroupParams): Promise<LeaveGroupResult>;
     loadGroup(stores: StoreProvider, groupID: string): Promise<{
         epoch: number;