@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/groups/ledger-commit-fold.js

@@ -0,0 +1,167 @@
+import { readGroupAnchor } from '@kumiai/mls';
+import { ingestVerifiedLedgerEntry } from './ledger-ingest.js';
+/**
+ * The namespace kubun owns on the control ledger. Every entry type kubun mints
+ * and projects lives under it: `kubun.circle.member`, `kubun.circle.def`,
+ * `kubun.group.settings`. Note the last one — it CONTAINS `group.` without
+ * starting with it, which is why this stays a prefix test and must never be
+ * loosened to a substring test.
+ */ const KUBUN_ENTRY_TYPE_PREFIX = 'kubun.';
+/**
+ * Whether an entry type is one kubun owns, and therefore one kubun's fold
+ * projects. Everything outside `kubun.*` is foreign: the handle consumes it and
+ * surfaces nothing to kubun, so nothing folds it.
+ *
+ * Anchored on KUBUN's namespace, not the one `@kumiai/mls` reserves, so an
+ * upstream rename (`group.role` → `kumiai.role`) cannot silently change which
+ * entries kubun projects.
+ *
+ * A producer must write rows only for FOREIGN entries: an entry the fold surfaces
+ * is appended and projected by ingest, which reads the row's pre-state to decide
+ * which domain event it stands for. A pre-written row reads as pre-existing, so
+ * the author alone sees a change event where every other device sees a create.
+ *
+ * This answers what kubun PROJECTS, not what it must OBSERVE — see
+ * {@link entriesRetainedByCommit}, whose answer for the role entry is the opposite.
+ */ export function isKubunLedgerEntryType(type) {
+    return type.startsWith(KUBUN_ENTRY_TYPE_PREFIX);
+}
+/**
+ * The entries a landed commit added to the handle's ledger that kubun does not
+ * project but must still OBSERVE. Everything outside `kubun.*`: the handle
+ * surfaces none of it, so no kubun fold builds a row from it, yet these entries
+ * carry HLCs this device has to merge — a role change stamped by another member
+ * is a timestamp this device must sort after.
+ *
+ * PROJECTS and OBSERVES are different questions — reusing one predicate for both
+ * drops the role entry's clock, which reaches this device through no other path.
+ *
+ * The delta is taken BY INDEX, never by comparing tokens: the handle's ledger is a
+ * log, not a set, so a token it already held can legitimately be enacted again.
+ * `ledgerLengthBeforeCommit` is the log's length read before `processMessage`.
+ */ export function entriesRetainedByCommit(handle, ledgerLengthBeforeCommit) {
+    const retained = [];
+    const log = handle.ledger;
+    for(let index = Math.max(ledgerLengthBeforeCommit, 0); index < log.length; index++){
+        const held = log[index];
+        if (held == null || isKubunLedgerEntryType(held.verified.entry.type)) {
+            continue;
+        }
+        retained.push({
+            verified: held.verified,
+            token: held.token
+        });
+    }
+    return retained;
+}
+/**
+ * The entries a device's OWN commit would surface, recovered from the
+ * post-commit handle's ledger. The sink only fires for a commit a handle
+ * PROCESSES — a device merges its own commit instead of processing it, so the
+ * local path derives the same list from the tokens it committed, keeping the
+ * entries kubun owns and dropping the rest. Both paths then fold identical
+ * entries through the same ingest.
+ *
+ * The receive side surfaces by kumiai's rule (everything kumiai does not reserve
+ * for itself) and this side surfaces by kubun's. The two agree on every type
+ * kubun commits, which is `kubun.*` plus the role entry kumiai interprets — a
+ * commit carrying some third party's namespace would surface remotely and not
+ * locally, and kubun mints no such entry.
+ */ export function entriesSurfacedByOwnCommit(handle, tokens) {
+    const entries = [];
+    for (const token of tokens){
+        const held = handle.ledger.find((candidate)=>candidate.token === token);
+        if (held == null || !isKubunLedgerEntryType(held.verified.entry.type)) {
+            continue;
+        }
+        entries.push(held.verified);
+    }
+    return entries;
+}
+/**
+ * Recover the signed token a surfaced entry was carried by. The handle's ledger
+ * log holds `{ token, verified }` pairs, and the entry a commit surfaces IS the
+ * `verified` the log stores for it, so the pair is recovered by identity rather
+ * than by re-deriving a digest or re-verifying a signature.
+ */ function tokenForEntry(handle, entry) {
+    for (const held of handle.ledger){
+        if (held.verified === entry) {
+            return held.token;
+        }
+    }
+    return undefined;
+}
+/**
+ * Fold a landed commit's surfaced entries into the same projection ingest a
+ * broadcast entry folds through, so the two sources converge on identical rows.
+ * Returns one descriptor per entry that moved a projection, for the caller to
+ * emit as domain events.
+ *
+ * NEVER throws. The MLS advance is the load-bearing state and a projection is a
+ * cache derivable from the ledger: a fold fault must not roll back a good
+ * commit, because a lane that refuses to advance past a frame re-reads that same
+ * frame forever. A faulted entry is logged and skipped; the projection heals on
+ * the next reproject (an admin entry's arrival rebuilds every dependent, and a
+ * ledger catch-up rebuilds all four from the whole ledger). Each entry folds
+ * independently, so one fault does not skip the rest.
+ */ export async function foldCommittedLedgerEntries(params) {
+    const { handle, entries, p2pStore, groupID, logger } = params;
+    const retained = params.retained ?? [];
+    if (entries.length === 0 && retained.length === 0) {
+        return [];
+    }
+    // Retained first, projected second — the enactment order the handle applied
+    // them in, which is the order their clocks were stamped in.
+    const pending = [
+        ...retained
+    ];
+    for (const entry of entries){
+        const token = tokenForEntry(handle, entry);
+        if (token == null) {
+            // The ledger log is the only source of an entry's signed token, and an
+            // entry the accepting handle surfaced is in it. Nothing to append without
+            // one, so log rather than guess.
+            logger?.warn('committed ledger entry skipped: no signed token in the handle ledger', {
+                groupID,
+                type: entry.entry.type
+            });
+            continue;
+        }
+        pending.push({
+            verified: entry,
+            token
+        });
+    }
+    const anchor = readGroupAnchor(handle);
+    const affected = [];
+    for (const { verified } of pending){
+        try {
+            const result = await ingestVerifiedLedgerEntry({
+                p2pStore,
+                ...params.hlc != null ? {
+                    hlc: params.hlc
+                } : {},
+                ...anchor != null ? {
+                    getGroupAnchor: async ()=>anchor
+                } : {},
+                // The accepting handle is already in hand, so its log is read straight
+                // off it. Going back through the registry here would re-acquire a lock
+                // this path may already hold.
+                getGroupLedger: async ()=>handle.ledger,
+                ...logger != null ? {
+                    logger
+                } : {}
+            }, verified, groupID);
+            if (result.ledger != null) {
+                affected.push(result.ledger);
+            }
+        } catch (error) {
+            logger?.warn('committed ledger entry projection failed, skipping', {
+                groupID,
+                type: verified.entry.type,
+                error
+            });
+        }
+    }
+    return affected;
+}

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);
+}