@kubun/plugin-p2p 0.11.0 → 0.12.1

package/lib/groups/ledger-ingest.d.ts

@@ -0,0 +1,124 @@
+import { HLC } from '@kubun/hlc';
+import type { Logger } from '@kubun/logger';
+import type { Circle, CircleMember, Group, P2PStoreAPI } from '@kubun/store-p2p';
+import type { GroupAnchor, LedgerLogEntry } from '@kumiai/mls';
+import { type VerifiedLedgerEntry } from './ledger.js';
+/**
+ * The local-event descriptor for an applied control-ledger entry. The ingest
+ * captures it after reprojecting, while the store still holds the post-state, so
+ * a caller can emit the matching local event for the 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;
+} | {
+    entry: 'circle.member';
+    row: CircleMember;
+} | {
+    entry: 'circle.member.removed';
+    row: CircleMember;
+} | {
+    entry: 'group.settings';
+    row: Group;
+};
+export type AffectedRow = {
+    kind: 'ledger';
+    ledger: LedgerAffected;
+};
+/**
+ * Whether a group is governed by a genesis anchor. The control gate must treat
+ * three cases differently:
+ *  - `anchored`: the MLS state was read and carries a genesis anchor → ledger authority.
+ *  - `unanchored`: the MLS state was read and carries no anchor (a group created
+ *    before the anchor, or external) → legacy role-column authority.
+ *  - `unknown`: the anchor could not be read at all (e.g. the handle was evicted,
+ *    or a teardown race) → fail closed. We must NOT fall back to the role-column
+ *    gate here: an anchored group whose anchor we momentarily can't read would
+ *    otherwise be authorized by its forgeable `role` column — exactly the
+ *    cross-peer bypass the ledger closes.
+ */
+type AnchorResolution = {
+    status: 'anchored';
+    anchor: GroupAnchor;
+    ledger: ReadonlyArray<LedgerLogEntry>;
+} | {
+    status: 'unanchored';
+} | {
+    status: 'unknown';
+};
+/** Inputs the ledger ingest needs — a strict subset of the receive params. */
+export type LedgerIngestParams = {
+    p2pStore: P2PStoreAPI;
+    /**
+     * Device-wide monotonic clock. On a newly-appended 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. An
+     * entry is always stored durably, but the projections can only be built once
+     * the authenticated epoch-0 root is known; a `null` anchor defers projection
+     * without dropping the entry.
+     */
+    getGroupAnchor?: (groupID: string) => Promise<GroupAnchor | null>;
+    /**
+     * Read the group's control ledger — the handle's own log, in enactment order.
+     * Every projection folds from it, so a group whose ledger cannot be read is
+     * not projectable and the entry's projection defers (it stays durable).
+     *
+     * A resolver rather than an array because the receive path is handed a group
+     * id, not a handle. Callers that already hold one under the registry's mutex
+     * pass a closure over it rather than re-acquiring the lock.
+     */
+    getGroupLedger?: (groupID: string) => Promise<ReadonlyArray<LedgerLogEntry>>;
+    /** Optional logger — warns on per-entry apply failures. */
+    logger?: Logger;
+};
+/**
+ * Resolve a group's anchor without ever throwing into the receive loop. A
+ * missing `getGroupAnchor` (callers that never project) is treated as
+ * `unanchored`; a read that throws is `unknown` (fail closed), distinct from a
+ * read that succeeds with no anchor (`unanchored`).
+ */
+export declare function resolveGroupAnchor(params: {
+    getGroupAnchor?: (groupID: string) => Promise<GroupAnchor | null>;
+    getGroupLedger?: (groupID: string) => Promise<ReadonlyArray<LedgerLogEntry>>;
+}, groupID: string): Promise<AnchorResolution>;
+/** The outcome of folding one verified entry into the projections. */
+export type LedgerIngestResult = {
+    /**
+     * True when the entry was folded. Always true today — the entry is already in
+     * the handle's ledger by the time this runs, and this step only projects.
+     * Kept so a caller that folds a batch can still report a count.
+     */
+    applied: boolean;
+    /** The projected row + discriminators, when this entry moved a projection. */
+    ledger?: LedgerAffected;
+};
+/**
+ * Fold ONE control-ledger entry a commit enacted into the projections that read
+ * it, and merge its clock.
+ *
+ * The entry itself needs no storing: it is already in the handle's ledger, put
+ * there by the commit that enacted it, and every projection folds from there.
+ * What is left is the device-local consequence — the observed HLC, the
+ * materialized rows, and the descriptor the caller announces from.
+ *
+ * The caller owns authentication. An entry a commit surfaced was already
+ * notarized by the handle that accepted the commit, so it is not re-verified
+ * here; this function trusts `verified` and never re-checks the signature.
+ */
+export declare function ingestVerifiedLedgerEntry(params: LedgerIngestParams, verified: VerifiedLedgerEntry, groupID: string): Promise<LedgerIngestResult>;
+export {};

package/lib/groups/ledger-ingest.js

@@ -0,0 +1,212 @@
+import { HLC } from '@kubun/hlc';
+import { ADMIN_ROLE_ENTRY_TYPE } from './admin-roster.js';
+import { reprojectCircleDefs, reprojectCircleMembers, reprojectGroupSettings } from './circle-projection.js';
+import { CIRCLE_DEF_ENTRY_TYPE, CIRCLE_MEMBER_ENTRY_TYPE, decodeCircleMemberSubject, GROUP_SETTINGS_ENTRY_TYPE } from './circle-reducers.js';
+import { entryOrd } from './ledger.js';
+/**
+ * Resolve a group's anchor without ever throwing into the receive loop. A
+ * missing `getGroupAnchor` (callers that never project) is treated as
+ * `unanchored`; a read that throws is `unknown` (fail closed), distinct from a
+ * read that succeeds with no anchor (`unanchored`).
+ */ export async function resolveGroupAnchor(params, groupID) {
+    if (params.getGroupAnchor == null) {
+        return {
+            status: 'unanchored'
+        };
+    }
+    let anchor;
+    try {
+        anchor = await params.getGroupAnchor(groupID);
+    } catch  {
+        return {
+            status: 'unknown'
+        };
+    }
+    if (anchor == null) {
+        return {
+            status: 'unanchored'
+        };
+    }
+    // The ledger is resolved with the anchor, not beside it: both are read off the
+    // same handle, and every projection needs both. Resolving them together is what
+    // makes an unreadable ledger indistinguishable from an unreadable anchor —
+    // `unknown`, fail closed — instead of projecting an empty fold over real rows.
+    if (params.getGroupLedger == null) {
+        return {
+            status: 'unknown'
+        };
+    }
+    try {
+        return {
+            status: 'anchored',
+            anchor,
+            ledger: await params.getGroupLedger(groupID)
+        };
+    } catch  {
+        return {
+            status: 'unknown'
+        };
+    }
+}
+/**
+ * Fold ONE control-ledger entry a commit enacted into the projections that read
+ * it, and merge its clock.
+ *
+ * The entry itself needs no storing: it is already in the handle's ledger, put
+ * there by the commit that enacted it, and every projection folds from there.
+ * What is left is the device-local consequence — the observed HLC, the
+ * materialized rows, and the descriptor the caller announces from.
+ *
+ * The caller owns authentication. An entry a commit surfaced was already
+ * notarized by the handle that accepted the commit, so it is not re-verified
+ * here; this function trusts `verified` and never re-checks the signature.
+ */ export async function ingestVerifiedLedgerEntry(params, verified, groupID) {
+    const { p2pStore } = params;
+    // An entry `@kumiai/mls` minted itself — the invitee's role entry, signed
+    // inside `createInvite` — carries no `ord`, so there is no clock to merge.
+    const ord = entryOrd(verified.entry);
+    if (params.hlc != null && ord != null) {
+        try {
+            params.hlc.receive(HLC.parse(ord));
+        } catch (error) {
+            params.logger?.warn('ledger entry HLC merge failed', {
+                groupID,
+                hlc: ord,
+                error
+            });
+        }
+    }
+    // The overlay can only be projected once the authenticated epoch-0 root is
+    // known. Defer projection when there is no anchor or it can't be read right
+    // now — the entry is safe in the handle's ledger either way, and a later entry
+    // or a reproject heals the overlay.
+    const resolution = await resolveGroupAnchor(params, groupID);
+    if (resolution.status !== 'anchored') {
+        params.logger?.debug('ledger entry role projection deferred', {
+            groupID,
+            type: verified.entry.type,
+            reason: resolution.status === 'unknown' ? 'anchor unavailable' : 'no genesis anchor'
+        });
+        return {
+            applied: true
+        };
+    }
+    const { anchor, ledger } = resolution;
+    // Local-event descriptor for this applied entry — populated by the projected
+    // control branches below so a caller can emit the same local event a producer
+    // fires. The pre-state each branch reads BEFORE reprojecting decides
+    // create-vs-change / add-vs-remove; the post-state is the projected row the
+    // event carries.
+    let ledgerAffected;
+    // Route by entry type to the matching projection, each of which reprojects the
+    // whole ledger unconditionally. An entry is judged against the ledger prefix
+    // through its own slot, so a full fold reaches the same answer an incremental
+    // one would and there is no cached-projection-is-stale case to detect — the
+    // watermark and incremental appliers this once needed are gone. An unprojected
+    // type falls through; the durable append above is the whole of its effect.
+    switch(verified.entry.type){
+        case ADMIN_ROLE_ENTRY_TYPE:
+            {
+                break;
+            }
+        case CIRCLE_DEF_ENTRY_TYPE:
+            {
+                const defEntry = verified;
+                // Pre-state (including a tombstoned row) read before reprojecting: an
+                // active row before this entry means the circle existed (a change, not a
+                // create); its `catalog_ids` is the baseline for catalogs-changed.
+                const before = await p2pStore.getCircle(defEntry.entry.subject, {
+                    includeRemoved: true
+                });
+                const preActive = before != null && before.removed_at_hlc == null;
+                await reprojectCircleDefs({
+                    store: p2pStore,
+                    groupID,
+                    anchor,
+                    ledger,
+                    logger: params.logger
+                });
+                // Post-state decides which local event to emit. A now-tombstoned row maps
+                // to a delete; an active row maps to create (no active pre-state) or
+                // change (active pre-state). A null post-state (a non-admin entry the
+                // projection dropped, or a tombstone with no prior row) emits nothing.
+                const after = await p2pStore.getCircle(defEntry.entry.subject, {
+                    includeRemoved: true
+                });
+                if (after != null) {
+                    if (after.removed_at_hlc != null) {
+                        ledgerAffected = {
+                            entry: 'circle.def.removed',
+                            row: after
+                        };
+                    } else {
+                        const catalogsChanged = preActive && before != null && JSON.stringify(before.catalog_ids) !== JSON.stringify(after.catalog_ids);
+                        ledgerAffected = {
+                            entry: 'circle.def',
+                            row: after,
+                            preExisted: preActive,
+                            catalogsChanged
+                        };
+                    }
+                }
+                break;
+            }
+        case CIRCLE_MEMBER_ENTRY_TYPE:
+            {
+                const memberEntry = verified;
+                const decoded = decodeCircleMemberSubject(memberEntry.entry.subject);
+                await reprojectCircleMembers({
+                    store: p2pStore,
+                    groupID,
+                    anchor,
+                    ledger,
+                    logger: params.logger
+                });
+                // Post-state decides the local event: a now-tombstoned row maps to a
+                // remove, an active row to an add (an add and a role-change both map to
+                // `circleMemberAdded` — there is no distinct role-change event). A null
+                // post-state (a malformed subject, a non-admin entry the projection
+                // dropped, or a tombstone with no prior row) emits nothing.
+                if (decoded != null) {
+                    const after = await p2pStore.getCircleMember(decoded.circleID, decoded.memberDID);
+                    if (after != null) {
+                        ledgerAffected = after.removed_at_hlc != null ? {
+                            entry: 'circle.member.removed',
+                            row: after
+                        } : {
+                            entry: 'circle.member',
+                            row: after
+                        };
+                    }
+                }
+                break;
+            }
+        case GROUP_SETTINGS_ENTRY_TYPE:
+            {
+                await reprojectGroupSettings({
+                    store: p2pStore,
+                    groupID,
+                    anchor,
+                    ledger,
+                    logger: params.logger
+                });
+                // Group settings are partial-merge with no tombstone and no
+                // create-vs-change distinction — the producer always emits
+                // `groupDataChanged` — so the post-state group row alone is the event.
+                const after = await p2pStore.getGroup(groupID);
+                if (after != null) {
+                    ledgerAffected = {
+                        entry: 'group.settings',
+                        row: after
+                    };
+                }
+                break;
+            }
+    }
+    return ledgerAffected != null ? {
+        applied: true,
+        ledger: ledgerAffected
+    } : {
+        applied: true
+    };
+}

package/lib/groups/ledger.d.ts

@@ -0,0 +1,44 @@
+import { type FoldDrop, type FoldInput, type GroupAnchor, type LedgerReducer } from '@kumiai/mls';
+export { type FoldDrop, type FoldInput, type LedgerEntry, type LedgerReducer, ledgerEntryDigest, signLedgerEntry, type VerifiedLedgerEntry, verifyLedgerEntry, } from '@kumiai/mls';
+/**
+ * A fold input paired with the slot it occupies in the group's control ledger.
+ *
+ * The position, not the entry, is the identity that matters for ordering. The
+ * handle's log records what each commit ENACTED rather than a set of claims, so
+ * it can hold the same token twice — a repeat is the only way to express a
+ * demotion back to a previously-held role — and two such entries share both
+ * their `ord` and their content-addressed `entryID`. Nothing derived from the
+ * entry can tell those two apart; only the slot can.
+ */
+export type PositionedFoldInput<TValue> = FoldInput<TValue> & {
+    /** Index in the handle's ledger, in enactment order. */
+    position: number;
+};
+/**
+ * The HLC kubun signed into an entry, or `null` when the entry carries none.
+ *
+ * DESCRIPTIVE ONLY: nothing orders or authorizes by it. An entry minted inside
+ * `createInvite` has no `ord` at all — kumiai orders by the epoch chain — so
+ * absence is normal and must stay distinguishable from a real clock.
+ */
+export declare function entryOrd(entry: {
+    ord?: string;
+}): string | null;
+/**
+ * Fold a group's control ledger into a reducer's projection.
+ *
+ * Entries fold in the order given, which is the order the handle's log holds
+ * them: enactment order, assigned by the authenticated MLS epoch chain. Every
+ * peer holding the same ledger holds the same sequence, so the fold is
+ * deterministic without kubun imposing an order of its own.
+ *
+ * Kubun used to sort by the signed `ord` — an order the author asserts, and so
+ * one the author can backdate: a demoted admin could date an entry into the
+ * window where it still held the role. A position is assigned by the commit
+ * chain and cannot be claimed.
+ *
+ * Authority is NOT checked here: the caller filters unauthorized entries out
+ * first, because the reducer's `verifyAuthority` sees only the entry and the
+ * prefix an entry is judged against is a property of its slot.
+ */
+export declare function foldLedgerEntries<TValue, TState>(entries: Array<FoldInput<TValue>>, anchor: GroupAnchor, reducer: LedgerReducer<TValue, TState>, onDrop?: (drop: FoldDrop) => void): TState;

package/lib/groups/ledger.js

@@ -0,0 +1,30 @@
+import { foldLedger } from '@kumiai/mls';
+export { ledgerEntryDigest, signLedgerEntry, verifyLedgerEntry } from '@kumiai/mls';
+/**
+ * The HLC kubun signed into an entry, or `null` when the entry carries none.
+ *
+ * DESCRIPTIVE ONLY: nothing orders or authorizes by it. An entry minted inside
+ * `createInvite` has no `ord` at all — kumiai orders by the epoch chain — so
+ * absence is normal and must stay distinguishable from a real clock.
+ */ export function entryOrd(entry) {
+    return entry.ord ?? null;
+}
+/**
+ * Fold a group's control ledger into a reducer's projection.
+ *
+ * Entries fold in the order given, which is the order the handle's log holds
+ * them: enactment order, assigned by the authenticated MLS epoch chain. Every
+ * peer holding the same ledger holds the same sequence, so the fold is
+ * deterministic without kubun imposing an order of its own.
+ *
+ * Kubun used to sort by the signed `ord` — an order the author asserts, and so
+ * one the author can backdate: a demoted admin could date an entry into the
+ * window where it still held the role. A position is assigned by the commit
+ * chain and cannot be claimed.
+ *
+ * Authority is NOT checked here: the caller filters unauthorized entries out
+ * first, because the reducer's `verifyAuthority` sees only the entry and the
+ * prefix an entry is judged against is a property of its slot.
+ */ export function foldLedgerEntries(entries, anchor, reducer, onDrop) {
+    return foldLedger(entries, anchor, reducer, onDrop);
+}