@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/sync/access-default-sender.d.ts

@@ -0,0 +1,23 @@
+import type { OwnIdentity } from '@kokuin/token';
+import type { KubunDB } from '@kubun/db';
+import type { EngineEventBus, EngineEvents } from '@kubun/engine';
+import type { Logger } from '@kubun/logger';
+import type { GroupBroadcastMessage } from '../groups/broadcast.js';
+export type AccessDefaultSenderParams = {
+    db: KubunDB;
+    eventBus: EngineEventBus<EngineEvents>;
+    identity: OwnIdentity;
+    /** Fire-and-forget hub broadcast trigger, one call per target group. */
+    scheduleBroadcast: (groupID: string, message: GroupBroadcastMessage) => void | Promise<void>;
+    logger?: Logger;
+};
+/**
+ * Subscribe to the engine's access-default events and replicate each rule to
+ * every MLS group the local peer belongs to. A model default is owner-global,
+ * not group-scoped: any co-member evaluating the owner's documents needs the
+ * rule, and the receiver's sender-bound apply keeps a forged owner out. The
+ * fan-out is a single tiny frame per group, so no scope resolution is needed.
+ *
+ * Returns a combined unsubscribe function for both listeners.
+ */
+export declare function wireAccessDefaultSender(params: AccessDefaultSenderParams): () => void;

package/lib/sync/access-default-sender.js

@@ -0,0 +1,80 @@
+import { getP2PStore } from '@kubun/store-p2p';
+import { signAccessDefaultRemove, signAccessDefaultSet } from '../groups/access-default-token.js';
+/**
+ * Subscribe to the engine's access-default events and replicate each rule to
+ * every MLS group the local peer belongs to. A model default is owner-global,
+ * not group-scoped: any co-member evaluating the owner's documents needs the
+ * rule, and the receiver's sender-bound apply keeps a forged owner out. The
+ * fan-out is a single tiny frame per group, so no scope resolution is needed.
+ *
+ * Returns a combined unsubscribe function for both listeners.
+ */ export function wireAccessDefaultSender(params) {
+    const broadcastToOwnGroups = async (message)=>{
+        const p2pStore = await getP2PStore(params.db);
+        const groups = await p2pStore.getGroupsForMember(params.identity.id);
+        // Distinct groups over distinct hub lanes with nothing shared between them,
+        // so the fan-out runs concurrently: in sequence one slow lane delays every
+        // group behind it.
+        await Promise.all(groups.map((group)=>params.scheduleBroadcast(group.id, message)));
+    };
+    const unsubscribeSet = params.eventBus.on('engine:access-default:set', async (event)=>{
+        try {
+            const auth = await signAccessDefaultSet(params.identity, {
+                modelID: event.modelID,
+                permissionType: event.permissionType,
+                rule: {
+                    level: event.accessLevel,
+                    allowedDIDs: event.allowedDIDs,
+                    allowedCircles: event.allowedCircles,
+                    allowedGroups: event.allowedGroups
+                },
+                hlc: event.hlc
+            });
+            await broadcastToOwnGroups({
+                type: 'access-default:set',
+                modelID: event.modelID,
+                permissionType: event.permissionType,
+                rule: {
+                    level: event.accessLevel,
+                    allowedDIDs: event.allowedDIDs,
+                    allowedCircles: event.allowedCircles,
+                    allowedGroups: event.allowedGroups
+                },
+                ownerDID: event.ownerDID,
+                hlc: event.hlc,
+                auth
+            });
+        } catch (error) {
+            params.logger?.warn('access-default-sender set handler failed', {
+                modelID: event.modelID,
+                error: String(error)
+            });
+        }
+    });
+    const unsubscribeRemove = params.eventBus.on('engine:access-default:removed', async (event)=>{
+        try {
+            const auth = await signAccessDefaultRemove(params.identity, {
+                modelID: event.modelID,
+                permissionTypes: event.permissionTypes,
+                hlc: event.hlc
+            });
+            await broadcastToOwnGroups({
+                type: 'access-default:remove',
+                modelID: event.modelID,
+                permissionTypes: event.permissionTypes,
+                ownerDID: event.ownerDID,
+                hlc: event.hlc,
+                auth
+            });
+        } catch (error) {
+            params.logger?.warn('access-default-sender remove handler failed', {
+                modelID: event.modelID,
+                error: String(error)
+            });
+        }
+    });
+    return ()=>{
+        unsubscribeSet();
+        unsubscribeRemove();
+    };
+}

package/lib/sync/authorize.d.ts

@@ -1,4 +1,5 @@
 import { type VerifyTokenHook } from '@kokuin/capability';
+import type { StoredAccessRule } from '@kubun/store-graph';
 /**
  * Check if delegation tokens grant the viewer read access to a user's documents.
  *
@@ -11,15 +12,68 @@ import { type VerifyTokenHook } from '@kokuin/capability';
  * @returns true if any token grants read access
  */
 export declare function checkSyncDelegation(viewerDID: string, ownerDID: string, delegationTokens: Array<string>, revocationChecker?: VerifyTokenHook): Promise<boolean>;
+/**
+ * Resolver for circle-granted sync scopes. All reads run against the SERVING
+ * device's own state: the owner's tier-2 read default, the requester's circle
+ * membership, and the requester's group membership. The methods are dumb store
+ * reads — the authorization rule combining them lives in {@link authorizeScope}
+ * so implementations cannot drift on the security-critical conjunction.
+ */
+export type CircleReadGrantResolver = {
+    /** The owner's tier-2 read default for the model, or `null` if none exists. */
+    getUserModelReadDefault(ownerDID: string, modelID: string): Promise<StoredAccessRule | null>;
+    /**
+     * Which of `circleIDs` the viewer reaches, each with the group it belongs to.
+     * An unknown or tombstoned circle is absent, so the gate fails closed on it.
+     *
+     * Batched rather than per-circle so the rule below costs a fixed number of
+     * reads instead of one per named circle — and the group arrives with the id,
+     * which keeps the tombstone filter that decides "unknown circle" in one place
+     * instead of two reads that could disagree.
+     */
+    listAccessibleCircles(viewerDID: string, circleIDs: Array<string>): Promise<Array<{
+        id: string;
+        groupID: string;
+    }>>;
+    /**
+     * Which of `groupIDs` the viewer is a member of, per the serving device's own
+     * membership view (rows grown only from local ops and verified MLS commits).
+     */
+    listMemberGroupIDs(viewerDID: string, groupIDs: Array<string>): Promise<Array<string>>;
+};
 export type AuthorizeScopeParams = {
     viewerDID: string;
     ownerDID: string;
+    modelID: string;
     delegationTokens: Array<string>;
     revocationChecker?: VerifyTokenHook;
+    /**
+     * Optional resolver enabling owner-granted read. When set, a scope the owner
+     * and delegation arms reject is still accepted if the owner's tier-2 read
+     * default for the model is `anyone`, or is `restricted` and names a circle the
+     * viewer belongs to. Only an explicit owner grant widens: the server default is
+     * never consulted, so a model with no tier-2 read default stays owner/
+     * delegation only. Omitted — owner + delegation only, unchanged.
+     */
+    circleReadGrant?: CircleReadGrantResolver;
 };
 /**
- * Authorize a single sync scope: the viewer must be the owner, or hold a
- * delegation token granting read access to the owner's documents. Shared by
- * negotiate and merkle-sync so the two access gates cannot drift apart.
+ * Authorize a single sync scope: the viewer must be the owner, hold a delegation
+ * token granting read access to the owner's documents, or — when a
+ * {@link CircleReadGrantResolver} is supplied — be reached by the owner's tier-2
+ * read default for the model, either because that default is `anyone` or because
+ * the viewer is a member of a circle it names AND a member of that circle's
+ * group per the serving device's own view. Shared by negotiate and merkle-sync
+ * so the two access gates cannot drift apart. Fail-closed: any arm that is not
+ * satisfiable denies.
+ *
+ * The group-membership conjunct is that half of the open-access definition
+ * (`explicitMember OR (open AND groupMember)`): for an open circle
+ * `isMemberOfAnyCircle` already implies it, so the outer check is
+ * redundant-but-consistent; for the explicit arm it is a data-plane backstop.
+ * The circle roster is a projection of admin-signed ledger entries, while the
+ * serving device's group-membership rows grow only from its own ops and verified
+ * MLS commits — so even a polluted circle projection cannot open the data plane
+ * without a matching local row. Unknown circle or unresolvable group → deny.
  */
 export declare function authorizeScope(params: AuthorizeScopeParams): Promise<boolean>;

package/lib/sync/authorize.js

@@ -62,12 +62,53 @@ import { checkCapability } from '@kokuin/capability';
     return false;
 }
 /**
- * Authorize a single sync scope: the viewer must be the owner, or hold a
- * delegation token granting read access to the owner's documents. Shared by
- * negotiate and merkle-sync so the two access gates cannot drift apart.
+ * Authorize a single sync scope: the viewer must be the owner, hold a delegation
+ * token granting read access to the owner's documents, or — when a
+ * {@link CircleReadGrantResolver} is supplied — be reached by the owner's tier-2
+ * read default for the model, either because that default is `anyone` or because
+ * the viewer is a member of a circle it names AND a member of that circle's
+ * group per the serving device's own view. Shared by negotiate and merkle-sync
+ * so the two access gates cannot drift apart. Fail-closed: any arm that is not
+ * satisfiable denies.
+ *
+ * The group-membership conjunct is that half of the open-access definition
+ * (`explicitMember OR (open AND groupMember)`): for an open circle
+ * `isMemberOfAnyCircle` already implies it, so the outer check is
+ * redundant-but-consistent; for the explicit arm it is a data-plane backstop.
+ * The circle roster is a projection of admin-signed ledger entries, while the
+ * serving device's group-membership rows grow only from its own ops and verified
+ * MLS commits — so even a polluted circle projection cannot open the data plane
+ * without a matching local row. Unknown circle or unresolvable group → deny.
  */ export async function authorizeScope(params) {
     if (params.viewerDID === params.ownerDID) {
         return true;
     }
-    return checkSyncDelegation(params.viewerDID, params.ownerDID, params.delegationTokens, params.revocationChecker);
+    if (await checkSyncDelegation(params.viewerDID, params.ownerDID, params.delegationTokens, params.revocationChecker)) {
+        return true;
+    }
+    if (params.circleReadGrant != null) {
+        const grant = params.circleReadGrant;
+        const rule = await grant.getUserModelReadDefault(params.ownerDID, params.modelID);
+        // Reached only through a rule the owner actually stored: a `null` rule means
+        // the owner declared nothing, and the server default must never stand in for
+        // a declaration — a device whose default flipped would otherwise open every
+        // model on it.
+        if (rule != null && rule.level === 'anyone') {
+            return true;
+        }
+        if (rule != null && rule.level === 'restricted' && rule.allowedCircles != null && rule.allowedCircles.length > 0) {
+            // Per-circle conjunction: both checks must hold for the SAME circle, so a
+            // membership in one granted circle can never combine with membership in an
+            // unrelated circle's group. The reads are batched but the conjunction is
+            // evaluated here, per circle, so no store implementation decides it.
+            const accessible = await grant.listAccessibleCircles(params.viewerDID, rule.allowedCircles);
+            if (accessible.length > 0) {
+                const memberGroupIDs = new Set(await grant.listMemberGroupIDs(params.viewerDID, Array.from(new Set(accessible.map((circle)=>circle.groupID)))));
+                if (accessible.some((circle)=>memberGroupIDs.has(circle.groupID))) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
 }

package/lib/sync/broadcast-queue.d.ts

@@ -30,7 +30,7 @@ export type BroadcastQueue = {
      * Enqueue a single mutation entry for the given target group, attributed to
      * `senderPeerDID`. May trigger an immediate flush if a threshold is reached.
      */
-    enqueue(targetGroupID: string, entry: MutationApplyEntry, senderPeerDID: string): void;
+    enqueue(targetGroupID: string, entry: MutationApplyEntry, senderPeerDID: string | undefined): void;
     /**
      * Cancel all pending timers and synchronously flush remaining entries
      * via `scheduleBroadcast`. Safe to call multiple times.
@@ -52,8 +52,7 @@ export type BroadcastQueue = {
  * Sender-DID consistency: the queue tracks the `senderPeerDID` of the first
  * entry in each batch. If a later enqueue arrives with a different sender
  * (defensive — in practice senderPeerDID is constant per peer), the prior
- * batch is flushed and a fresh batch starts. This preserves the invariant
- * that every flushed `mutation:apply` message carries a single coherent
- * `senderPeerDID`.
+ * batch is flushed and a fresh batch starts, so every flushed message carries
+ * a single coherent `senderPeerDID`.
  */
 export declare function createBroadcastQueue(params: BroadcastQueueParams): BroadcastQueue;

package/lib/sync/broadcast-queue.js

@@ -19,9 +19,8 @@ export const DEFAULT_BROADCAST_BATCH_CONFIG = {
  * Sender-DID consistency: the queue tracks the `senderPeerDID` of the first
  * entry in each batch. If a later enqueue arrives with a different sender
  * (defensive — in practice senderPeerDID is constant per peer), the prior
- * batch is flushed and a fresh batch starts. This preserves the invariant
- * that every flushed `mutation:apply` message carries a single coherent
- * `senderPeerDID`.
+ * batch is flushed and a fresh batch starts, so every flushed message carries
+ * a single coherent `senderPeerDID`.
  */ export function createBroadcastQueue(params) {
     const { config, scheduleBroadcast, logger } = params;
     const queues = new Map();

package/lib/sync/catalog-scope.d.ts

@@ -1,17 +1,18 @@
-import type { KubunDB } from '@kubun/db';
+import type { StoreProvider } from '@kubun/db';
 export type CatalogSyncScope = {
     modelIDs: Array<string>;
     owners: Array<string> | undefined;
-    requiredClusterIDs: Array<string>;
-    missingClusterIDs: Array<string>;
 };
 /**
  * Resolve catalog criteria to sync-compatible scopes.
  *
  * Takes catalog IDs, resolves their criteria, and returns:
- * - modelIDs: union of all model filters from all catalogs
+ * - modelIDs: union of all model filters from all catalogs, with an omitted
+ *   filter expanded to every model this device has deployed
  * - owners: union of all owner filters (explicit + circle members)
- * - requiredClusterIDs: cluster IDs for all required models
- * - missingClusterIDs: cluster IDs for models not in knownModelIDs
+ *
+ * Which of those models the requester lacks is NOT decided here: the negotiate
+ * handler answers that over the scopes it accepted, which is the only set that
+ * production actually sends.
  */
-export declare function resolveCatalogSyncScopes(db: KubunDB, catalogIDs: Array<string>, knownModelIDs?: Array<string>): Promise<CatalogSyncScope>;
+export declare function resolveCatalogSyncScopes(db: StoreProvider, catalogIDs: Array<string>): Promise<CatalogSyncScope>;

package/lib/sync/catalog-scope.js

@@ -4,11 +4,14 @@ import { getP2PStore } from '@kubun/store-p2p';
  * Resolve catalog criteria to sync-compatible scopes.
  *
  * Takes catalog IDs, resolves their criteria, and returns:
- * - modelIDs: union of all model filters from all catalogs
+ * - modelIDs: union of all model filters from all catalogs, with an omitted
+ *   filter expanded to every model this device has deployed
  * - owners: union of all owner filters (explicit + circle members)
- * - requiredClusterIDs: cluster IDs for all required models
- * - missingClusterIDs: cluster IDs for models not in knownModelIDs
- */ export async function resolveCatalogSyncScopes(db, catalogIDs, knownModelIDs) {
+ *
+ * Which of those models the requester lacks is NOT decided here: the negotiate
+ * handler answers that over the scopes it accepted, which is the only set that
+ * production actually sends.
+ */ export async function resolveCatalogSyncScopes(db, catalogIDs) {
     const [graphStore, p2pStore] = await Promise.all([
         getGraphStore(db),
         getP2PStore(db)
@@ -16,53 +19,66 @@ import { getP2PStore } from '@kubun/store-p2p';
     const allModelIDs = new Set();
     const allOwners = new Set();
     let hasOwnerFilter = false;
+    // Catalogs are advisory: only a locally-activated catalog scopes sync. A known
+    // (not-activated) or unknown catalog contributes nothing. Read as one batch —
+    // the loop below needs every record anyway, and `resolveCatalogScope` reads the
+    // row again for itself, so a per-id read here would be the second of three.
+    const catalogs = await graphStore.getCatalogs(catalogIDs);
+    const circleIDs = new Set();
+    // Read once, and only if some catalog omits its model filter.
+    let deployedModelIDs;
+    const getDeployedModelIDs = async ()=>{
+        deployedModelIDs ??= await graphStore.listDocumentModelIDs();
+        return deployedModelIDs;
+    };
     for (const catalogID of catalogIDs){
-        const scope = await graphStore.resolveCatalogScope(catalogID);
-        if (scope.models != null) {
-            for (const m of scope.models){
-                allModelIDs.add(m);
-            }
+        const catalog = catalogs.get(catalogID);
+        if (catalog == null || catalog.active !== 1) {
+            continue;
         }
+        const scope = await graphStore.resolveCatalogScope(catalogID);
+        const criteria = catalog.filter_criteria;
+        const catalogCircles = criteria.circles != null && criteria.circles.length > 0 ? criteria.circles : undefined;
         if (scope.owners != null) {
             hasOwnerFilter = true;
             for (const o of scope.owners){
                 allOwners.add(o);
             }
         }
-        // Resolve circle-based owners via p2p store
-        const catalog = await graphStore.getCatalog(catalogID);
-        if (catalog != null) {
-            const criteria = catalog.filter_criteria;
-            if (criteria.circles != null && criteria.circles.length > 0) {
-                hasOwnerFilter = true;
-                for (const circleID of criteria.circles){
-                    const members = await p2pStore.listCircleMembers(circleID);
-                    for (const member of members){
-                        allOwners.add(member.member_did);
-                    }
-                }
+        if (catalogCircles != null) {
+            hasOwnerFilter = true;
+            for (const circleID of catalogCircles){
+                circleIDs.add(circleID);
+            }
+        }
+        if (scope.models != null) {
+            for (const m of scope.models){
+                allModelIDs.add(m);
+            }
+        } else if (scope.owners != null || catalogCircles != null) {
+            // "Omitted means no constraint" is only true where a dimension can be
+            // enumerated: expanding models at resolution time also covers a model
+            // deployed after the catalog was written. Owners stay anchorless on
+            // purpose — "everyone" is not a set — so the expansion is gated on the
+            // catalog naming owners or circles. Without that gate a criteria-less
+            // catalog would widen the SERVING side, where an absent owner filter
+            // means every distinct owner of every model.
+            for (const m of (await getDeployedModelIDs())){
+                allModelIDs.add(m);
             }
         }
     }
-    const modelIDs = Array.from(allModelIDs);
-    const owners = hasOwnerFilter ? Array.from(allOwners) : undefined;
-    // Resolve clusters for all models in a single pass
-    const knownSet = new Set(knownModelIDs ?? []);
-    const requiredClusterIDs = new Set();
-    const missingClusterIDs = new Set();
-    await Promise.all(modelIDs.map(async (modelID)=>{
-        const clusterID = await graphStore.getClusterForModel(modelID);
-        if (clusterID != null) {
-            requiredClusterIDs.add(clusterID);
-            if (!knownSet.has(modelID)) {
-                missingClusterIDs.add(clusterID);
-            }
+    // Resolve circle-based owners via the p2p store, every catalog's circles at
+    // once. `listOwnersForCircles` unions `listCircleOwners` over the set: explicit
+    // members plus, for an open circle, the whole group's members — the pull-owner
+    // set mirrors the open-access predicate.
+    if (circleIDs.size > 0) {
+        for (const owner of (await p2pStore.listOwnersForCircles(Array.from(circleIDs)))){
+            allOwners.add(owner);
         }
-    }));
+    }
     return {
-        modelIDs,
-        owners,
-        requiredClusterIDs: Array.from(requiredClusterIDs),
-        missingClusterIDs: Array.from(missingClusterIDs)
+        modelIDs: Array.from(allModelIDs),
+        owners: hasOwnerFilter ? Array.from(allOwners) : undefined
     };
 }

package/lib/sync/errors.d.ts

@@ -9,4 +9,13 @@ export declare class SyncAccessDeniedError extends Error {
     constructor(reason: string, message?: string);
     get code(): 'KB08';
     get reason(): string;
+    /**
+     * Carried alongside the code when the handler boundary translates this into a
+     * wire error, so a caller can tell the denials apart without parsing the
+     * message. The reasons are a fixed categorical set and disclose nothing the
+     * caller did not supply.
+     */
+    get data(): {
+        reason: string;
+    };
 }

package/lib/sync/errors.js

@@ -16,4 +16,14 @@
     get reason() {
         return this.#reason;
     }
+    /**
+   * Carried alongside the code when the handler boundary translates this into a
+   * wire error, so a caller can tell the denials apart without parsing the
+   * message. The reasons are a fixed categorical set and disclose nothing the
+   * caller did not supply.
+   */ get data() {
+        return {
+            reason: this.#reason
+        };
+    }
 }

package/lib/sync/forwarder.d.ts

@@ -71,27 +71,21 @@ export type EvaluateAndForwardResult = {
     skipped: number;
 };
 /**
- * Evaluate forwarding candidates for a single mutation:apply entry the local
- * peer has just applied, and forward to each surviving candidate group via
- * `scheduleBroadcast`.
+ * Evaluate forwarding candidates for one just-applied `mutation:apply` entry and
+ * forward to each survivor via `scheduleBroadcast`.
  *
- * Pipeline (per candidate group):
- * 1. Source group exclusion — `sourceGroupID` is filtered out before any check.
- * 2. Access gate — `computeBroadcastScopes` against the post-apply rule.
- * 3. Catalog gate — at least one circle the local peer belongs to in the
- *    candidate group must have a catalog whose `filter_criteria` matches the
- *    document.
- * 4. Filter (when `forwarding` is a function) — narrows further.
- * 5. Dedup — `recordBroadcast` BEFORE schedule. False return → skip silently.
- * 6. Schedule — single-entry `mutation:apply` broadcast with
- *    `senderPeerDID = selfDID`.
+ * Gates per candidate group, in order: the source group is excluded first;
+ * `computeBroadcastScopes` against the post-apply rule; a circle the local peer
+ * belongs to in that group must hold a catalog whose `filter_criteria` matches
+ * the document; then the caller's `forwarding` filter when it is a function.
+ * `recordBroadcast` runs BEFORE the schedule and a false return skips silently.
  *
- * Per-candidate errors are isolated: one bad candidate logs + continues; the
- * rest still get evaluated. The function never throws.
+ * Per-candidate errors are isolated — one bad candidate logs and the rest are
+ * still evaluated — and the function never throws.
  *
- * Routing decision: each candidate gets its OWN single-entry broadcast (no
- * batch queue). The queue's `senderPeerDID`-mismatch flush conflicts
- * with mixing locally-authored and forwarded entries in one batch — deferring
- * batched-forwarding keeps the receive path simple.
+ * Each candidate gets its OWN single-entry broadcast, `senderPeerDID = selfDID`,
+ * rather than going through the batch queue, whose `senderPeerDID`-mismatch
+ * flush conflicts with mixing locally-authored and forwarded entries in one
+ * batch.
  */
 export declare function evaluateAndForward(params: EvaluateAndForwardParams): Promise<EvaluateAndForwardResult>;

package/lib/sync/forwarder.js

@@ -10,28 +10,22 @@ export function rethrowIfProgrammerError(error) {
     }
 }
 /**
- * Evaluate forwarding candidates for a single mutation:apply entry the local
- * peer has just applied, and forward to each surviving candidate group via
- * `scheduleBroadcast`.
+ * Evaluate forwarding candidates for one just-applied `mutation:apply` entry and
+ * forward to each survivor via `scheduleBroadcast`.
  *
- * Pipeline (per candidate group):
- * 1. Source group exclusion — `sourceGroupID` is filtered out before any check.
- * 2. Access gate — `computeBroadcastScopes` against the post-apply rule.
- * 3. Catalog gate — at least one circle the local peer belongs to in the
- *    candidate group must have a catalog whose `filter_criteria` matches the
- *    document.
- * 4. Filter (when `forwarding` is a function) — narrows further.
- * 5. Dedup — `recordBroadcast` BEFORE schedule. False return → skip silently.
- * 6. Schedule — single-entry `mutation:apply` broadcast with
- *    `senderPeerDID = selfDID`.
+ * Gates per candidate group, in order: the source group is excluded first;
+ * `computeBroadcastScopes` against the post-apply rule; a circle the local peer
+ * belongs to in that group must hold a catalog whose `filter_criteria` matches
+ * the document; then the caller's `forwarding` filter when it is a function.
+ * `recordBroadcast` runs BEFORE the schedule and a false return skips silently.
  *
- * Per-candidate errors are isolated: one bad candidate logs + continues; the
- * rest still get evaluated. The function never throws.
+ * Per-candidate errors are isolated — one bad candidate logs and the rest are
+ * still evaluated — and the function never throws.
  *
- * Routing decision: each candidate gets its OWN single-entry broadcast (no
- * batch queue). The queue's `senderPeerDID`-mismatch flush conflicts
- * with mixing locally-authored and forwarded entries in one batch — deferring
- * batched-forwarding keeps the receive path simple.
+ * Each candidate gets its OWN single-entry broadcast, `senderPeerDID = selfDID`,
+ * rather than going through the batch queue, whose `senderPeerDID`-mismatch
+ * flush conflicts with mixing locally-authored and forwarded entries in one
+ * batch.
  */ export async function evaluateAndForward(params) {
     // 1. Zero-overhead short-circuit when forwarding is disabled.
     if (params.forwarding === false) {