@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/groups/broadcast.js

@@ -1 +1,702 @@
-import{HLC as e}from"@kubun/hlc";import{evaluateAndForward as r,rethrowIfProgrammerError as a}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 c}from"./store-received-revocation.js";function i(r,a){return e.compare(e.parse(r),e.parse(a))>0}export async function processBroadcast(e,o,d){let{p2pStore:p,graphStore:n}=e;switch(o.type){case"circle:create":{let e=await p.getCircle(o.circle.id,{includeRemoved:!0});if(null!=e){let r=e.removed_at_hlc??e.hlc;if(!i(o.circle.hlc,r))return{applied:!1};await p.updateCircle(o.circle.id,{name:o.circle.name,description:o.circle.description,catalog_ids:o.circle.catalogIDs,hlc:o.circle.hlc});let a=await p.getCircle(o.circle.id);return null!=a?{applied:!0,affected:{kind:"circle",row:a}}:{applied:!0}}await p.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 r=await p.getCircle(o.circle.id);return null!=r?{applied:!0,affected:{kind:"circle",row:r}}:{applied:!0}}case"circle:update":{let e=await p.getCircle(o.circleID,{includeRemoved:!0});if(null==e)return{applied:!1};let r=e.removed_at_hlc??e.hlc;if(!i(o.update.hlc,r))return{applied:!1};await p.updateCircle(o.circleID,{name:o.update.name,description:o.update.description,catalog_ids:o.update.catalogIDs,hlc:o.update.hlc});let a=await p.getCircle(o.circleID);return null!=a?{applied:!0,affected:{kind:"circle",row:a}}:{applied:!0}}case"circle:delete":{let e=await p.getCircle(o.circleID,{includeRemoved:!0});if(null==e||!i(o.hlc,e.hlc))return{applied:!1};return await p.markCircleRemoved(o.circleID,o.hlc),{applied:!0,affected:{kind:"circle",row:e}}}case"member:add":{let e=await p.getCircleMember(o.member.circleID,o.member.memberDID);if(null!=e){let r=e.removed_at_hlc??e.hlc;if(!i(o.member.hlc,r))return{applied:!1}}await p.addCircleMember({circle_id:o.member.circleID,member_did:o.member.memberDID,role:o.member.role,hlc:o.member.hlc});let r=await p.getCircleMember(o.member.circleID,o.member.memberDID);return null!=r?{applied:!0,affected:{kind:"member",row:r}}:{applied:!0}}case"member:remove":{let e=await p.getCircleMember(o.circleID,o.memberDID);return await p.removeCircleMember(o.circleID,o.memberDID,o.hlc),null!=e?{applied:!0,affected:{kind:"member",row:e}}:{applied:!0}}case"catalog:create":{let e=await n.getCatalog(o.catalog.id);if(null!=e){if(!i(o.catalog.hlc,e.hlc))return{applied:!1};await n.updateCatalog(o.catalog.id,{name:o.catalog.name,description:o.catalog.description,filter_criteria:o.catalog.filterCriteria,hlc:o.catalog.hlc});let r=await n.getCatalog(o.catalog.id);return null!=r?{applied:!0,affected:{kind:"catalog",row:r}}:{applied:!0}}await n.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 r=await n.getCatalog(o.catalog.id);return null!=r?{applied:!0,affected:{kind:"catalog",row:r}}:{applied:!0}}case"catalog:update":{let e=await n.getCatalog(o.catalogID);if(null==e||!i(o.update.hlc,e.hlc))return{applied:!1};await n.updateCatalog(o.catalogID,{name:o.update.name,description:o.update.description,filter_criteria:o.update.filterCriteria,hlc:o.update.hlc});let r=await n.getCatalog(o.catalogID);return null!=r?{applied:!0,affected:{kind:"catalog",row:r}}:{applied:!0}}case"catalog:delete":{let e=await n.getCatalog(o.catalogID);if(null==e||!i(o.hlc,e.hlc))return{applied:!1};return await n.deleteCatalog(o.catalogID),{applied:!0,affected:{kind:"catalog",row:e}}}case"delegation:share":return{applied:await t({p2pStore:p,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 c({p2pStore:p,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 p.getGroup(o.groupID);if(null==e||!i(o.update.hlc,e.hlc))return{applied:!1};await p.updateGroup(o.groupID,{name:o.update.name,description:o.update.description,hlc:o.update.hlc});let r=await p.getGroup(o.groupID);return null!=r?{applied:!0,affected:{kind:"group",row:r}}:{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,r,a)=>n.getUserModelAccessDefault(e,r,a),isMemberOfAnyCircle:(e,r)=>p.isMemberOfAnyCircle(e,r),isMemberOfAnyGroup:(e,r)=>p.isMemberOfAnyGroup(e,r),getModelInterfaces:e=>n.getModelInterfaces(e)},defaultAccessLevel:e.defaultAccessLevel??{read:"only_owner",write:"only_owner"}}):void 0,c=null!=e.forwarding&&!1!==e.forwarding&&null!=e.scheduleBroadcast,i=!1,u=0,s=0,m=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 g=!1;try{let e=await p.recordBroadcast({docID:l.docID,version:l.version,mlsGroupID:d});g=!0,!e&&m++}catch(r){a(r),e.logger?.warn("mutation:apply recordBroadcast failed, skipping forward",{docID:l.docID,version:l.version,groupID:d,error:r})}if(i=!0,!g)continue;if(c&&null!=e.forwarding&&null!=e.scheduleBroadcast&&null!=o.document)try{let a=await r({entry:l,postState:o.document,sourceGroupID:d,selfDID:e.selfDID,p2pStore:p,graphStore:n,defaultAccessLevel:e.defaultAccessLevel??{read:"only_owner",write:"only_owner"},forwarding:e.forwarding,scheduleBroadcast:e.scheduleBroadcast,logger:e.logger});s+=a.forwarded}catch(r){a(r),e.logger?.warn("mutation:apply forwarding failed, skipping entry",{docID:l.docID,version:l.version,groupID:d,error:r})}}catch(r){a(r),e.logger?.warn("mutation:apply entry failed, skipping",{docID:l.docID,version:l.version,modelID:l.modelID,groupID:d,error:r})}let g={applied:i,dropped:u,duplicates:m};return c&&(g.forwarded=s),g}case"circle-catchup:request":case"circle-catchup:reply":return{applied:!1}}}export async function applyCatchupReply(e,r,a){let l=0,t=0;for(let t of r.circles){let r={type:"circle:create",circle:{id:t.id,groupID:t.groupID,name:t.name,description:t.description,catalogIDs:t.catalogIDs,hlc:t.hlc}},c=(await processBroadcast(e,r,a)).applied;if(null!=t.removedAtHLC){let r={type:"circle:delete",circleID:t.id,hlc:t.removedAtHLC},l=await processBroadcast(e,r,a);c=c||l.applied}c&&l++}for(let l of r.circleMembers){let r={type:"member:add",member:{circleID:l.circleID,memberDID:l.memberDID,role:l.role,hlc:l.hlc}},c=(await processBroadcast(e,r,a)).applied;if(null!=l.removedAtHLC){let r={type:"member:remove",circleID:l.circleID,memberDID:l.memberDID,hlc:l.removedAtHLC},t=await processBroadcast(e,r,a);c=c||t.applied}c&&t++}return{circlesApplied:l,membersApplied:t}}
+import { normalizeDID } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { toISO } from '../context/types.js';
+import { evaluateAndForward, rethrowIfProgrammerError } from '../sync/forwarder.js';
+import { createReceiveAccessGate } from '../sync/receive-access-gate.js';
+import { verifyAccessDefault } from './access-default-token.js';
+import { verifyCatalog } from './catalog-token.js';
+import { reprojectCircleDefs, reprojectCircleMembers, reprojectGroupSettings } from './circle-projection.js';
+import { entryOrd } from './ledger.js';
+import { resolveGroupAnchor } from './ledger-ingest.js';
+import { mirrorRosterRoles } from './roster-projection.js';
+import { storeReceivedGrant } from './store-received-grant.js';
+import { storeReceivedRevocation } from './store-received-revocation.js';
+/**
+ * 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':
+            {
+                // Authenticate via the signed token: an absent, forged, or unsigned token
+                // verifies to null and is dropped. The authoritative catalog comes from
+                // the verified payload, never the surrounding plaintext frame.
+                const verified = message.auth != null ? await verifyCatalog(message.auth) : null;
+                if (verified == null || verified.claim.op !== 'set') {
+                    params.logger?.warn('catalog:create dropped: token verification failed', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                const catalog = verified.claim.catalog;
+                // Sender-bound: a catalog is applied only when its owner is the
+                // authenticated author. Nobody can publish a catalog under another DID.
+                // `verified.issuer` is already canonicalized (short form), so normalize
+                // the record owner to compare — it may carry the signer's long form.
+                if (normalizeDID(catalog.ownerDID) !== verified.issuer) {
+                    params.logger?.warn('catalog:create dropped: owner is not the authenticated author', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                // Discovery is advisory: an absent catalog is stored KNOWN (not active) so
+                // it applies no sync until an explicit local activation. LWW by the
+                // catalog's own `hlc`: an existing row is replaced only by a strictly-newer
+                // write, and only its content — the local `active` flag and first-discovery
+                // source columns are never touched by a remote frame.
+                const existing = await graphStore.getCatalog(catalog.id);
+                if (existing == null) {
+                    // Persist the verified set token so this discovered catalog can later be
+                    // forwarded verbatim (e.g. relayed in an invite seed) and re-verified.
+                    await graphStore.upsertDiscoveredCatalog({
+                        catalog: {
+                            id: catalog.id,
+                            owner_did: catalog.ownerDID,
+                            name: catalog.name,
+                            description: catalog.description,
+                            filter_criteria: catalog.filterCriteria,
+                            hlc: catalog.hlc,
+                            signed_token: message.auth
+                        },
+                        sourceGroupID: groupID,
+                        sourceCircleID: null
+                    });
+                    return {
+                        applied: true
+                    };
+                }
+                if (normalizeDID(existing.owner_did) !== verified.issuer || catalog.hlc <= existing.hlc) {
+                    return {
+                        applied: false
+                    };
+                }
+                await graphStore.updateCatalog(catalog.id, {
+                    name: catalog.name,
+                    description: catalog.description,
+                    filter_criteria: catalog.filterCriteria,
+                    hlc: catalog.hlc,
+                    signed_token: message.auth
+                });
+                return {
+                    applied: true
+                };
+            }
+        case 'catalog:update':
+            {
+                const verified = message.auth != null ? await verifyCatalog(message.auth) : null;
+                if (verified == null || verified.claim.op !== 'update') {
+                    params.logger?.warn('catalog:update dropped: token verification failed', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                const claim = verified.claim;
+                const existing = await graphStore.getCatalog(claim.catalogID);
+                // Only the catalog's owner may update it, and only with a strictly-newer
+                // write. An unknown catalog cannot be created by an update (no owner/name).
+                if (existing == null || normalizeDID(existing.owner_did) !== verified.issuer || claim.hlc <= existing.hlc) {
+                    return {
+                        applied: false
+                    };
+                }
+                await graphStore.updateCatalog(claim.catalogID, {
+                    ...claim.update.name != null ? {
+                        name: claim.update.name
+                    } : {},
+                    ...claim.update.description != null ? {
+                        description: claim.update.description
+                    } : {},
+                    ...claim.update.filterCriteria != null ? {
+                        filter_criteria: claim.update.filterCriteria
+                    } : {},
+                    hlc: claim.hlc
+                });
+                return {
+                    applied: true
+                };
+            }
+        case 'catalog:delete':
+            {
+                const verified = message.auth != null ? await verifyCatalog(message.auth) : null;
+                if (verified == null || verified.claim.op !== 'remove') {
+                    params.logger?.warn('catalog:delete dropped: token verification failed', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                const existing = await graphStore.getCatalog(verified.claim.catalogID);
+                // Only the owner may delete. An owner retracting a catalog suggestion must
+                // not silently break a member who activated it: a locally-activated row is
+                // left completely untouched, and only a known (not-active) row is removed.
+                // No tombstone is needed — a remote frame can never overwrite local
+                // activation, so a stale set reviving a removed known catalog is harmless.
+                if (existing == null || normalizeDID(existing.owner_did) !== verified.issuer || existing.active === 1) {
+                    return {
+                        applied: false
+                    };
+                }
+                await graphStore.deleteCatalog(verified.claim.catalogID);
+                return {
+                    applied: true
+                };
+            }
+        case 'access-default:set':
+            {
+                const applied = await applyAccessDefaultSetFrame({
+                    graphStore,
+                    frame: message,
+                    ...params.logger != null ? {
+                        logger: params.logger
+                    } : {},
+                    groupID
+                });
+                return {
+                    applied
+                };
+            }
+        case 'access-default:remove':
+            {
+                const verified = await verifyAccessDefault(message.auth);
+                if (verified == null || verified.claim.op !== 'remove') {
+                    params.logger?.warn('access-default:remove dropped: token verification failed', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                // Normalized on both sides, as the `:set` arm is. `verified.issuer` is
+                // always the canonical short form and tokens sign with
+                // `embedLongForm: true`, so a raw comparison is fail-closed today only
+                // because every identity is a `did:key`. The first `did:peer:4` identity
+                // would silently drop every removal group-wide while the matching `set`
+                // still applied — leaving a stale grant standing.
+                if (normalizeDID(message.ownerDID) !== verified.issuer) {
+                    params.logger?.warn('access-default:remove dropped: owner is not the authenticated author', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                const claim = verified.claim;
+                // LWW per permission type: remove only the types whose stored anchor is
+                // older than this removal. A null anchor sorts as oldest, so it is removed.
+                const removable = [];
+                for (const permissionType of claim.permissionTypes){
+                    const storedHLC = await graphStore.getUserModelAccessDefaultHLC(verified.issuer, claim.modelID, permissionType);
+                    if (storedHLC == null || claim.hlc > storedHLC) {
+                        removable.push(permissionType);
+                    }
+                }
+                if (removable.length === 0) {
+                    return {
+                        applied: false
+                    };
+                }
+                await graphStore.removeUserModelAccessDefaults(verified.issuer, claim.modelID, removable, claim.hlc);
+                return {
+                    applied: true
+                };
+            }
+        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 '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.
+                // The role is read from the announcer's live membership row, not taken
+                // from the message: the request is unauthenticated, so a sender must not
+                // be able to state its own role. A request from a DID this peer holds no
+                // row for is reported as the bare membership role rather than dropped —
+                // the notification is advisory and carries no authority either way.
+                const memberRow = await params.p2pStore.getGroupMember(message.groupID, message.memberDID);
+                await params.emitter?.emit('groupLeaveRequested', {
+                    groupID: message.groupID,
+                    memberDID: message.memberDID,
+                    role: memberRow?.role ?? 'member',
+                    createdAt: memberRow == null ? new Date().toISOString() : toISO(memberRow.created_at)
+                });
+                return {
+                    applied: true
+                };
+            }
+        case 'peer:announce':
+            {
+                // Unattributable, so nothing is written. The DID is the row's KEY, and a
+                // capability claim filed under a placeholder would be a claim nobody made
+                // sitting where a claim someone made belongs.
+                //
+                // Unreachable through the lane as kubun wires it — `mlsDecryptFramed`
+                // throws rather than returning a nameless sender, so an unattributable
+                // frame never opens. This is the guard for the layer above changing its
+                // mind, and it fails closed.
+                if (message.announcerDID == null) {
+                    params.logger?.warn('peer:announce dropped: frame has no authenticated sender', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                // Loopback drop. The hub already fans a publish to subscribers minus the
+                // sender, so this is redundancy — but the device's own row is seeded
+                // locally, and a self-announce arriving here would overwrite it with the
+                // remote-observed shape.
+                if (message.announcerDID === params.selfDID) {
+                    return {
+                        applied: false
+                    };
+                }
+                // LWW by the announcer's own stamp, compared exactly as the access-default
+                // rules are: an announce is idempotent, so a replayed older frame — a
+                // retained one drained after a live one, say — must not revert the row.
+                const stored = await p2pStore.getPeerAnnouncement({
+                    groupID,
+                    peerDID: message.announcerDID
+                });
+                if (stored != null && message.hlc <= stored.hlc) {
+                    return {
+                        applied: false
+                    };
+                }
+                await p2pStore.upsertPeerAnnouncement({
+                    groupID,
+                    peerDID: message.announcerDID,
+                    label: message.label,
+                    availability: message.availability,
+                    capabilities: message.capabilities,
+                    hlc: message.hlc,
+                    epoch: params.getGroupEpoch?.(groupID) ?? 0
+                });
+                return {
+                    applied: true
+                };
+            }
+        case 'mutation:apply':
+            {
+                // Loopback drop: never re-apply our own broadcast.
+                //
+                // An ABSENT sender does not drop. It is not "someone else" and it is not
+                // us — it is "unknown", and unknown must apply:
+                //  - the sender is the immediate frame sender, so for a forwarded mutation
+                //    it names the forwarder, not the author. Dropping on it would discard
+                //    validly-authored, validly-forwarded mutations.
+                //  - authorization does not rest on it. Every entry carries its own signed
+                //    `mutationJWT`, verified independently by `applyVerifiedMutation`.
+                // This guard is redundancy, not protection: the hub already fans a publish
+                // to subscribers minus the sender.
+                if (message.senderPeerDID != null && 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;
+            }
+        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'
+            };
+    }
+}
+export async function applyAccessDefaultSetFrame(params) {
+    const { graphStore, frame, logger, groupID } = params;
+    // Authenticate via the signed token: a forged or unsigned token verifies to
+    // null and is dropped. Every authoritative field comes from the verified
+    // payload, never the surrounding plaintext frame.
+    const verified = await verifyAccessDefault(frame.auth);
+    if (verified == null || !isSetClaim(verified)) {
+        logger?.warn('access-default:set dropped: token verification failed', {
+            groupID
+        });
+        return false;
+    }
+    // Sender-bound: a member states only its OWN sharing policy. The row owner is
+    // the authenticated issuer; a frame claiming a foreign owner is dropped. The
+    // issuer is already normalized, so the plaintext owner must be too — an
+    // equivalent DID in another form is the same principal.
+    if (normalizeDID(frame.ownerDID) !== verified.issuer) {
+        logger?.warn('access-default:set dropped: owner is not the authenticated author', {
+            groupID
+        });
+        return false;
+    }
+    return await applyVerifiedAccessDefaultSet(graphStore, verified);
+}
+/**
+ * Apply one signed access-default set token, with no surrounding frame.
+ *
+ * What a catch-up reply carries: a token and nothing else, so there is no
+ * plaintext mirror to cross-check and none is needed — the frame's mirror
+ * fields exist for a receiver rebuilding what was signed, and the authoritative
+ * values were always the claim's. Every other rule is the live path's: the owner
+ * is the authenticated issuer, and the write happens only if strictly newer than
+ * what is stored.
+ */ export async function applyAccessDefaultSetToken(params) {
+    const verified = await verifyAccessDefault(params.token);
+    if (verified == null || !isSetClaim(verified)) {
+        params.logger?.warn('access-default catch-up entry dropped: verification failed', {
+            groupID: params.groupID
+        });
+        return false;
+    }
+    return await applyVerifiedAccessDefaultSet(params.graphStore, verified);
+}
+/**
+ * A verified access-default that states a rule rather than withdrawing one.
+ * Written as a guard because the union discriminates on a NESTED field, which a
+ * `verified.claim.op !== 'set'` check does not narrow the parent by.
+ */ function isSetClaim(verified) {
+    return verified.claim.op === 'set';
+}
+async function applyVerifiedAccessDefaultSet(graphStore, verified) {
+    const claim = verified.claim;
+    // LWW: apply only when strictly newer than the stored rule's anchor. An
+    // unstamped stored rule (null hlc) is treated as oldest, so any stamped
+    // incoming rule wins.
+    const storedHLC = await graphStore.getUserModelAccessDefaultHLC(verified.issuer, claim.modelID, claim.permissionType);
+    if (storedHLC != null && claim.hlc <= storedHLC) {
+        return false;
+    }
+    await graphStore.setUserModelAccessDefault({
+        ownerDID: verified.issuer,
+        modelID: claim.modelID,
+        permissionType: claim.permissionType,
+        // Narrowed by `isRule` at verification, which refuses any level outside the
+        // three the read predicate is written for.
+        accessLevel: claim.rule.level,
+        allowedDIDs: claim.rule.allowedDIDs,
+        allowedCircles: claim.rule.allowedCircles,
+        allowedGroups: claim.rule.allowedGroups,
+        hlc: claim.hlc
+    });
+    return true;
+}
+/**
+ * Adopt the control state a handle already holds: merge the HLCs its entries
+ * carry into this device's clock, then rebuild every projection from them.
+ *
+ * For a peer whose handle was filled by something other than a landed commit —
+ * a joiner, whose Welcome folded the group's whole ledger and checked it against
+ * the authenticated head before this device had any say. Those entries never
+ * passed through the receive path, so nothing else has observed their clocks or
+ * projected them.
+ *
+ * The merge keeps this device's later writes sorting after what the group did
+ * before it arrived. It decides no authority — that reads the enacted position —
+ * but the LWW comparisons that are not ledger folds (removal timestamps,
+ * access-default rules) still depend on a clock that has seen the group's.
+ */ export async function adoptHandleLedgerState(params, groupID) {
+    const { hlc, logger } = params;
+    if (hlc != null && params.getGroupLedger != null) {
+        let ledger;
+        try {
+            ledger = await params.getGroupLedger(groupID);
+        } catch (error) {
+            // The reproject below reads the ledger through the same resolver and
+            // defers on its own when it cannot; losing the merge is not worth failing
+            // a join over.
+            logger?.warn('ledger clock merge skipped: ledger unreadable', {
+                groupID,
+                error
+            });
+            ledger = [];
+        }
+        for (const { verified } of ledger){
+            // An entry `@kumiai/mls` minted itself carries no `ord` — it orders by the
+            // epoch chain and never stamps kubun's clock. Nothing to merge.
+            const ord = entryOrd(verified.entry);
+            if (ord == null) {
+                continue;
+            }
+            try {
+                hlc.receive(HLC.parse(ord));
+            } catch (error) {
+                logger?.warn('ledger entry HLC merge failed', {
+                    groupID,
+                    hlc: ord,
+                    error
+                });
+            }
+        }
+    }
+    await reprojectControlProjections(params, groupID);
+}
+/**
+ * Rebuild every control projection from the group's whole ledger.
+ *
+ * A batch may carry any mix of entry types, so all three rebuild unconditionally
+ * rather than the caller working out which were touched; reprojecting a type the
+ * batch didn't move is a no-op that re-confirms the current rows.
+ */ async function reprojectControlProjections(params, groupID) {
+    const { p2pStore, logger } = params;
+    const resolution = await resolveGroupAnchor(params, groupID);
+    if (resolution.status !== 'anchored') {
+        logger?.debug('ledger batch applied; projection deferred', {
+            groupID,
+            reason: resolution.status === 'unknown' ? 'anchor unavailable' : 'no genesis anchor'
+        });
+        return;
+    }
+    const { anchor, ledger } = resolution;
+    // Sequential, and in this order: the circle rebuilds upsert each row's `open`
+    // from the circle fold, then the settings rebuild overwrites `open` from the
+    // authoritative open set. Running them concurrently, or settings first, lets
+    // the circle upsert win and delists nothing.
+    const rebuild = async (store)=>{
+        await reprojectCircleDefs({
+            store,
+            groupID,
+            anchor,
+            ledger,
+            logger
+        });
+        await reprojectCircleMembers({
+            store,
+            groupID,
+            anchor,
+            ledger,
+            logger
+        });
+        await reprojectGroupSettings({
+            store,
+            groupID,
+            anchor,
+            ledger,
+            logger
+        });
+    };
+    if (params.withProjectionTransaction != null) {
+        await params.withProjectionTransaction(rebuild);
+    } else {
+        await rebuild(p2pStore);
+    }
+}
+/**
+ * Adopt a whole ledger gathered from one untrusted responder.
+ *
+ * Signatures do NOT cover omission or reordering — a responder can hand back
+ * genuine tokens with a demotion missing — so the list is installed against the
+ * authenticated head FIRST and rejected whole on mismatch, before anything is
+ * projected. Roles are reconciled against the roster the install folded, not the
+ * ledger, because nothing later revisits a stale `admin` row.
+ *
+ * Throws whatever the install throws — a rejected ledger changes nothing.
+ */ export async function bootstrapGroupLedger(params, tokens, groupID) {
+    const roster = await params.installGroupLedger(groupID, tokens);
+    await reprojectControlProjections(params, groupID);
+    const members = await params.p2pStore.listGroupMembers(groupID);
+    await mirrorRosterRoles({
+        store: params.p2pStore,
+        groupID,
+        roster,
+        memberDIDs: members.map((member)=>member.member_did),
+        members
+    });
+    return {
+        applied: tokens.length,
+        rejected: 0
+    };
+}