@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/broadcast.js

@@ -1,38 +1,16 @@
+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 { 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 { 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';
-/**
- * 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.
@@ -53,17 +31,196 @@ import { storeReceivedRevocation } from './store-received-revocation.js';
     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':
-            // 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
-            };
+            {
+                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
@@ -108,251 +265,74 @@ import { storeReceivedRevocation } from './store-received-revocation.js';
                     applied: stored
                 };
             }
-        case 'ledger:entry':
+        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':
             {
-                // 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', {
+                // 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
                     };
                 }
-                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.
+                // 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
                     };
                 }
-                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'
-                    });
+                // 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: true
+                        applied: false
                     };
                 }
-                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()
+                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
@@ -361,7 +341,17 @@ import { storeReceivedRevocation } from './store-received-revocation.js';
         case 'mutation:apply':
             {
                 // Loopback drop: never re-apply our own broadcast.
-                if (message.senderPeerDID === params.selfDID) {
+                //
+                // 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
                     };
@@ -497,14 +487,6 @@ import { storeReceivedRevocation } from './store-received-revocation.js';
                 }
                 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
@@ -519,109 +501,202 @@ import { storeReceivedRevocation } from './store-received-revocation.js';
             };
     }
 }
+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);
+}
 /**
- * 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 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.
  *
- * 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.
+ * 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.
  *
- * 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
+ * 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
             });
-            continue;
+            ledger = [];
         }
-        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) {
+        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 {
-                params.hlc.receive(HLC.parse(verified.entry.hlc));
+                hlc.receive(HLC.parse(ord));
             } catch (error) {
-                logger?.warn('ledger catch-up entry HLC merge failed', {
+                logger?.warn('ledger entry HLC merge failed', {
                     groupID,
-                    hlc: verified.entry.hlc,
+                    hlc: ord,
                     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'
-            });
-        }
+    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,
-        rejected
+        applied: tokens.length,
+        rejected: 0
     };
 }