@kubun/plugin-p2p 0.10.1 → 0.11.0

package/lib/groups/broadcast.d.ts

@@ -1,11 +1,14 @@
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
+import { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
-import type { CatalogRecord, CircleMemberRecord, CircleRecord } from '@kubun/protocol';
-import type { Catalog, GraphStoreAPI } from '@kubun/store-graph';
+import type { CatalogRecord } from '@kubun/protocol';
+import type { DelegationStoreAPI } from '@kubun/store-delegation';
+import type { GraphStoreAPI } from '@kubun/store-graph';
 import type { Circle, CircleMember, Group, P2PStoreAPI } from '@kubun/store-p2p';
 import { type ForwardingConfig } from '../sync/forwarder.js';
 import type { StoreUnreadableMode } from '../types.js';
 import type { P2PEventEmitter } from './events.js';
+import type { GroupAnchor } from './group-anchor.js';
 export type MutationApplyEntry = {
     mutationJWT: string;
     docID: string;
@@ -14,49 +17,17 @@ export type MutationApplyEntry = {
     modelID: string;
 };
 /**
- * A circle row in a catch-up snapshot. Mirrors the wire form of `circle:create`
- * (matching {@link CircleRecord} field names) plus `removedAtHLC` so tombstoned
- * circles carry their removal HLC. `null` when the circle is active.
+ * Optional signed token over a control operation. Its issuer (`iss`) is the
+ * authenticated author; receivers verify it and authorize that author as a
+ * group admin, dropping the operation when the token is absent or invalid. The
+ * signed payload is the whole message minus this field, so the signature covers
+ * every operation field, not just the author.
  */
-export type CircleSnapshot = CircleRecord & {
-    removedAtHLC: string | null;
-};
-/**
- * A circle-member row in a catch-up snapshot. Mirrors the wire form of
- * `member:add` (matching {@link CircleMemberRecord} field names) plus
- * `removedAtHLC` so tombstoned memberships carry their removal HLC. `null` when
- * the membership is active.
- */
-export type CircleMemberSnapshot = CircleMemberRecord & {
-    removedAtHLC: string | null;
-};
+type ControlAuth = string;
 export type GroupBroadcastMessage = {
-    type: 'circle:create';
-    circle: CircleRecord;
-} | {
-    type: 'circle:update';
-    circleID: string;
-    update: {
-        name?: string;
-        description?: string;
-        catalogIDs?: Array<string>;
-        hlc: string;
-    };
-} | {
-    type: 'circle:delete';
-    circleID: string;
-    hlc: string;
-} | {
-    type: 'member:add';
-    member: CircleMemberRecord;
-} | {
-    type: 'member:remove';
-    circleID: string;
-    memberDID: string;
-    hlc: string;
-} | {
     type: 'catalog:create';
     catalog: CatalogRecord;
+    auth?: ControlAuth;
 } | {
     type: 'catalog:update';
     catalogID: string;
@@ -66,10 +37,12 @@ export type GroupBroadcastMessage = {
         filterCriteria?: CatalogRecord['filterCriteria'];
         hlc: string;
     };
+    auth?: ControlAuth;
 } | {
     type: 'catalog:delete';
     catalogID: string;
     hlc: string;
+    auth?: ControlAuth;
 } | {
     /**
      * Distributes a minted `document/write` capability token to group
@@ -102,13 +75,9 @@ export type GroupBroadcastMessage = {
     /** HLC stamped by the revoker; mirrors the revoker-side stored row. */
     hlc: string;
 } | {
-    type: 'group:update';
+    type: 'ledger:entry';
     groupID: string;
-    update: {
-        name?: string;
-        description?: string;
-        hlc: string;
-    };
+    token: string;
 } | {
     /**
      * A member announces a voluntary leave. MLS forbids self-removal, so this
@@ -128,38 +97,60 @@ export type GroupBroadcastMessage = {
     senderPeerDID: string;
 } | {
     /**
-     * A rejoining peer asks current members for a snapshot of the group's
-     * circle + circle-member rows so it can recover state it missed while
-     * absent. `requestID` correlates the eventual batched reply.
+     * A rejoining peer asks current members for the group's full control
+     * ledger so it can backfill entries it missed while absent. `requestID`
+     * correlates the eventual batched reply.
      */
-    type: 'circle-catchup:request';
+    type: 'ledger-catchup:request';
     requestID: string;
 } | {
     /**
-     * A current member's batched response to a `circle-catchup:request`. One
-     * frame carrying the group's current circle + circle-member rows,
-     * INCLUDING tombstoned entries (each row's `removedAtHLC` distinguishes
-     * active from removed). The requester correlates it via `requestID` and
-     * applies each row through the existing circle/member broadcast handlers.
+     * A member's reply to a `ledger-catchup:request`: the group's control
+     * ledger as an array of signed entry tokens. The responder is UNTRUSTED —
+     * each token self-authenticates, so the requester re-verifies every one
+     * independently and a forged or unsigned token is dropped without
+     * poisoning the rest. Idempotent + order-independent on the token digest.
      */
-    type: 'circle-catchup:reply';
+    type: 'ledger-catchup:reply';
     requestID: string;
-    circles: Array<CircleSnapshot>;
-    circleMembers: Array<CircleMemberSnapshot>;
+    entries: Array<string>;
 };
-export type AffectedRow = {
-    kind: 'circle';
+/** Narrow {@link GroupBroadcastMessage} to the variant(s) carrying the given `type`. */
+export type BroadcastOf<TType extends GroupBroadcastMessage['type']> = Extract<GroupBroadcastMessage, {
+    type: TType;
+}>;
+/**
+ * The local-event descriptor for an applied `ledger:entry`. The ingest arm
+ * captures it after reprojecting, while the store still holds the post-state,
+ * so {@link forwardRemoteBroadcast} can emit the matching local event for a
+ * remote-driven change without re-reading or re-verifying. Each variant carries
+ * the projected row plus the create-vs-change / add-vs-remove discriminators the
+ * ingest derived by comparing the pre-state it read before reprojecting.
+ */
+export type LedgerAffected = {
+    entry: 'circle.def';
+    row: Circle;
+    /** True when an active circle row existed before this entry (changed, not created). */
+    preExisted: boolean;
+    /** True when the entry's catalog set differs from the pre-state's (catalogs changed). */
+    catalogsChanged: boolean;
+} | {
+    entry: 'circle.def.removed';
     row: Circle;
 } | {
-    kind: 'member';
+    entry: 'circle.member';
     row: CircleMember;
 } | {
-    kind: 'catalog';
-    row: Catalog;
+    entry: 'circle.member.removed';
+    row: CircleMember;
 } | {
-    kind: 'group';
+    entry: 'group.settings';
     row: Group;
 };
+export type AffectedRow = {
+    kind: 'ledger';
+    ledger: LedgerAffected;
+};
 export type ProcessBroadcastResult = {
     applied: boolean;
     /**
@@ -187,9 +178,21 @@ export type ProcessBroadcastResult = {
      * (possibly `0`) on `mutation:apply`.
      */
     duplicates?: number;
+    /**
+     * Set to `'unknown-type'` when the message carried a `type` outside the
+     * known discriminated union (version skew). The frame is not applied and is
+     * logged; other branches never set this.
+     */
+    reason?: 'unknown-type';
 };
 export type ProcessBroadcastParams = {
     p2pStore: P2PStoreAPI;
+    /**
+     * Delegation store for received-grant / received-revocation handling. The
+     * delegation token and revocation rows live here (group-agnostic); the p2p
+     * store keeps only the `jti` → group edge.
+     */
+    delegationStore: DelegationStoreAPI;
     graphStore: GraphStoreAPI;
     /**
      * Engine graph internals — required to apply `mutation:apply` entries via
@@ -235,6 +238,21 @@ export type ProcessBroadcastParams = {
      * Absent in tests that don't exercise the subscription path.
      */
     emitter?: P2PEventEmitter;
+    /**
+     * Device-wide monotonic clock. On a newly-appended `ledger:entry` the
+     * receiver merges the entry's HLC into this clock so its own later entries
+     * sort strictly after observed ones. Optional: callers that never receive
+     * ledger entries (and existing tests) omit it and the merge is skipped.
+     */
+    hlc?: HLC;
+    /**
+     * Resolve a group's genesis anchor, or `null` when none is available yet. A
+     * `ledger:entry` is always stored durably, but the admin-role overlay can
+     * only be projected once the authenticated epoch-0 root is known; a `null`
+     * anchor defers projection without dropping the entry. Optional so callers
+     * that never project (and existing tests) can omit it.
+     */
+    getGroupAnchor?: (groupID: string) => Promise<GroupAnchor | null>;
     /** Optional logger — warns on per-entry apply failures. */
     logger?: Logger;
 };
@@ -257,35 +275,31 @@ export type ProcessBroadcastParams = {
  */
 export declare function processBroadcast(params: ProcessBroadcastParams, message: GroupBroadcastMessage, groupID: string): Promise<ProcessBroadcastResult>;
 /**
- * Summary of a batched catch-up apply: how many rows mutated local state.
+ * Summary of a batched ledger catch-up apply.
  */
-export type ApplyCatchupReplyResult = {
-    /** Count of circle rows whose synthesized message mutated local state. */
-    circlesApplied: number;
-    /** Count of member rows whose synthesized message mutated local state. */
-    membersApplied: number;
+export type ApplyLedgerCatchupReplyResult = {
+    /** Count of entries whose verified token was newly appended to the ledger. */
+    applied: number;
+    /** Count of entries dropped because their token failed verification. */
+    rejected: number;
 };
 /**
- * Apply a batched catch-up reply row-by-row through the existing per-row
- * broadcast handlers. Each snapshot row is turned into the single equivalent
- * {@link GroupBroadcastMessage} and fed through {@link processBroadcast}, so all
- * conflict resolution (HLC last-write-wins for circle create/update, the
- * earliest-wins tombstone guards for circle/member removal) is the exact same
- * code the live broadcast path runs. No additional merge logic lives here.
+ * Apply a batched ledger catch-up reply from an UNTRUSTED responder. Each entry
+ * carries its own signed token, so the responder's identity is irrelevant: every
+ * token is verified independently and a forged or unsigned one is dropped without
+ * aborting the batch. Surviving entries are appended idempotently on the token
+ * digest, so a replayed or duplicated reply is a harmless no-op.
  *
- * A tombstoned circle replays a `circle:create` (so a rejoiner that never saw
- * the circle materializes the row) immediately followed by a `circle:delete`
- * stamped with the row's `removedAtHLC`. The delete's earliest-wins guard
- * converges the tombstone; the create is a no-op when a newer local row already
- * exists. An active circle replays a single `circle:create` (the apply path
- * routes create -> update for an existing id). Member rows map symmetrically to
- * `member:add` / `member:remove` — `member:add` materializes the row so the
- * subsequent `member:remove` has a row to tombstone.
+ * A catch-up reply delivers the ledger's history out of order by construction, so
+ * after any new entry lands the projection is rebuilt authoritatively from the
+ * whole ledger (a full reproject) rather than applied incrementally. All four
+ * control projections — admin roster, circle defs, circle members, group
+ * settings — rebuild here, so a circle or settings entry delivered via catch-up
+ * materializes immediately rather than waiting for a later live entry. Projection
+ * is deferred when no genesis anchor is available yet — the entries are still
+ * stored durably.
  *
- * Idempotent and order-independent: re-applying the same batch, or applying its
- * rows in any order, lands the same final state because every synthesized
- * message runs the same LWW / earliest-wins guards.
+ * Never throws out of the per-token loop: one bad token must not abort the batch.
  */
-export declare function applyCatchupReply(params: ProcessBroadcastParams, reply: Extract<GroupBroadcastMessage, {
-    type: 'circle-catchup:reply';
-}>, groupID: string): Promise<ApplyCatchupReplyResult>;
+export declare function applyLedgerCatchupReply(params: ProcessBroadcastParams, reply: BroadcastOf<'ledger-catchup:reply'>, groupID: string): Promise<ApplyLedgerCatchupReplyResult>;
+export {};