@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/join-utils.js

@@ -1,9 +1,28 @@
+import { normalizeDID } from '@kokuin/token';
 import { HLC as HLCClass } from '@kubun/hlc';
 import { getDelegationStore } from '@kubun/store-delegation';
+import { getGraphStore } from '@kubun/store-graph';
 import { getP2PStore } from '@kubun/store-p2p';
+import { canonicalStringify } from '@sozai/codec';
 import { toISO } from '../context/types.js';
+import { signAccessDefaultSet } from './access-default-token.js';
+import { adoptHandleLedgerState, applyAccessDefaultSetFrame } from './broadcast.js';
+import { verifyCatalog } from './catalog-token.js';
 import { storeReceivedGrant } from './store-received-grant.js';
 import { storeReceivedRevocation } from './store-received-revocation.js';
+/**
+ * Whether an invite's plaintext catalog record equals the creator-signed one,
+ * field by field. Guards the invite-seed apply so a tampered plaintext field is
+ * rejected rather than silently overwritten by the authentic value. Filter
+ * criteria compare order-independently by key (token signing re-sorts keys) but
+ * remain sensitive to values and array contents, so a spoofed model list is
+ * still caught.
+ */ function catalogRecordsMatch(a, b) {
+    return a.id === b.id && a.ownerDID === b.ownerDID && a.name === b.name && a.description === b.description && a.hlc === b.hlc && // The SAME canonicalization token signing applies, so a criteria object that
+    // only differs in key order compares equal here for the same reason it signs
+    // identically. Array element order stays significant, which filter lists need.
+    canonicalStringify(a.filterCriteria) === canonicalStringify(b.filterCriteria);
+}
 export async function finalizeJoinedGroup(params) {
     const { stores, emitter, invite, logger } = params;
     const store = await getP2PStore(stores);
@@ -102,3 +121,246 @@ export async function finalizeJoinedGroup(params) {
         })));
     return results.reduce((count, applied)=>count + (applied ? 1 : 0), 0);
 }
+/**
+ * Gather the group state an invite seeds into the joiner: the inviter's own
+ * model access-defaults (each signed so it self-authenticates), and the catalogs
+ * the group's circles reference. Access-default rows without an HLC anchor are
+ * skipped — they carry no LWW ordering and cannot be authenticated for
+ * replication.
+ */ export async function collectInviteSeeds(params) {
+    const { stores, identity, ownerDID, groupID, logger } = params;
+    const [p2pStore, graphStore] = await Promise.all([
+        getP2PStore(stores),
+        getGraphStore(stores)
+    ]);
+    // Circles of the group being joined. Removed circles still resolve in this
+    // group's ledger, so they count as this group's.
+    const circles = await p2pStore.listCirclesByGroup(groupID, {
+        includeRemoved: true
+    });
+    const groupCircleIDs = new Set(circles.map((circle)=>circle.id));
+    // Resolve the group's catalogs (the ones its circles reference) up front: the
+    // catalog seeds are built from this same map below, and the union of their
+    // model IDs bounds which circle-less access-defaults may travel. First circle
+    // that references a catalog wins as its provenance source.
+    const catalogSourceCircle = new Map();
+    for (const circle of circles){
+        for (const catalogID of circle.catalog_ids){
+            if (!catalogSourceCircle.has(catalogID)) {
+                catalogSourceCircle.set(catalogID, circle.id);
+            }
+        }
+    }
+    const catalogMap = await graphStore.getCatalogs(Array.from(catalogSourceCircle.keys()));
+    const catalogModelIDs = new Set();
+    for (const catalog of catalogMap.values()){
+        for (const modelID of catalog.filter_criteria.models ?? []){
+            catalogModelIDs.add(modelID);
+        }
+    }
+    // Seed an access-default row iff it either names a circle of the joined group,
+    // or is circle-less AND its model is in the group's catalog model set. The
+    // invite must disclose nothing beyond what the group already carries by design
+    // — its circles and its catalogs' declared model set. A row naming only foreign
+    // circles would land as an orphan and disclose unrelated groups; a circle-less
+    // row for an unrelated model (anyone / only_owner / groups-only) would leak that
+    // model's existence and the owner's posture to a joiner with no reason to know
+    // it. Catalogs scope RELEVANCE here, never authorization.
+    const rows = await graphStore.listUserModelAccessDefaults(ownerDID);
+    const accessDefaults = [];
+    for (const row of rows){
+        const circleIDs = row.allowedCircles ?? [];
+        if (circleIDs.length > 0) {
+            if (!circleIDs.some((circleID)=>groupCircleIDs.has(circleID))) {
+                continue;
+            }
+        } else if (!catalogModelIDs.has(row.modelID)) {
+            continue;
+        }
+        const hlc = await graphStore.getUserModelAccessDefaultHLC(ownerDID, row.modelID, row.permissionType);
+        if (hlc == null) {
+            continue;
+        }
+        const rule = {
+            level: row.level,
+            allowedDIDs: row.allowedDIDs,
+            allowedCircles: row.allowedCircles,
+            allowedGroups: row.allowedGroups
+        };
+        const auth = await signAccessDefaultSet(identity, {
+            modelID: row.modelID,
+            permissionType: row.permissionType,
+            rule,
+            hlc
+        });
+        accessDefaults.push({
+            ownerDID,
+            modelID: row.modelID,
+            permissionType: row.permissionType,
+            rule,
+            hlc,
+            auth
+        });
+    }
+    const catalogs = [];
+    for (const [catalogID, sourceCircleID] of catalogSourceCircle){
+        const catalog = catalogMap.get(catalogID);
+        if (catalog == null) {
+            continue;
+        }
+        // Advisory data: a catalog with no captured creator token cannot be
+        // authenticated on the joiner, so skip it rather than seed an unverifiable
+        // record. Post-change every catalog is minted with a token, so this only
+        // drops pre-existing tokenless rows.
+        if (catalog.signed_token == null) {
+            logger?.debug('invite catalog seed skipped: no signed token', {
+                catalogID,
+                groupID
+            });
+            continue;
+        }
+        catalogs.push({
+            catalog: {
+                id: catalog.id,
+                ownerDID: catalog.owner_did,
+                name: catalog.name,
+                description: catalog.description,
+                filterCriteria: catalog.filter_criteria,
+                hlc: catalog.hlc
+            },
+            sourceCircleID,
+            token: catalog.signed_token
+        });
+    }
+    return {
+        accessDefaults,
+        catalogs
+    };
+}
+/**
+ * Apply the control state a join produced, after the MLS join completes.
+ *
+ * The control ledger is NOT among the parameters, deliberately: it arrived on
+ * the MLS invite and `processWelcome` has already checked it against the
+ * authenticated head and folded it into the handle, which is what every
+ * projection reads. All that is left is to adopt what the handle now holds. A
+ * second copy carried beside it could only agree or disagree, and a joiner has
+ * no way to tell which.
+ *
+ * The rest authenticates independently: access-defaults apply sender-bound + LWW
+ * via their owner-signed tokens, and catalogs upsert as plain sync-scope records
+ * trusted from the inviter. A third-party access-default row is dropped without
+ * blocking the rest.
+ */ export async function applyInviteControlState(params) {
+    const { stores, groupID, accessDefaults, catalogs, hlc, getGroupAnchor, getGroupLedger, logger } = params;
+    // Only a caller that can resolve the group's anchor and ledger can adopt
+    // anything: without both, the projections defer and the clock has nothing to
+    // observe, so the whole step would be a no-op that still demanded a p2p store.
+    if (getGroupAnchor != null && getGroupLedger != null) {
+        const p2pStore = await getP2PStore(stores);
+        await adoptHandleLedgerState({
+            p2pStore,
+            hlc,
+            getGroupAnchor,
+            getGroupLedger,
+            // Only the projection rebuild is transactional. The adopt reads the
+            // ledger through the registry first, and holding a transaction across
+            // that mutex would deadlock kubun's single SQLite connection.
+            withProjectionTransaction: (run)=>stores.withTransaction(async (tx)=>await run(await getP2PStore(tx))),
+            ...logger != null ? {
+                logger
+            } : {}
+        }, groupID);
+    }
+    if (accessDefaults != null && accessDefaults.length > 0 || catalogs != null && catalogs.length > 0) {
+        const graphStore = await getGraphStore(stores);
+        for (const seed of accessDefaults ?? []){
+            await applyAccessDefaultSetFrame({
+                graphStore,
+                frame: seed,
+                ...logger != null ? {
+                    logger
+                } : {},
+                groupID
+            });
+        }
+        for (const seed of catalogs ?? []){
+            const { catalog, sourceCircleID, token } = seed;
+            // Authenticate the seed with the SAME verification the broadcast
+            // `catalog:create` receive path uses: an absent, forged, or unsigned token
+            // verifies to null and is dropped. The inviter cannot mint a token for
+            // another member's catalog, so a spoofed seed cannot pass this gate.
+            const verified = token != null ? await verifyCatalog(token) : null;
+            if (verified == null || verified.claim.op !== 'set') {
+                logger?.warn('invite catalog seed dropped: token verification failed', {
+                    catalogID: catalog.id,
+                    groupID
+                });
+                continue;
+            }
+            const authentic = verified.claim.catalog;
+            // Creator-binding: the catalog's owner must be the authenticated author.
+            // `verified.issuer` is already canonicalized (did:peer:4 short form), so
+            // normalize the record owner before comparing — the stored owner DID may
+            // be the long form the signer's identity carries.
+            if (normalizeDID(authentic.ownerDID) !== verified.issuer) {
+                logger?.warn('invite catalog seed dropped: owner is not the authenticated author', {
+                    catalogID: catalog.id,
+                    groupID
+                });
+                continue;
+            }
+            // Payload-matches-record: the plaintext seed must equal the signed record,
+            // so a tampered field (name, filter, hlc, …) is rejected outright rather
+            // than silently healed to the authentic value.
+            if (!catalogRecordsMatch(catalog, authentic)) {
+                logger?.warn('invite catalog seed dropped: record does not match signed token', {
+                    catalogID: catalog.id,
+                    groupID
+                });
+                continue;
+            }
+            const existing = await graphStore.getCatalog(authentic.id);
+            if (existing == null) {
+                // Seeded catalogs arrive KNOWN (not active): join surfaces them, but
+                // activation stays an explicit local decision. Provenance records the
+                // joined group + the circle that referenced the catalog. The verified
+                // token is persisted so the joiner can later forward it verbatim.
+                await graphStore.upsertDiscoveredCatalog({
+                    catalog: {
+                        id: authentic.id,
+                        owner_did: authentic.ownerDID,
+                        name: authentic.name,
+                        description: authentic.description,
+                        filter_criteria: authentic.filterCriteria,
+                        hlc: authentic.hlc,
+                        signed_token: token
+                    },
+                    sourceGroupID: groupID,
+                    sourceCircleID
+                });
+            } else if (normalizeDID(existing.owner_did) === verified.issuer && authentic.hlc > existing.hlc) {
+                // Owner-binding on the STORED row, which the creator check above does
+                // not give: that one proves the incoming record's owner is its issuer,
+                // and says nothing about whose row already sits under that id. Without
+                // this, an inviter validly signs a catalog for itself under an id that
+                // already exists locally under a different owner and rewrites that
+                // row's name, description and filter — `updateCatalog` touches neither
+                // `owner_did` nor `active`, so this is the one way a remote frame
+                // reaches an ACTIVE catalog's content. The ids are not secret:
+                // `shareRowID('catalog', groupID, ownerDID)` derives from two known
+                // values. Both live broadcast arms already bind this way.
+                //
+                // Content LWW only — a re-discovery never overwrites the local `active`
+                // flag or the first-discovery source columns.
+                await graphStore.updateCatalog(authentic.id, {
+                    name: authentic.name,
+                    description: authentic.description,
+                    filter_criteria: authentic.filterCriteria,
+                    hlc: authentic.hlc,
+                    signed_token: token
+                });
+            }
+        }
+    }
+}

package/lib/groups/ledger-affected-events.d.ts

@@ -5,11 +5,16 @@ import type { P2PEventEmitter } from './events.js';
  * entry that a receiving peer just applied, so GraphQL subscribers see
  * remote circle/group changes live — the same events a local producer fires.
  *
- * Only `ledger:entry` projections surface as `affected`; every other applied
- * message (delegation grant/revoke, advisory leave) already emits its own event
- * from inside `processBroadcast`, so this covers exactly the circle/group
- * projection rows the apply core returns rather than emits. The payloads are
- * built from `affected.row`, which `processBroadcast` snapshots at the right
- * moment (after-state for create/change, before-state for delete/remove).
+ * Only control-ledger projections surface as `affected`; every other applied
+ * message (delegation grant/revoke, advisory leave) emits its own event from
+ * inside `processBroadcast`. So this covers exactly the circle/group projection
+ * rows the apply core returns rather than emits.
+ *
+ * Every payload comes from `affected.row`, the POST-state in all six cases,
+ * delete and remove included: a tombstone sets only `removed_at_hlc` and leaves
+ * the other columns standing, so the removed-event payload still carries the
+ * last active `role` / `name` a before-state snapshot would have. The apply core
+ * reads pre-state for one purpose — deciding create-vs-change and whether
+ * catalogs moved — and it never becomes an event payload.
  */
 export declare function emitLedgerAffectedEvents(emitter: P2PEventEmitter, result: ProcessBroadcastResult): Promise<void>;

package/lib/groups/ledger-affected-events.js

@@ -1,15 +1,20 @@
-import { toISO } from '../context/types.js';
+import { toCircleData, toISO } from '../context/types.js';
 /**
  * Emit the local `P2PEventEmitter` events for a remote-driven control-ledger
  * entry that a receiving peer just applied, so GraphQL subscribers see
  * remote circle/group changes live — the same events a local producer fires.
  *
- * Only `ledger:entry` projections surface as `affected`; every other applied
- * message (delegation grant/revoke, advisory leave) already emits its own event
- * from inside `processBroadcast`, so this covers exactly the circle/group
- * projection rows the apply core returns rather than emits. The payloads are
- * built from `affected.row`, which `processBroadcast` snapshots at the right
- * moment (after-state for create/change, before-state for delete/remove).
+ * Only control-ledger projections surface as `affected`; every other applied
+ * message (delegation grant/revoke, advisory leave) emits its own event from
+ * inside `processBroadcast`. So this covers exactly the circle/group projection
+ * rows the apply core returns rather than emits.
+ *
+ * Every payload comes from `affected.row`, the POST-state in all six cases,
+ * delete and remove included: a tombstone sets only `removed_at_hlc` and leaves
+ * the other columns standing, so the removed-event payload still carries the
+ * last active `role` / `name` a before-state snapshot would have. The apply core
+ * reads pre-state for one purpose — deciding create-vs-change and whether
+ * catalogs moved — and it never becomes an event payload.
  */ export async function emitLedgerAffectedEvents(emitter, result) {
     if (!result.applied || result.affected == null || result.affected.kind !== 'ledger') {
         return;
@@ -23,22 +28,12 @@ import { toISO } from '../context/types.js';
                 // producer: a catalogs-only change emits `circleCatalogsChanged`, any other
                 // change emits `circleDataChanged`. The `*Changed` payloads carry `circleID`.
                 if (!ledger.preExisted) {
-                    await emitter.emit('circleCreated', {
-                        id: row.id,
-                        groupID: row.group_id,
-                        name: row.name,
-                        description: row.description,
-                        createdAt: toISO(row.created_at)
-                    });
+                    await emitter.emit('circleCreated', toCircleData(row));
                     return;
                 }
                 const eventName = ledger.catalogsChanged ? 'circleCatalogsChanged' : 'circleDataChanged';
                 await emitter.emit(eventName, {
-                    id: row.id,
-                    groupID: row.group_id,
-                    name: row.name,
-                    description: row.description,
-                    createdAt: toISO(row.created_at),
+                    ...toCircleData(row),
                     circleID: row.id
                 });
                 return;
@@ -46,13 +41,7 @@ import { toISO } from '../context/types.js';
         case 'circle.def.removed':
             {
                 const { row } = ledger;
-                await emitter.emit('circleDeleted', {
-                    id: row.id,
-                    groupID: row.group_id,
-                    name: row.name,
-                    description: row.description,
-                    createdAt: toISO(row.created_at)
-                });
+                await emitter.emit('circleDeleted', toCircleData(row));
                 return;
             }
         case 'circle.member':

package/lib/groups/ledger-commit-fold.d.ts

@@ -0,0 +1,107 @@
+import type { HLC } from '@kubun/hlc';
+import type { Logger } from '@kubun/logger';
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+import { type GroupHandle, type VerifiedLedgerEntry } from '@kumiai/mls';
+import { type LedgerAffected } from './ledger-ingest.js';
+export type CommitFoldParams = {
+    /**
+     * The handle that ACCEPTED the commit — post-advance. Two things are read from
+     * it: the genesis anchor the projections fold against, and the ledger log the
+     * surfaced entries' signed tokens live in.
+     */
+    handle: GroupHandle;
+    /**
+     * The entries the commit surfaced, collected by the handle's sink. Already
+     * notarized by the handle that accepted the commit (verified, admin-authored
+     * at their own position, group-scoped), so they are NEVER re-verified here.
+     */
+    entries: Array<VerifiedLedgerEntry>;
+    /**
+     * Transaction-scoped p2p store on the remote path, the lane's own short
+     * transaction on the local one. Never a bare store read inside a caller's
+     * transaction — that deadlocks single-connection SQLite against the tx's own
+     * write lock.
+     */
+    /**
+     * The entries the commit enacted that kubun does not PROJECT but must RETAIN
+     * — see {@link entriesRetainedByCommit}. Already carried by the same accepted
+     * commit as `entries`, so equally notarized and equally never re-verified.
+     * Ingested BEFORE `entries`, matching the enactment order the handle applied
+     * them in: a commit of `[promote Bob, entry-issued-by-Bob]` must have Bob's
+     * grant durable before the entry it authorizes is folded, or that entry is
+     * dropped as unauthorized and never revisits the verdict.
+     */
+    retained?: Array<RetainedCommitEntry>;
+    p2pStore: P2PStoreAPI;
+    groupID: string;
+    hlc?: HLC;
+    logger?: Logger;
+};
+/** A signed token plus its notarized entry, as the handle's ledger log holds it. */
+export type RetainedCommitEntry = {
+    verified: VerifiedLedgerEntry;
+    token: string;
+};
+/**
+ * Whether an entry type is one kubun owns, and therefore one kubun's fold
+ * projects. Everything outside `kubun.*` is foreign: the handle consumes it and
+ * surfaces nothing to kubun, so nothing folds it.
+ *
+ * Anchored on KUBUN's namespace, not the one `@kumiai/mls` reserves, so an
+ * upstream rename (`group.role` → `kumiai.role`) cannot silently change which
+ * entries kubun projects.
+ *
+ * A producer must write rows only for FOREIGN entries: an entry the fold surfaces
+ * is appended and projected by ingest, which reads the row's pre-state to decide
+ * which domain event it stands for. A pre-written row reads as pre-existing, so
+ * the author alone sees a change event where every other device sees a create.
+ *
+ * This answers what kubun PROJECTS, not what it must OBSERVE — see
+ * {@link entriesRetainedByCommit}, whose answer for the role entry is the opposite.
+ */
+export declare function isKubunLedgerEntryType(type: string): boolean;
+/**
+ * The entries a landed commit added to the handle's ledger that kubun does not
+ * project but must still OBSERVE. Everything outside `kubun.*`: the handle
+ * surfaces none of it, so no kubun fold builds a row from it, yet these entries
+ * carry HLCs this device has to merge — a role change stamped by another member
+ * is a timestamp this device must sort after.
+ *
+ * PROJECTS and OBSERVES are different questions — reusing one predicate for both
+ * drops the role entry's clock, which reaches this device through no other path.
+ *
+ * The delta is taken BY INDEX, never by comparing tokens: the handle's ledger is a
+ * log, not a set, so a token it already held can legitimately be enacted again.
+ * `ledgerLengthBeforeCommit` is the log's length read before `processMessage`.
+ */
+export declare function entriesRetainedByCommit(handle: GroupHandle, ledgerLengthBeforeCommit: number): Array<RetainedCommitEntry>;
+/**
+ * The entries a device's OWN commit would surface, recovered from the
+ * post-commit handle's ledger. The sink only fires for a commit a handle
+ * PROCESSES — a device merges its own commit instead of processing it, so the
+ * local path derives the same list from the tokens it committed, keeping the
+ * entries kubun owns and dropping the rest. Both paths then fold identical
+ * entries through the same ingest.
+ *
+ * The receive side surfaces by kumiai's rule (everything kumiai does not reserve
+ * for itself) and this side surfaces by kubun's. The two agree on every type
+ * kubun commits, which is `kubun.*` plus the role entry kumiai interprets — a
+ * commit carrying some third party's namespace would surface remotely and not
+ * locally, and kubun mints no such entry.
+ */
+export declare function entriesSurfacedByOwnCommit(handle: GroupHandle, tokens: Array<string>): Array<VerifiedLedgerEntry>;
+/**
+ * Fold a landed commit's surfaced entries into the same projection ingest a
+ * broadcast entry folds through, so the two sources converge on identical rows.
+ * Returns one descriptor per entry that moved a projection, for the caller to
+ * emit as domain events.
+ *
+ * NEVER throws. The MLS advance is the load-bearing state and a projection is a
+ * cache derivable from the ledger: a fold fault must not roll back a good
+ * commit, because a lane that refuses to advance past a frame re-reads that same
+ * frame forever. A faulted entry is logged and skipped; the projection heals on
+ * the next reproject (an admin entry's arrival rebuilds every dependent, and a
+ * ledger catch-up rebuilds all four from the whole ledger). Each entry folds
+ * independently, so one fault does not skip the rest.
+ */
+export declare function foldCommittedLedgerEntries(params: CommitFoldParams): Promise<Array<LedgerAffected>>;

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

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