@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/groups/broadcast.js

@@ -1 +1,627 @@
-import{HLC as e}from"@kubun/hlc";import{evaluateAndForward as a,rethrowIfProgrammerError as r}from"../sync/forwarder.js";import{createReceiveAccessGate as l}from"../sync/receive-access-gate.js";import{storeReceivedGrant as t}from"./store-received-grant.js";import{storeReceivedRevocation as i}from"./store-received-revocation.js";function c(a,r){return e.compare(e.parse(a),e.parse(r))>0}export async function processBroadcast(e,o,d){let{p2pStore:n,graphStore:p}=e;switch(o.type){case"circle:create":{let e=await n.getCircle(o.circle.id);if(null!=e){if(!c(o.circle.hlc,e.hlc))return{applied:!1};await n.updateCircle(o.circle.id,{name:o.circle.name,description:o.circle.description,catalog_ids:o.circle.catalogIDs,hlc:o.circle.hlc});let a=await n.getCircle(o.circle.id);return null!=a?{applied:!0,affected:{kind:"circle",row:a}}:{applied:!0}}await n.createCircle({id:o.circle.id,group_id:o.circle.groupID,name:o.circle.name,description:o.circle.description,catalog_ids:o.circle.catalogIDs,hlc:o.circle.hlc});let a=await n.getCircle(o.circle.id);return null!=a?{applied:!0,affected:{kind:"circle",row:a}}:{applied:!0}}case"circle:update":{let e=await n.getCircle(o.circleID);if(null==e||!c(o.update.hlc,e.hlc))return{applied:!1};await n.updateCircle(o.circleID,{name:o.update.name,description:o.update.description,catalog_ids:o.update.catalogIDs,hlc:o.update.hlc});let a=await n.getCircle(o.circleID);return null!=a?{applied:!0,affected:{kind:"circle",row:a}}:{applied:!0}}case"circle:delete":{let e=await n.getCircle(o.circleID);if(null==e||!c(o.hlc,e.hlc))return{applied:!1};return await n.deleteCircle(o.circleID),{applied:!0,affected:{kind:"circle",row:e}}}case"member:add":{await n.addCircleMember({circle_id:o.member.circleID,member_did:o.member.memberDID,role:o.member.role,hlc:o.member.hlc});let e=await n.getCircleMember(o.member.circleID,o.member.memberDID);return null!=e?{applied:!0,affected:{kind:"member",row:e}}:{applied:!0}}case"member:remove":{let e=await n.getCircleMember(o.circleID,o.memberDID);return await n.removeCircleMember(o.circleID,o.memberDID),null!=e?{applied:!0,affected:{kind:"member",row:e}}:{applied:!0}}case"catalog:create":{let e=await p.getCatalog(o.catalog.id);if(null!=e){if(!c(o.catalog.hlc,e.hlc))return{applied:!1};await p.updateCatalog(o.catalog.id,{name:o.catalog.name,description:o.catalog.description,filter_criteria:o.catalog.filterCriteria,hlc:o.catalog.hlc});let a=await p.getCatalog(o.catalog.id);return null!=a?{applied:!0,affected:{kind:"catalog",row:a}}:{applied:!0}}await p.createCatalog({id:o.catalog.id,owner_did:o.catalog.ownerDID,name:o.catalog.name,description:o.catalog.description,filter_criteria:o.catalog.filterCriteria,hlc:o.catalog.hlc});let a=await p.getCatalog(o.catalog.id);return null!=a?{applied:!0,affected:{kind:"catalog",row:a}}:{applied:!0}}case"catalog:update":{let e=await p.getCatalog(o.catalogID);if(null==e||!c(o.update.hlc,e.hlc))return{applied:!1};await p.updateCatalog(o.catalogID,{name:o.update.name,description:o.update.description,filter_criteria:o.update.filterCriteria,hlc:o.update.hlc});let a=await p.getCatalog(o.catalogID);return null!=a?{applied:!0,affected:{kind:"catalog",row:a}}:{applied:!0}}case"catalog:delete":{let e=await p.getCatalog(o.catalogID);if(null==e||!c(o.hlc,e.hlc))return{applied:!1};return await p.deleteCatalog(o.catalogID),{applied:!0,affected:{kind:"catalog",row:e}}}case"delegation:share":return{applied:await t({p2pStore:n,token:o.token,groupID:o.groupID,hlc:o.hlc,selfDID:e.selfDID,...null!=e.emitter?{emitter:e.emitter}:{},...null!=e.logger?{logger:e.logger}:{}})};case"delegation:revoke":return{applied:await i({p2pStore:n,token:o.token,groupID:o.groupID,hlc:o.hlc,...null!=e.selfDID?{selfDID:e.selfDID}:{},...null!=e.emitter?{emitter:e.emitter}:{},...null!=e.logger?{logger:e.logger}:{}})};case"group:update":{let e=await n.getGroup(o.groupID);if(null==e||!c(o.update.hlc,e.hlc))return{applied:!1};await n.updateGroup(o.groupID,{name:o.update.name,description:o.update.description,hlc:o.update.hlc});let a=await n.getGroup(o.groupID);return null!=a?{applied:!0,affected:{kind:"group",row:a}}:{applied:!0}}case"group:leaveRequest":return await e.emitter?.emit("groupLeaveRequested",{groupID:o.groupID,memberDID:o.memberDID,role:"",createdAt:new Date().toISOString()}),{applied:!0};case"mutation:apply":{if(o.senderPeerDID===e.selfDID)return{applied:!1};let t="drop"===(e.storeUnreadable??"persist")?l({selfDID:e.selfDID,db:{getUserModelAccessDefault:(e,a,r)=>p.getUserModelAccessDefault(e,a,r),isMemberOfAnyCircle:(e,a)=>n.isMemberOfAnyCircle(e,a),isMemberOfAnyGroup:(e,a)=>n.isMemberOfAnyGroup(e,a),getModelInterfaces:e=>p.getModelInterfaces(e)},defaultAccessLevel:e.defaultAccessLevel??{read:"only_owner",write:"only_owner"}}):void 0,i=null!=e.forwarding&&!1!==e.forwarding&&null!=e.scheduleBroadcast,c=!1,u=0,g=0,s=0;for(let l of o.entries)try{let o=await e.graph.applyVerifiedMutation({token:l.mutationJWT,origin:"peer",arrivalGroupID:d,...null!=t?{accessGate:t}:{}});if(o.dropped){u++;continue}let m=!1;try{let e=await n.recordBroadcast({docID:l.docID,version:l.version,mlsGroupID:d});m=!0,!e&&s++}catch(a){r(a),e.logger?.warn("mutation:apply recordBroadcast failed, skipping forward",{docID:l.docID,version:l.version,groupID:d,error:a})}if(c=!0,!m)continue;if(i&&null!=e.forwarding&&null!=e.scheduleBroadcast&&null!=o.document)try{let r=await a({entry:l,postState:o.document,sourceGroupID:d,selfDID:e.selfDID,p2pStore:n,graphStore:p,defaultAccessLevel:e.defaultAccessLevel??{read:"only_owner",write:"only_owner"},forwarding:e.forwarding,scheduleBroadcast:e.scheduleBroadcast,logger:e.logger});g+=r.forwarded}catch(a){r(a),e.logger?.warn("mutation:apply forwarding failed, skipping entry",{docID:l.docID,version:l.version,groupID:d,error:a})}}catch(a){r(a),e.logger?.warn("mutation:apply entry failed, skipping",{docID:l.docID,version:l.version,modelID:l.modelID,groupID:d,error:a})}let m={applied:c,dropped:u,duplicates:s};return i&&(m.forwarded=g),m}}}
+import { HLC } from '@kubun/hlc';
+import { evaluateAndForward, rethrowIfProgrammerError } from '../sync/forwarder.js';
+import { createReceiveAccessGate } from '../sync/receive-access-gate.js';
+import { ADMIN_ROLE_ENTRY_TYPE, ADMIN_ROSTER_PROJECTION, applyAdminEntryIncremental, reprojectAdminRoster } from './admin-roster.js';
+import { applyCircleDefEntryIncremental, applyCircleMemberEntryIncremental, applyGroupSettingsEntryIncremental, CIRCLE_DEF_PROJECTION, CIRCLE_MEMBER_PROJECTION, GROUP_SETTINGS_PROJECTION, 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 { ledgerEntryDigest, verifyLedgerEntry } from './ledger-entry.js';
+import { storeReceivedGrant } from './store-received-grant.js';
+import { storeReceivedRevocation } from './store-received-revocation.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`).
+ */ async function resolveGroupAnchor(params, groupID) {
+    if (params.getGroupAnchor == null) {
+        return {
+            status: 'unanchored'
+        };
+    }
+    let anchor;
+    try {
+        anchor = await params.getGroupAnchor(groupID);
+    } catch  {
+        return {
+            status: 'unknown'
+        };
+    }
+    return anchor != null ? {
+        status: 'anchored',
+        anchor
+    } : {
+        status: 'unanchored'
+    };
+}
+/**
+ * Process a received broadcast message, applying it to the local database
+ * with HLC-based last-write-wins conflict resolution.
+ *
+ * Returns `{ applied, affected? }`. `applied` is true when the message
+ * mutated local state. `affected` carries the row snapshot needed by
+ * downstream event mapping: after-state for create / update, before-state
+ * for delete / remove.
+ *
+ * Readback note: for create / update the post-apply row is fetched with a
+ * separate `get*` call rather than a txn-scoped read. If an unrelated
+ * concurrent write to the same row lands between apply and readback, the
+ * emitted `affected.row` reflects that later write. `BroadcastService`
+ * serializes receives, so the realistic exposure is only a same-row local
+ * mutation between apply and readback, which is acceptable for event
+ * payload fidelity.
+ */ export async function processBroadcast(params, message, groupID) {
+    const { p2pStore, graphStore } = params;
+    switch(message.type){
+        case 'catalog:create':
+        case 'catalog:update':
+        case 'catalog:delete':
+            // No authorized broadcast path exists for catalog control today, so a
+            // received catalog control frame cannot be attributed to an admin author.
+            // Drop it rather than apply an unauthenticated mutation.
+            params.logger?.warn('dropping catalog control broadcast: no authorized path', {
+                type: message.type
+            });
+            return {
+                applied: false
+            };
+        case 'delegation:share':
+            {
+                // Co-members relay the same broadcast but only the addressed device
+                // stores a held row. The grantor stamps the HLC, mirroring its own
+                // issued row for LWW consistency across devices.
+                const stored = await storeReceivedGrant({
+                    delegationStore: params.delegationStore,
+                    p2pStore,
+                    token: message.token,
+                    groupID: message.groupID,
+                    hlc: message.hlc,
+                    selfDID: params.selfDID,
+                    ...params.emitter != null ? {
+                        emitter: params.emitter
+                    } : {},
+                    ...params.logger != null ? {
+                        logger: params.logger
+                    } : {}
+                });
+                return {
+                    applied: stored
+                };
+            }
+        case 'delegation:revoke':
+            {
+                const stored = await storeReceivedRevocation({
+                    delegationStore: params.delegationStore,
+                    token: message.token,
+                    groupID: message.groupID,
+                    hlc: message.hlc,
+                    ...params.selfDID != null ? {
+                        selfDID: params.selfDID
+                    } : {},
+                    ...params.emitter != null ? {
+                        emitter: params.emitter
+                    } : {},
+                    ...params.logger != null ? {
+                        logger: params.logger
+                    } : {}
+                });
+                return {
+                    applied: stored
+                };
+            }
+        case 'ledger:entry':
+            {
+                // The token is self-authenticating, so verify it directly instead of the
+                // admin gate. A forged, unsigned, or garbage token verifies to null and
+                // is dropped — store untouched, never thrown.
+                const verified = await verifyLedgerEntry(message.token);
+                if (verified == null) {
+                    params.logger?.warn('ledger entry dropped: token verification failed', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                const entryID = ledgerEntryDigest(message.token);
+                const appended = await p2pStore.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: verified.entry.type,
+                    subject: verified.entry.subject,
+                    value: verified.entry.value,
+                    hlc: verified.entry.hlc,
+                    issuer_did: verified.issuer,
+                    signed_token: message.token
+                });
+                if (!appended) {
+                    // A duplicate (already-stored token): no clock advance, no re-projection.
+                    return {
+                        applied: false
+                    };
+                }
+                if (params.hlc != null) {
+                    try {
+                        params.hlc.receive(HLC.parse(verified.entry.hlc));
+                    } catch (error) {
+                        params.logger?.warn('ledger entry HLC merge failed', {
+                            groupID,
+                            hlc: verified.entry.hlc,
+                            error
+                        });
+                    }
+                }
+                // The entry is durable now; the role overlay can only be projected once the
+                // authenticated epoch-0 root is known. Defer projection (without dropping
+                // the entry) when there is no anchor or it can't be read right now — a later
+                // entry or catch-up reproject heals the overlay.
+                const resolution = await resolveGroupAnchor(params, groupID);
+                if (resolution.status !== 'anchored') {
+                    params.logger?.debug('ledger entry appended; role projection deferred', {
+                        groupID,
+                        type: verified.entry.type,
+                        reason: resolution.status === 'unknown' ? 'anchor unavailable' : 'no genesis anchor'
+                    });
+                    return {
+                        applied: true
+                    };
+                }
+                const anchor = resolution.anchor;
+                // Local-event descriptor for this applied entry — populated by the
+                // projected control branches below so `forwardRemoteBroadcast` can emit the
+                // same local event a producer fires, for a remote-driven change. 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. For each: an absent
+                // watermark (first projection) or an out-of-order / catch-up entry at or
+                // before what we've already folded means the cached projection is no
+                // longer a correct fold-through-this-entry, so rebuild authoritatively
+                // from the whole ledger. In-order means the entry is strictly newer than
+                // everything projected, so the current projection is exactly the
+                // fold-so-far: apply it incrementally and advance the watermark (the
+                // entry is accounted for even when its issuer lacked authority and the
+                // projection was unchanged). An unprojected type falls through; the entry
+                // is already durable.
+                switch(verified.entry.type){
+                    case ADMIN_ROLE_ENTRY_TYPE:
+                        {
+                            const adminEntry = verified;
+                            const watermark = await p2pStore.getProjectionWatermark(groupID, ADMIN_ROSTER_PROJECTION);
+                            if (watermark == null || adminEntry.entry.hlc <= watermark) {
+                                await reprojectAdminRoster({
+                                    store: p2pStore,
+                                    groupID,
+                                    anchor,
+                                    logger: params.logger
+                                });
+                            } else {
+                                await applyAdminEntryIncremental({
+                                    store: p2pStore,
+                                    groupID,
+                                    verified: adminEntry,
+                                    logger: params.logger
+                                });
+                                await p2pStore.setProjectionWatermark(groupID, ADMIN_ROSTER_PROJECTION, adminEntry.entry.hlc);
+                            }
+                            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;
+                            const watermark = await p2pStore.getProjectionWatermark(groupID, CIRCLE_DEF_PROJECTION);
+                            if (watermark == null || defEntry.entry.hlc <= watermark) {
+                                await reprojectCircleDefs({
+                                    store: p2pStore,
+                                    groupID,
+                                    anchor,
+                                    logger: params.logger
+                                });
+                            } else {
+                                await applyCircleDefEntryIncremental({
+                                    store: p2pStore,
+                                    groupID,
+                                    anchor,
+                                    verified: defEntry,
+                                    logger: params.logger
+                                });
+                                await p2pStore.setProjectionWatermark(groupID, CIRCLE_DEF_PROJECTION, defEntry.entry.hlc);
+                            }
+                            // 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);
+                            const watermark = await p2pStore.getProjectionWatermark(groupID, CIRCLE_MEMBER_PROJECTION);
+                            if (watermark == null || memberEntry.entry.hlc <= watermark) {
+                                await reprojectCircleMembers({
+                                    store: p2pStore,
+                                    groupID,
+                                    anchor,
+                                    logger: params.logger
+                                });
+                            } else {
+                                await applyCircleMemberEntryIncremental({
+                                    store: p2pStore,
+                                    groupID,
+                                    anchor,
+                                    verified: memberEntry,
+                                    logger: params.logger
+                                });
+                                await p2pStore.setProjectionWatermark(groupID, CIRCLE_MEMBER_PROJECTION, memberEntry.entry.hlc);
+                            }
+                            // 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:
+                        {
+                            const settingsEntry = verified;
+                            const watermark = await p2pStore.getProjectionWatermark(groupID, GROUP_SETTINGS_PROJECTION);
+                            if (watermark == null || settingsEntry.entry.hlc <= watermark) {
+                                await reprojectGroupSettings({
+                                    store: p2pStore,
+                                    groupID,
+                                    anchor,
+                                    logger: params.logger
+                                });
+                            } else {
+                                await applyGroupSettingsEntryIncremental({
+                                    store: p2pStore,
+                                    groupID,
+                                    anchor,
+                                    verified: settingsEntry,
+                                    logger: params.logger
+                                });
+                                await p2pStore.setProjectionWatermark(groupID, GROUP_SETTINGS_PROJECTION, settingsEntry.entry.hlc);
+                            }
+                            // 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,
+                    affected: {
+                        kind: 'ledger',
+                        ledger: ledgerAffected
+                    }
+                } : {
+                    applied: true
+                };
+            }
+        case 'group:leaveRequest':
+            {
+                // Advisory notification only — surface it for admin apps to act on. No
+                // store mutation: this is not an authoritative removal (a forged request
+                // must not evict anyone), and MLS forbids self-removal anyway.
+                await params.emitter?.emit('groupLeaveRequested', {
+                    groupID: message.groupID,
+                    memberDID: message.memberDID,
+                    role: '',
+                    createdAt: new Date().toISOString()
+                });
+                return {
+                    applied: true
+                };
+            }
+        case 'mutation:apply':
+            {
+                // Loopback drop: never re-apply our own broadcast.
+                if (message.senderPeerDID === params.selfDID) {
+                    return {
+                        applied: false
+                    };
+                }
+                const storeUnreadable = params.storeUnreadable ?? 'persist';
+                // Build the receive-time access gate per `'drop'` broadcast, as a factory
+                // over the apply's transaction-scoped stores so its access reads run
+                // inside the apply transaction (a main-connection read there deadlocks on
+                // single-connection SQLite). Under `'persist'` the gate is omitted —
+                // `applyVerifiedMutation` takes its zero-overhead no-gate path.
+                const accessGate = storeUnreadable === 'drop' ? ({ graphStore: txGraphStore, p2pStore: txP2PStore })=>{
+                    if (txP2PStore == null) {
+                        return undefined;
+                    }
+                    return createReceiveAccessGate({
+                        selfDID: params.selfDID,
+                        db: {
+                            getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>txGraphStore.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+                            isMemberOfAnyCircle: (viewerDID, circleIDs)=>txP2PStore.isMemberOfAnyCircle(viewerDID, circleIDs),
+                            isMemberOfAnyGroup: (viewerDID, groupIDs)=>txP2PStore.isMemberOfAnyGroup(viewerDID, groupIDs),
+                            getModelInterfaces: (modelID)=>txGraphStore.getModelInterfaces(modelID)
+                        },
+                        defaultAccessLevel: params.defaultAccessLevel ?? {
+                            read: 'only_owner',
+                            write: 'only_owner'
+                        }
+                    });
+                } : undefined;
+                // Forwarding is enabled when both `forwarding` is set + truthy AND a
+                // `scheduleBroadcast` hook is supplied. Either alone is a no-op.
+                const forwardingEnabled = params.forwarding != null && params.forwarding !== false && params.scheduleBroadcast != null;
+                let anyApplied = false;
+                let dropped = 0;
+                let forwarded = 0;
+                let duplicates = 0;
+                for (const entry of message.entries){
+                    try {
+                        const applyResult = await params.graph.applyVerifiedMutation({
+                            token: entry.mutationJWT,
+                            origin: 'peer',
+                            arrivalGroupID: groupID,
+                            ...accessGate != null ? {
+                                accessGate
+                            } : {}
+                        });
+                        if (applyResult.dropped) {
+                            dropped++;
+                            continue;
+                        }
+                        // recordBroadcast wrapped in its own try/catch: if the dedup row
+                        // insert fails (DB error), skip forwarding for THIS entry to avoid
+                        // propagating a broadcast that has no corresponding broadcast_log
+                        // row (next receive would re-apply + re-forward). The mutation
+                        // itself was applied successfully so we still mark anyApplied.
+                        // Continue the per-entry loop — don't unwind for the rest.
+                        let recordedOK = false;
+                        try {
+                            const recorded = await p2pStore.recordBroadcast({
+                                docID: entry.docID,
+                                version: entry.version,
+                                mlsGroupID: groupID
+                            });
+                            recordedOK = true;
+                            if (!recorded) {
+                                duplicates++;
+                            }
+                        } catch (error) {
+                            rethrowIfProgrammerError(error);
+                            params.logger?.warn('mutation:apply recordBroadcast failed, skipping forward', {
+                                docID: entry.docID,
+                                version: entry.version,
+                                groupID,
+                                error
+                            });
+                        }
+                        anyApplied = true;
+                        if (!recordedOK) {
+                            continue;
+                        }
+                        // Forward AFTER recordBroadcast success so the source-group dedup
+                        // entry is in place before any downstream peer can echo back.
+                        if (forwardingEnabled && params.forwarding != null && params.scheduleBroadcast != null && applyResult.document != null) {
+                            try {
+                                const fwdResult = await evaluateAndForward({
+                                    entry,
+                                    postState: applyResult.document,
+                                    sourceGroupID: groupID,
+                                    selfDID: params.selfDID,
+                                    p2pStore,
+                                    graphStore,
+                                    defaultAccessLevel: params.defaultAccessLevel ?? {
+                                        read: 'only_owner',
+                                        write: 'only_owner'
+                                    },
+                                    forwarding: params.forwarding,
+                                    scheduleBroadcast: params.scheduleBroadcast,
+                                    logger: params.logger
+                                });
+                                forwarded += fwdResult.forwarded;
+                            } catch (error) {
+                                rethrowIfProgrammerError(error);
+                                params.logger?.warn('mutation:apply forwarding failed, skipping entry', {
+                                    docID: entry.docID,
+                                    version: entry.version,
+                                    groupID,
+                                    error
+                                });
+                            }
+                        }
+                    } catch (error) {
+                        rethrowIfProgrammerError(error);
+                        // Partial-apply tolerance: log and skip this entry, continue with rest.
+                        params.logger?.warn('mutation:apply entry failed, skipping', {
+                            docID: entry.docID,
+                            version: entry.version,
+                            modelID: entry.modelID,
+                            groupID,
+                            error
+                        });
+                    }
+                }
+                // `affected` stays undefined — document mutation consumers listen to
+                // engine events (document:saved, engine:document:*, engine:mutation:received)
+                // which fire via the engine-routed apply path. The broadcast event stream
+                // remains control-plane-centric.
+                const result = {
+                    applied: anyApplied,
+                    dropped,
+                    duplicates
+                };
+                if (forwardingEnabled) {
+                    result.forwarded = forwarded;
+                }
+                return result;
+            }
+        case 'ledger-catchup:request':
+        case 'ledger-catchup:reply':
+            // Catch-up request/reply are dispatched by the broadcast service's
+            // catch-up path, not the LWW apply switch. Treated as no-ops here so the
+            // generic broadcast handler stays exhaustive.
+            return {
+                applied: false
+            };
+        default:
+            // Version skew: a newer peer shipped a `type` outside our union. Return an
+            // explicit not-applied outcome (never a silent `undefined`) so no consumer
+            // dereferences undefined, and log it.
+            params.logger?.warn('unknown broadcast message type', {
+                type: message.type,
+                groupID
+            });
+            return {
+                applied: false,
+                reason: 'unknown-type'
+            };
+    }
+}
+/**
+ * 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 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.
+ *
+ * Never throws out of the per-token loop: one bad token must not abort the batch.
+ */ export async function applyLedgerCatchupReply(params, reply, groupID) {
+    const { p2pStore, logger } = params;
+    let applied = 0;
+    let rejected = 0;
+    for (const token of reply.entries){
+        // The untrusted check: a forged, unsigned, or garbage token verifies to
+        // null and is dropped here. The responder is never trusted — this is the
+        // sole authority over what enters the local ledger.
+        const verified = await verifyLedgerEntry(token);
+        if (verified == null) {
+            rejected++;
+            logger?.warn('ledger catch-up entry dropped: token verification failed', {
+                groupID
+            });
+            continue;
+        }
+        const entryID = ledgerEntryDigest(token);
+        const appended = await p2pStore.appendLedgerEntry({
+            group_id: groupID,
+            entry_id: entryID,
+            type: verified.entry.type,
+            subject: verified.entry.subject,
+            value: verified.entry.value,
+            hlc: verified.entry.hlc,
+            issuer_did: verified.issuer,
+            signed_token: token
+        });
+        if (!appended) {
+            continue;
+        }
+        applied++;
+        if (params.hlc != null) {
+            try {
+                params.hlc.receive(HLC.parse(verified.entry.hlc));
+            } catch (error) {
+                logger?.warn('ledger catch-up entry HLC merge failed', {
+                    groupID,
+                    hlc: verified.entry.hlc,
+                    error
+                });
+            }
+        }
+    }
+    if (applied > 0) {
+        const resolution = await resolveGroupAnchor(params, groupID);
+        if (resolution.status === 'anchored') {
+            // Full authoritative rebuild — a catch-up batch delivers history out of
+            // order, so the cached projection can no longer be trusted as a
+            // fold-through-watermark. This also resets each watermark to the max folded
+            // HLC. A batch may carry any mix of entry types, so all control
+            // projections rebuild unconditionally; reprojecting a type the batch
+            // didn't touch is a harmless no-op that just re-confirms the current rows.
+            await reprojectAdminRoster({
+                store: p2pStore,
+                groupID,
+                anchor: resolution.anchor,
+                logger
+            });
+            await reprojectCircleDefs({
+                store: p2pStore,
+                groupID,
+                anchor: resolution.anchor,
+                logger
+            });
+            await reprojectCircleMembers({
+                store: p2pStore,
+                groupID,
+                anchor: resolution.anchor,
+                logger
+            });
+            await reprojectGroupSettings({
+                store: p2pStore,
+                groupID,
+                anchor: resolution.anchor,
+                logger
+            });
+        } else {
+            logger?.debug('ledger catch-up applied; projection deferred', {
+                groupID,
+                applied,
+                reason: resolution.status === 'unknown' ? 'anchor unavailable' : 'no genesis anchor'
+            });
+        }
+    }
+    return {
+        applied,
+        rejected
+    };
+}